OCRRouter

API-documentatie

Handleidingen voor de kernconcepten. Elk eindpunt en elke parameter staat in de API-referentie.

Quickstart

Maak een API-sleutel aan en verstuur vervolgens een bestand. Nieuwe accounts beginnen met 50 gratis credits.

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"
  }'

Request

POST https://api.ocrrouter.ai/v1/ocr met een JSON-body en een Authorization: Bearer-header.

modelstringEen model-ID zoals mistral/mistral-ocr, of auto.
file_urlstringPublieke URL van een PDF of afbeelding. Gebruik file_url, file_base64 of file_id.
file_base64stringHet bestand als base64, tot maximaal 20 MB.
file_idstringID geretourneerd door POST /v1/files, voor grotere bestanden.
formatstringmarkdown (standaard), json, text, html, csv, docx of xlsx.
pagesstringPaginabereik, bijvoorbeeld 1-5,8. Standaard alle pagina's.
fallbacksstring[]Model-ID's om op volgorde te proberen als het eerste model faalt.
routestringBij model auto: quality (standaard), cheapest of fastest.
filenamestringOptionele naam die in je activiteitenlogboek wordt getoond.

Andere eindpunten:

  • GET /v1/models toont elk model, de prijs en de beschikbaarheid. Geen sleutel nodig.
  • POST /v1/files accepteert een multipart-upload met een file-veld en retourneert een file_id die 24 uur geldig is.
  • GET /v1/requests/:id retourneert een eerder resultaat. Voeg ?format= toe met een willekeurig uitvoerformaat om het in een ander formaat op te halen.
  • GET /v1/credits retourneert je saldo en het verbruik van deze sleutel.
  • POST /v1/keys/temporary retourneert een tijdelijke sleutel met 50 credits. Zonder registratie, één per dag.

Uitvoerformaten

markdown

Het volledige document als Markdown. Tabellen zijn GitHub-flavored tabellen, formules staan tussen $...$ en pagina's worden gescheiden door <!-- page:N -->.

json

Dezelfde structuur voor elk model: pagina's, elk met getypeerde blokken. Bloktypen zijn heading, paragraph, list, table, formula, image, header en footer. bbox, confidence en paginagrootte zijn null als het model deze niet levert, wat geldt voor de huidige live modellen.

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

De Markdown-respons plus een output-object met een bestand: format, filename, mime_type, encoding en data. text, html en csv zijn UTF-8-strings (encoding: "utf8"); docx en xlsx zijn base64 (encoding: "base64"). csv en xlsx bevatten de tabellen (één tabblad per tabel), of de tekstregels als er geen tabellen zijn. txt wordt geaccepteerd als alternatieve naam voor 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}}

Routering en fallbacks

Stel model in op auto en wij kiezen een model voor elk document. Gebruik route om aan te geven wat belangrijk is: cheapest, fastest of quality.

Voeg fallbacks toe om bestand te blijven tegen storingen. Als het eerste model een fout geeft of rate-limited is, wordt het volgende uitgevoerd. De respons vermeldt welk model heeft geantwoord, en je betaalt alleen voor dat model.

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

Credits

Elk model heeft een prijs in credits per pagina. Voor $ 1 koop je 1,000 credits en ze vervallen nooit. Elke respons bevat usage.credits.

  • Mislukte en lege resultaten zijn gratis.
  • Hetzelfde bestand opnieuw naar hetzelfde model sturen wordt gratis vanuit de cache geserveerd.
  • Elke API-sleutel kan een eigen creditlimiet hebben.

Foutmeldingen

400Het request is ongeldig of het bestandstype wordt niet ondersteund.
401De API-sleutel ontbreekt of is ingetrokken.
402Onvoldoende credits, of de sleutel heeft de creditlimiet bereikt.
413Het bestand is groter dan de limiet voor dit model.
429Te veel requests. Probeer het opnieuw na de tijd in de Retry-After-header.
502Elk model in de fallback-keten is mislukt. Er worden geen kosten in rekening gebracht.
503Het opgevraagde model is nog niet gekoppeld.

Agents, MCP en CLI

Coding-agents kunnen OCRRouter gebruiken zonder registratiestap. De CLI en de MCP-server vragen bij het eerste gebruik een tijdelijke sleutel met 50 credits aan en slaan deze op in ~/.ocrrouter/config.json. Stel OCRROUTER_API_KEY in om je eigen sleutel te gebruiken.

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

Een machineleesbare samenvatting van deze pagina is te vinden op /llms.txt.

Vragen