OCRRouter

Dokumentacja API

Przewodniki po kluczowych funkcjach. Wszystkie punkty końcowe i parametry znajdziesz w dokumentacji technicznej API.

Szybki start

Utwórz klucz API, a następnie wyślij plik. Nowe konta zaczynają z 50 darmowymi kredytami.

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

Zapytanie

POST https://api.ocrrouter.ai/v1/ocr z ciałem zapytania JSON i nagłówkiem Authorization: Bearer.

modelstringID modelu, np. mistral/mistral-ocr, lub auto.
file_urlstringPubliczny adres URL pliku PDF lub obrazu. Użyj jednego z parametrów: file_url, file_base64 lub file_id.
file_base64stringPlik zakodowany w base64, do 20 MB.
file_idstringID zwrócone przez POST /v1/files, przeznaczone dla większych plików.
formatstringmarkdown (domyślny), json, text, html, csv, docx lub xlsx.
pagesstringZakres stron, na przykład 1-5,8. Domyślnie przetwarzane są wszystkie strony.
fallbacksstring[]Lista ID modeli do sprawdzenia po kolei, jeśli pierwszy model zwróci błąd.
routestringDla modelu auto: quality (domyślny), cheapest lub fastest.
filenamestringOpcjonalna nazwa wyświetlana w dzienniku aktywności.

Pozostałe punkty końcowe:

  • GET /v1/models zwraca listę wszystkich modeli, ich ceny oraz dostępność. Klucz nie jest wymagany.
  • POST /v1/files przyjmuje żądanie multipart z polem file i zwraca file_id ważne przez 24 godziny.
  • GET /v1/requests/:id zwraca wcześniejszy wynik. Dodaj ?format= z dowolnym formatem wyjściowym, aby pobrać go w innej postaci.
  • GET /v1/credits zwraca stan Twojego konta oraz zużycie dla danego klucza.
  • POST /v1/keys/temporary zwraca klucz tymczasowy z 50 kredytami. Bez rejestracji, jeden dziennie.

Formaty wyjściowe

markdown

Cały dokument w formacie Markdown. Tabele w stylu GitHub Markdown, formuły ujęte w $...$, a strony rozdzielone przez <!-- page:N -->.

json

Ta sama struktura dla każdego modelu: strony z typowanymi blokami. Typy bloków to: heading, paragraph, list, table, formula, image, header oraz footer. Pola bbox, confidence oraz wymiary strony mają wartość null, jeśli model ich nie udostępnia, co dotyczy obecnie działających modeli.

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

Odpowiedź w Markdown uzupełniona o obiekt output zawierający plik: format, filename, mime_type, encoding oraz data. text, html i csv są ciągami UTF-8 (encoding: "utf8"); docx i xlsx są zakodowane w base64 (encoding: "base64"). csv i xlsx zawierają tabele (jeden arkusz na tabelę) lub linie tekstu, jeśli tabel brak. Wartość txt jest akceptowana jako zamiennik formatu 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 i modele rezerwowe

Ustaw model na auto, a my dobierzemy odpowiedni model dla każdego dokumentu. Użyj route, aby określić priorytet: cheapest, fastest lub quality.

Dodaj fallbacks, aby zachować ciągłość działania w razie awarii. Jeśli pierwszy model zwróci błąd lub przekroczy limit zapytań, uruchomi się kolejny. W odpowiedzi otrzymasz informację, który model przetworzył dokument, i zapłacisz tylko za ten jeden.

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

Kredyty

Każdy model ma określoną cenę w kredytach za stronę. 1 USD pozwala kupić 1,000 kredytów, które nigdy nie wygasają. Każda odpowiedź zawiera pole usage.credits.

  • Nieudane i puste wyniki są darmowe.
  • Wysłanie tego samego pliku do tego samego modelu jest serwowane z pamięci podręcznej bez dodatkowych opłat.
  • Każdy klucz API może mieć własny limit kredytów.

Błędy

400Nieprawidłowe żądanie lub nieobsługiwany format pliku.
401Brak klucza API lub klucz został unieważniony.
402Brak wystarczającej liczby kredytów lub klucz osiągnął limit.
413Plik przekracza limit dozwolony dla tego modelu.
429Zbyt wiele zapytań. Spróbuj ponownie po czasie podanym w nagłówku Retry-After.
502Wszystkie modele w łańcuchu rezerwowym zawiodły. Kredyty nie zostały pobrane.
503Wybrany model nie jest jeszcze podłączony.

Agenci, MCP i CLI

Agenci kodujący mogą korzystać z OCRRouter bez konieczności rejestracji. Narzędzie CLI oraz serwer MCP pobierają przy pierwszym użyciu klucz tymczasowy z 50 kredytami i zapisują go w ~/.ocrrouter/config.json. Ustaw zmienną OCRROUTER_API_KEY, aby korzystać z własnego klucza.

# CLI
npx ocrrouter invoice.pdf --format markdown

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

Wersja tej strony w formacie czytelnym dla maszyn znajduje się pod adresem /llms.txt.

Pytania