Top-level fields
idstring- Request ID, starting req_. Use it with GET /v1/requests/{id} to fetch the result again for free.
modelstring- The model that produced the result. With model auto or fallbacks this is the one that succeeded.
formatstring- The format you asked for: markdown, json, text, html, csv, docx or xlsx.
attemptsobject[]- Every model tried, in order: { model, ok, ms, error? }. A skipped model has ms 0 and an error such as "Model is not available" or "More than N pages".
markdownstring- All pages joined, each one preceded by a <!-- page:N --> line. Not present when format is json.
pagesobject[]- One entry per page. For every format except json: { index, markdown }. For json: { index, width, height, unit, blocks } (see below).
outputobject- Only for text, html, csv, docx and xlsx: { format, filename, mime_type, encoding, data }. encoding is utf8 for text, html and csv and base64 for docx and xlsx.
document_typestring- Echoed when you sent document_type.
fieldsobject | null- Extracted fields for the document_type, with a fixed schema. null when extraction failed.
fields_errorstring- Why extraction failed. Only present when it did; the OCR result is still returned and the extraction is not charged.
mrz_validboolean- Passports only: whether the MRZ check digits are correct (ICAO 9303).
usage.pagesinteger- Pages processed.
usage.creditsinteger- Credits charged in total, including extraction. 0 for a cache hit without document_type. 1,000 credits = $1.
usage.extraction_creditsinteger- Part of usage.credits spent on fields (11 per document). Only present with document_type.
usage.latency_msinteger- Time from receiving the request to the result, in milliseconds.
usage.cachedboolean- true when the same file, model and page range was read before; the earlier result is returned and the OCR is not charged again.
format: markdown
The default. markdown holds the whole document with a <!-- page:N --> line before each page, and pages holds the same text split by page. Tables are GitHub-flavoured Markdown and formulas are LaTeX in $$...$$.
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": "markdown"
}'format: json
Each page becomes a list of typed blocks in reading order. When the engine returns positions (see the bbox column on each model doc), blocks carry bbox and confidence; otherwise both are null and the blocks are parsed from the Markdown.
pages[]
indexinteger- Page number, starting at 1.
widthnumber | null- Page width reported by the engine, in `unit`. null when the engine returns no positions.
heightnumber | null- Page height, in `unit`.
unitstring | null- pixel, normalized (0 to 1), normalized_1000 (0 to 999 grid, DeepSeek-OCR) or another unit the engine reports. null without positions.
blocksobject[]- The page as typed blocks in reading order. Every block has type, bbox and confidence.
Block types
heading{ level, text }- level 1 to 6 and the heading text without # marks.
paragraph{ text }- A paragraph. Line breaks inside it are kept as \n.
list{ ordered, items }- ordered is true for 1. 2. 3. lists; items holds the text of each item.
table{ rows, markdown }- rows is an array of rows, each an array of cell strings, header row first. markdown is the same table as GitHub-flavoured Markdown.
formula{ latex }- A display formula in LaTeX, from a $$...$$ block.
image{ alt }- A figure or picture. alt is its caption or alt text, often empty.
bbox[x0, y0, x1, y1] | null- Left, top, right, bottom of the block in the page's `unit`. Only from engines that return positions; null otherwise.
confidencenumber | null- Engine score from 0 to 1 when the engine reports one; null otherwise. Scores from different engines are not comparable.
{"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}}File formats
text, html, csv, docx and xlsx return the Markdown response plus output. csv and xlsx hold the tables, or the text lines when there are none. Decode data with base64 for docx and xlsx.
{"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}}import base64, os, requests
r = requests.post("https://api.ocrrouter.ai/v1/ocr",
headers={"Authorization": f"Bearer {os.environ['OCRROUTER_API_KEY']}"},
json={"file_url": "https://example.com/report.pdf", "format": "docx"}).json()
out = r["output"]
data = base64.b64decode(out["data"]) if out["encoding"] == "base64" else out["data"].encode()
open(out["filename"], "wb").write(data)Positions and units
bbox is [x0, y0, x1, y1]: left, top, right, bottom. Its unit is the page's unit as the engine reports it, so check pages[].unit before drawing: pixel values relate to width and height, normalized values run from 0 to 1, and normalized_1000 values run from 0 to 999. To draw on a page image of your own size, divide by width and height and multiply by your image size.