OCRRouter

Documentazione API

Guide per i concetti principali. Ogni endpoint e parametro è descritto nel riferimento API.

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.

modelstringUn ID modello come mistral/mistral-ocr, oppure auto.
file_urlstringURL pubblico di un PDF o di un'immagine. Usa uno tra file_url, file_base64 o file_id.
file_base64stringIl file codificato in base64, fino a 20 MB.
file_idstringID restituito da POST /v1/files, per file più grandi.
formatstringmarkdown (predefinito), json, text, html, csv, docx o xlsx.
pagesstringIntervallo di pagine, ad esempio 1-5,8. L'impostazione predefinita include tutte le pagine.
fallbacksstring[]ID dei modelli da provare, in ordine, se il primo modello fallisce.
routestringCon model impostato su auto: quality (predefinito), cheapest o fastest.
filenamestringNome facoltativo mostrato nel registro attività.

Altri endpoint:

  • GET /v1/models elenca tutti i modelli, il relativo prezzo e la disponibilità. Nessuna chiave richiesta.
  • POST /v1/files accetta un caricamento multipart con un campo file e restituisce un file_id valido per 24 ore.
  • GET /v1/requests/:id restituisce un risultato precedente. Aggiungi ?format= con qualsiasi formato di output per ottenerlo in un altro formato.
  • GET /v1/credits restituisce il tuo saldo e l'utilizzo di questa chiave.
  • POST /v1/keys/temporary restituisce 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.

200result
{"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.

200result
{"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

400La richiesta non è valida o il tipo di file non è supportato.
401La chiave API è mancante o revocata.
402Crediti insufficienti o la chiave ha raggiunto il proprio limite di spesa.
413Il file supera il limite consentito per questo modello.
429Troppe richieste. Riprova dopo il tempo indicato nell'header Retry-After.
502Tutti i modelli nella sequenza di fallback sono falliti. Non ti verrà addebitato alcun costo.
503Il modello richiesto non è ancora connesso.

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 mcp

Un riassunto di questa pagina leggibile da macchina è disponibile su /llms.txt.

Domande frequenti