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.
| model | string | ID modelu, np. mistral/mistral-ocr, lub auto. |
| file_url | string | Publiczny adres URL pliku PDF lub obrazu. Użyj jednego z parametrów: file_url, file_base64 lub file_id. |
| file_base64 | string | Plik zakodowany w base64, do 20 MB. |
| file_id | string | ID zwrócone przez POST /v1/files, przeznaczone dla większych plików. |
| format | string | markdown (domyślny), json, text, html, csv, docx lub xlsx. |
| pages | string | Zakres stron, na przykład 1-5,8. Domyślnie przetwarzane są wszystkie strony. |
| fallbacks | string[] | Lista ID modeli do sprawdzenia po kolei, jeśli pierwszy model zwróci błąd. |
| route | string | Dla modelu auto: quality (domyślny), cheapest lub fastest. |
| filename | string | Opcjonalna nazwa wyświetlana w dzienniku aktywności. |
Pozostałe punkty końcowe:
GET /v1/modelszwraca listę wszystkich modeli, ich ceny oraz dostępność. Klucz nie jest wymagany.POST /v1/filesprzyjmuje żądanie multipart z polemfilei zwracafile_idważne przez 24 godziny.GET /v1/requests/:idzwraca wcześniejszy wynik. Dodaj?format=z dowolnym formatem wyjściowym, aby pobrać go w innej postaci.GET /v1/creditszwraca stan Twojego konta oraz zużycie dla danego klucza.POST /v1/keys/temporaryzwraca 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.
{"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.
{"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
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 mcpWersja tej strony w formacie czytelnym dla maszyn znajduje się pod adresem /llms.txt.