OCRRouter

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

model string
A model ID from GET /v1/models, or auto. Default auto.
file_url string
Public http(s) URL of the file. Send exactly one of file_url, file_base64, file_id.
file_base64 string
The file as base64 (a data: URL prefix is accepted). Up to 20 MB.
file_id string
ID returned by POST /v1/files.
filename string
Name shown in your activity log.
format string
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.
pages string
Page range such as 1-5,8. Default all pages. PDF only.
fallbacks string[]
Up to 5 model IDs to try, in order, if the first fails.
route string
Used with model auto: quality (default), cheapest or fastest.
document_type string
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"}'
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}}
200format: docx
{"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}}
200document_type: invoice
{"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}}
200document_type: receipt
{"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}}
200document_type: passport
{"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}}
200document_type: id_card
{"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}}
200document_type: bank_statement
{"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}}
200document_type: menu
{"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}}
200document_type: extraction failed (OCR result still returned)
{"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

file file, 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).
public boolean
true returns a url anyone can open. PDFs, images, audio, video and plain text open in the browser; other types download.
expires_in integer | "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"
200result
{"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"
200result
{"id": "file_3b9c1e7a52d0f48e61","deleted": true}

GET/v1/requests/{id}

Fetch an earlier result again, in any output format, without paying again.

Query

format string
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"
200result
{"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
200result
{"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"
200result
{"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

hours integer
Window size, 1 to 720. Default 24.
curl "https://api.ocrrouter.ai/v1/stats?hours=24"
200result
{"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
200result
{"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.

402error
{"error": {"code": "insufficient_credits","message": "This request needs up to 72 credits and your ba…"}}