API reference
Base URL https://api.ocrrouter.ai. Requests and responses are JSON. Send your key as a Bearer token.
POST/v1/ocr
Read a PDF or image and return Markdown, JSON or a file (text, html, csv, docx, xlsx). Waits for the result.
Body
modelstring- A model ID from GET /v1/models, or auto. Default auto.
file_urlstring- Public http(s) URL of the file. Send exactly one of file_url, file_base64, file_id.
file_base64string- The file as base64 (a data: URL prefix is accepted). Up to 20 MB.
file_idstring- ID returned by POST /v1/files.
filenamestring- Name shown in your activity log.
formatstring- markdown (default), json, text (alias txt), html, csv, docx or xlsx. The last five return the Markdown response plus an output object: { format, filename, mime_type, encoding, data }. text, html and csv come as UTF-8 strings (encoding utf8); docx and xlsx as base64 (encoding base64). csv and xlsx hold the tables, or the text lines when there are none.
pagesstring- Page range such as 1-5,8. Default all pages. PDF only.
fallbacksstring[]- Up to 5 model IDs to try, in order, if the first fails.
routestring- Used with model auto: quality (default), cheapest or fastest.
document_typestring- invoice, receipt, passport, id_card, bank_statement or menu. Adds a fields object with a fixed schema for that type, read from the OCR text by one extra model call, for 11 credits per document. Missing values are null, dates are YYYY-MM-DD, amounts are numbers. Passports also get mrz_valid (ICAO 9303 check digits). If extraction fails you still get the OCR result, fields is null, fields_error says why, and extraction is not charged.
Errors
- 400 invalid_request, unknown_model, unsupported_file, unreadable_pdf, invalid_pages, invalid_file_url, file_fetch_failed
- 401 missing_api_key, invalid_api_key
- 402 insufficient_credits, key_limit_reached
- 413 file_too_large, too_many_pages
- 429 rate_limited
- 502 all_models_failed
- 503 model_unavailable
curl https://api.ocrrouter.ai/v1/ocr \
-H "Authorization: Bearer $OCRROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"mistral/mistral-ocr","file_url":"https://example.com/invoice.pdf","format":"json"}'{"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}}{"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}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "invoice","markdown": "<!-- page:1 -->\n…","fields": {"invoice_number": "INV-2025-0142","supplier_name": "Acme GmbH","supplier_address": "Hauptstr. 1, 10115 Berlin","customer_name": "Globex Ltd","issue_date": "2025-03-01","due_date": "2025-03-31","currency": "EUR","subtotal": 1000,"tax": 190,"total": 1190,"line_items": [{"description": "Consulting, March","quantity": 10,"unit_price": 100,"amount": 1000}]},"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "receipt","markdown": "<!-- page:1 -->\n…","fields": {"merchant": "Blue Bottle Coffee","date": "2025-04-12","items": [{ "name": "Latte", "quantity": 2, "price": 11 }],"subtotal": 11,"tax": 0.98,"tip": 2,"total": 13.98,"payment_method": "Visa"},"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "passport","markdown": "<!-- page:1 -->\n…","fields": {"document_number": "L898902C3","surname": "ERIKSSON","given_names": "ANNA MARIA","nationality": "UTO","date_of_birth": "1974-08-12","sex": "F","expiry_date": "2012-04-15","issuing_country": "UTO","mrz_line1": "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<","mrz_line2": "L898902C36UTO7408122F1204159ZE184226B<<<<<10"},"mrz_valid": true,"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "id_card","markdown": "<!-- page:1 -->\n…","fields": {"document_type": "National identity card","id_number": "T22000129","full_name": "Erika Mustermann","date_of_birth": "1983-08-12","address": "Heidestr. 17, 51147 Köln","expiry_date": "2031-08-01","issuing_authority": "Stadt Köln"},"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "bank_statement","markdown": "<!-- page:1 -->\n…","fields": {"account_holder": "Jane Doe","account_number_last4": "4821","period_start": "2025-05-01","period_end": "2025-05-31","opening_balance": 2450.1,"closing_balance": 2101.35,"currency": "USD","transactions": [{"date": "2025-05-03","description": "Grocery Store","debit": 48.75,"credit": null,"balance": 2401.35}]},"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "menu","markdown": "<!-- page:1 -->\n…","fields": {"restaurant": "Harbor Lane Kitchen","currency": "USD","sections": ["Starters", "Mains"],"items": [{"section": "Starters","name": "Crispy calamari","description": "Lemon aioli, charred lemon","price": 12.5,"currency": "USD","options": []},{"section": "Mains","name": "Wood-fired margherita","description": "San Marzano tomato, fior di latte, basil","price": 16,"currency": "USD","options": ["Add burrata +5"]}]},"usage": {"pages": 1,"credits": 26,"extraction_credits": 11,"latency_ms": 4120,"cached": false}}{"id": "req_3b1d9e07c2a4f5","model": "google/gemini-flash","format": "markdown","document_type": "invoice","markdown": "<!-- page:1 -->\n…","fields": null,"fields_error": "Field extraction failed: Model output is not JS…","usage": {"pages": 1,"credits": 15,"extraction_credits": 0,"latency_ms": 4120,"cached": false}}POST/v1/files
Upload a file once and refer to it by ID for 24 hours. Add public=true to also get a public link to it. Send multipart/form-data with a file field.
Body
filefile, required- PDF, PNG, JPG, WebP or GIF, up to 20 MB. With public=true: any file type, up to 50 MB (subscribers: up to 2 GB; one request carries at most 95 MB, larger files go through the upload box).
publicboolean- true returns a url anyone can open. PDFs, images, audio, video and plain text open in the browser; other types download.
expires_ininteger | "never"- With public=true: seconds until the link expires (60 or more). Leave it out, or send "never", for a link that never expires (expires_at: null). Images and PDFs get a small ocrrouter.ai watermark unless the account subscribes; the response says watermarked: true or false.
Errors
- 400 invalid_request, unsupported_file, empty_file
- 401 invalid_api_key
- 413 file_too_large (with limit_mb and subscriber_limit_mb), direct_upload_required
curl https://api.ocrrouter.ai/v1/files \
-H "Authorization: Bearer $OCRROUTER_API_KEY" \
-F "file=@report.pdf" \
-F "public=true"{"id": "file_3b9c1e7a52d0f48e61","filename": "report.pdf","mime": "application/pdf","bytes": 482113,"pages": 12,"created_at": "2026-11-12T09:00:00.000Z","expires_at": null,"permanent": true,"watermarked": true,"url": "https://ocrrouter.ai/f/Jq3vX0aYb1dKc8mTn2pRzw/r…"}DELETE/v1/files/{id}
Delete an upload now. Its public link stops working immediately.
Errors
- 401 invalid_api_key
- 404 file_not_found
curl -X DELETE https://api.ocrrouter.ai/v1/files/file_3b9c1e7a52d0f48e61 \
-H "Authorization: Bearer $OCRROUTER_API_KEY"{"id": "file_3b9c1e7a52d0f48e61","deleted": true}GET/v1/requests/{id}
Fetch an earlier result again, in any output format, without paying again.
Query
formatstring- markdown, json, text, html, csv, docx or xlsx. Default: the format of the original request.
Errors
- 401 invalid_api_key
- 404 not_found
curl "https://api.ocrrouter.ai/v1/requests/req_8f2c1a41d0b3c7e9a2?format=markdown" \
-H "Authorization: Bearer $OCRROUTER_API_KEY"{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "markdown","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…" }],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}GET/v1/modelsNo key
List every model with its price and whether it can be called right now. No key needed.
curl https://api.ocrrouter.ai/v1/models{"data": [{"id": "mistral/mistral-ocr","name": "Mistral OCR","provider": "Mistral","type": "OCR API","description": "Fast document OCR that returns clean Markdown w…","available": true,"credits_per_page": 25,"inputs": ["pdf", "image"],"max_pages": 1000,"supports": ["Tables", "Math", "Bounding boxes", "Multilingual"]}]}GET/v1/credits
Your credit balance and this key's usage against its limit.
Errors
- 401 invalid_api_key
curl https://api.ocrrouter.ai/v1/credits \
-H "Authorization: Bearer $OCRROUTER_API_KEY"{"credits": 14280,"key": { "credits_used": 5120, "credit_limit": 20000 }}GET/v1/statsNo key
Measured success rate and speed per model from recent traffic. No key needed.
Query
hoursinteger- Window size, 1 to 720. Default 24.
curl "https://api.ocrrouter.ai/v1/stats?hours=24"{"window_hours": 24,"models": {"mistral/mistral-ocr": {"requests": 412,"ok": 409,"failed": 3,"successRate": 0.9927,"pages": 3120,"medianMsPerPage": 940}}}POST/v1/keys/temporaryNo key
Get a temporary key with 50 credits, without an account. One per IP address per day. Meant for agents and first tries.
Errors
- 429 temporary_key_limit
curl -X POST https://api.ocrrouter.ai/v1/keys/temporary{"api_key": "ocr_tmp_5f0c…","credits": 50,"note": "Temporary key with 50 credits. Sign up to keep …"}Errors
Every error has the same shape: a short machine-readable code and a message you can show to a person. A 429 response includes a Retry-After header. When all models fail, the 502 body also lists each attempt, and you are not charged.
{"error": {"code": "insufficient_credits","message": "This request needs up to 72 credits and your ba…"}}