Guida rapida
Crea una chiave API, poi invia un file. I nuovi account partono con 50 crediti gratuiti.
curl https://api.ocrrouter.ai/v1/ocr \
-H "Authorization: Bearer $OCRROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"file_url": "https://example.com/invoice.pdf",
"format": "markdown"
}'Richiesta
POST https://api.ocrrouter.ai/v1/ocr con un corpo JSON e un header Authorization: Bearer.
| model | string | Un ID modello come mistral/mistral-ocr, oppure auto. |
| file_url | string | URL pubblico di un PDF o di un'immagine. Usa uno tra file_url, file_base64 o file_id. |
| file_base64 | string | Il file codificato in base64, fino a 20 MB. |
| file_id | string | ID restituito da POST /v1/files, per file più grandi. |
| format | string | markdown (predefinito), json, text, html, csv, docx o xlsx. |
| pages | string | Intervallo di pagine, ad esempio 1-5,8. L'impostazione predefinita include tutte le pagine. |
| fallbacks | string[] | ID dei modelli da provare, in ordine, se il primo modello fallisce. |
| route | string | Con model impostato su auto: quality (predefinito), cheapest o fastest. |
| filename | string | Nome facoltativo mostrato nel registro attività. |
Altri endpoint:
GET /v1/modelselenca tutti i modelli, il relativo prezzo e la disponibilità. Nessuna chiave richiesta.POST /v1/filesaccetta un caricamento multipart con un campofilee restituisce unfile_idvalido per 24 ore.GET /v1/requests/:idrestituisce un risultato precedente. Aggiungi?format=con qualsiasi formato di output per ottenerlo in un altro formato.GET /v1/creditsrestituisce il tuo saldo e l'utilizzo di questa chiave.POST /v1/keys/temporaryrestituisce una chiave temporanea con 50 crediti. Nessuna registrazione, una al giorno.
Formati di output
markdown
L'intero documento in formato Markdown. Le tabelle sono in formato GitHub Flavored Markdown, le formule sono racchiuse tra $...$ e le pagine sono separate da <!-- page:N -->.
json
La stessa struttura per ogni modello: pagine, ciascuna con blocchi tipizzati. I tipi di blocco sono heading, paragraph, list, table, formula, image, header e footer. bbox, confidence e dimensioni della pagina sono null quando il modello non li fornisce, come avviene per i modelli attualmente attivi.
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "json","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"pages": [{"index": 1,"width": null,"height": null,"blocks": [{"type": "heading","level": 1,"text": "Invoice INV-2041","bbox": null,"confidence": null},{"type": "paragraph","text": "Acme Supply Co.\n14 Harbour Street, Sydney NSW 2…","bbox": null,"confidence": null},{"type": "table","rows": [["Item", "Qty", "Unit price", "Amount"],["A4 paper, 5 reams", "4", "$24.00", "$96.00"]],"markdown": "| Item | Qty | Unit price | Amount |\n|---|---|-…","bbox": null,"confidence": null}]}],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}text, html, csv, docx, xlsx
La risposta in Markdown più un oggetto output contenente un file: format, filename, mime_type, encoding e data. text, html e csv sono stringhe UTF-8 (encoding: "utf8"); docx e xlsx sono in base64 (encoding: "base64"). csv e xlsx contengono le tabelle (un foglio per tabella), oppure le righe di testo quando non sono presenti tabelle. txt è accettato come alias di text.
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "docx","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"markdown": "<!-- page:1 -->\n# Invoice INV-2041\n…","pages": [{ "index": 1, "markdown": "# Invoice INV-2041\n…" }],"output": {"format": "docx","filename": "invoice.docx","mime_type": "application/vnd.openxmlformats-officedocument.w…","encoding": "base64","data": "UEsDBBQAAAAIA…"},"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}Routing e fallback
Imposta model su auto e sceglieremo noi il modello per ciascun documento. Usa route per indicare la tua priorità: cheapest, fastest o quality.
Aggiungi fallbacks per continuare a lavorare anche in caso di disservizi. Se il primo modello restituisce un errore o subisce un rate limit, viene eseguito il successivo. La risposta indica quale modello ha risposto e pagherai solo per quello.
{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}Crediti
Ogni modello ha un prezzo in crediti per pagina. Con 1 $ acquisti 1,000 crediti e non hanno scadenza. Ogni risposta include usage.credits.
- I risultati falliti e vuoti sono gratuiti.
- L'invio dello stesso file allo stesso modello viene servito dalla cache gratuitamente.
- Ogni chiave API può avere un proprio limite di crediti.
Errori
Agenti, MCP e CLI
Gli agenti di programmazione possono usare OCRRouter senza necessità di registrazione. La CLI e il server MCP richiedono una chiave temporanea con 50 crediti al primo utilizzo e la salvano in ~/.ocrrouter/config.json. Imposta OCRROUTER_API_KEY per utilizzare la tua chiave personale.
# CLI
npx ocrrouter invoice.pdf --format markdown
# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcpUn riassunto di questa pagina leggibile da macchina è disponibile su /llms.txt.