OCRRouter

API-Dokumentation

Leitfäden für die wichtigsten Konzepte. Jeder Endpunkt und Parameter ist in der API-Referenz beschrieben.

Quickstart

Erstelle einen API-Schlüssel und sende eine Datei. Neue Accounts starten mit 50 kostenlosen 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 mit einem JSON-Body und einem Authorization: Bearer-Header.

modelstringEine Modell-ID wie mistral/mistral-ocr oder auto.
file_urlstringÖffentliche URL eines PDFs oder Bildes. Verwende file_url, file_base64 oder file_id.
file_base64stringDie Datei als Base64, bis zu 20 MB.
file_idstringID von POST /v1/files für größere Dateien.
formatstringmarkdown (Standard), json, text, html, csv, docx oder xlsx.
pagesstringSeitenbereich, zum Beispiel 1-5,8. Standardmäßig alle Seiten.
fallbacksstring[]Modell-IDs, die nacheinander versucht werden, falls das erste Modell fehlschlägt.
routestringBei model auto: quality (Standard), cheapest oder fastest.
filenamestringOptionaler Name, der in deinem Aktivitätsprotokoll angezeigt wird.

Weitere Endpunkte:

  • GET /v1/models listet alle Modelle, deren Preise und Verfügbarkeit auf. Kein Schlüssel erforderlich.
  • POST /v1/files akzeptiert einen Multipart-Upload mit einem file-Feld und gibt eine file_id zurück, die 24 Stunden gültig ist.
  • GET /v1/requests/:id ruft ein früheres Ergebnis ab. Füge ?format= mit einem beliebigen Ausgabeformat hinzu, um es in einem anderen Format zu erhalten.
  • GET /v1/credits gibt dein Guthaben und den Verbrauch dieses Schlüssels zurück.
  • POST /v1/keys/temporary gibt einen temporären Schlüssel mit 50 Credits zurück. Ohne Registrierung, einer pro Tag.

Ausgabeformate

markdown

Das gesamte Dokument als Markdown. Tabellen sind GitHub-Flavored Tables, Formeln werden in $...$ gefasst und Seiten werden durch <!-- page:N --> getrennt.

json

Die gleiche Struktur für jedes Modell: Seiten mit jeweils typisierten Blöcken. Blocktypen sind heading, paragraph, list, table, formula, image, header und footer. bbox, confidence und Seitengröße sind null, wenn das Modell sie nicht bereitstellt, was bei den aktuell verfügbaren Modellen der Fall ist.

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

Die Markdown-Antwort plus ein output-Objekt, das eine Datei enthält: format, filename, mime_type, encoding und data. text, html und csv sind UTF-8-Strings (encoding: "utf8"); docx und xlsx sind Base64 (encoding: "base64"). csv und xlsx enthalten die Tabellen (ein Tabellenblatt pro Tabelle) oder die Textzeilen, falls keine Tabellen vorhanden sind. txt wird als Alias für text akzeptiert.

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 und Fallbacks

Setze model auf auto, und wir wählen für jedes Dokument das passende Modell aus. Verwende route, um die Priorität festzulegen: cheapest, fastest oder quality.

Füge fallbacks hinzu, um Ausfälle abzufedern. Schlägt das erste Modell fehl oder läuft in ein Rate-Limit, springt das nächste an. Die Antwort zeigt, welches Modell geantwortet hat, und du zahlst nur für dieses.

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

Credits

Jedes Modell hat einen Preis in Credits pro Seite. 1 $ entspricht 1,000 Credits, die nie verfallen. Jede Antwort enthält usage.credits.

  • Fehlgeschlagene und leere Ergebnisse sind kostenlos.
  • Wird dieselbe Datei erneut an dasselbe Modell gesendet, erfolgt die Auslieferung kostenlos aus dem Cache.
  • Jeder API-Schlüssel kann ein eigenes Credit-Limit haben.

Fehler

400Der Request ist fehlerhaft oder der Dateityp wird nicht unterstützt.
401Der API-Schlüssel fehlt oder wurde widerrufen.
402Nicht genügend Credits oder der Schlüssel hat sein Limit erreicht.
413Die Datei überschreitet das Limit für dieses Modell.
429Zu viele Requests. Wiederhole die Anfrage nach Ablauf der Zeit im Retry-After-Header.
502Alle Modelle in der Fallback-Kette sind fehlgeschlagen. Es entstehen keine Kosten.
503Das angeforderte Modell ist noch nicht angebunden.

Agenten, MCP und CLI

Coding-Agenten können OCRRouter ohne vorherige Registrierung nutzen. Das CLI und der MCP-Server fordern bei der ersten Verwendung einen temporären Schlüssel mit 50 Credits an und speichern ihn in ~/.ocrrouter/config.json. Setze OCRROUTER_API_KEY, um deinen eigenen Schlüssel zu verwenden.

# CLI
npx ocrrouter invoice.pdf --format markdown

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

Eine maschinenlesbare Zusammenfassung dieser Seite findest du unter /llms.txt.

Fragen