OCRRouter

PaddleOCR-VL API docs

How OCRRouter calls PaddleOCR-VL, what the upstream returns field by field, and how that becomes Markdown and JSON blocks.

Overview

PaddleOCR-VL is a compact (0.9B) vision-language document parser from Baidu's PaddlePaddle team. A layout model finds blocks, then the VL model reads each one.

OCRRouter calls version 1.6 through OpenParser and returns page Markdown plus layout blocks with pixel boxes and detection scores.

Price and limits

Model ID
paddle/paddleocr-vl
Price
6 credits / page ($6 per 1,000 pages)
Max pages per request
500
Inputs
PDF; PNG, JPEG and other images OpenParser accepts
Languages
109 languages
Positions (bbox)
Yes, when the upstream returns them
License
Apache-2.0
  • Up to 500 pages per job in OCRRouter
  • Confidence is the layout detection score, not a text recognition score
  • Model can be changed server-side with OPENPARSER_PADDLE_MODEL

You pay only for pages that succeed. A failed attempt that falls back to another model is not charged. See pricing.

How OCRRouter calls it

Gateway
OpenParser
Endpoint
POST https://api.openparser.dev/parse (multipart)
Upstream model
ocr_model "paddleocr-vl-1.6"
Request
request part {"ocr_model", "output_format": "openparser@1"} plus the original file; Idempotency-Key header per call
Long documents
HTTP 202 with a job; OCRRouter polls /jobs/{id} with backoff from 1 to 5 seconds

Options

What OCRRouter sets on the upstream call. You choose the model, format and pages in your request; vendor-specific options are not passed through.

ocr_model
"paddleocr-vl-1.6"
output_format
"openparser@1"
File
Sent as uploaded, no rendering
Client options
None. Callers cannot pass model options.

Raw response fields

Every field the upstream documents, with its type and meaning taken from the vendor's own reference. Fields marked "read by OCRRouter" are the ones our connector uses; the rest are listed so you know what the engine produces.

What OCRRouter receives (OpenParser openparser@1)

OpenParser runs PaddleOCR-VL and converts its result into the openparser@1 document graph: pages with reading order, and elements with locations and scores. Field meanings follow the openparser@1 schema reference.

Source: openparser@1 schema, retrieved 2026-11-19

output_formatstring
Schema version, always "openparser@1".Example: "openparser@1"
document_idstring
Stable identifier for the parsed document.
provenance.provider / provenance.modelstring
Provider and model that produced the result.Example: "baidu" / "paddleocr-vl-1.6"
textstring, read by OCRRouter
Plain text in reading order. Spans index into it.
markdownstring, read by OCRRouter
Best-effort Markdown rendering of the whole document.
pages[].numberinteger, read by OCRRouter
One-based page number, contiguous 1 to N.Example: 1
pages[].width / heightnumber, read by OCRRouter
Size of the page coordinate space.Example: 800 / 300
pages[].unitstring, read by OCRRouter
Unit of the coordinate space: pixel, point, inch or normalized.Example: "pixel"
pages[].element_idsstring[], read by OCRRouter
IDs of elements on the page.
pages[].reading_orderstring[], read by OCRRouter
Ordered top-level element IDs for the page.
elements[].idstring, read by OCRRouter
Element ID, unique in the document.
elements[].kindstring, read by OCRRouter
Element type discriminator: text, table, figure, formula and others.Example: "text"
elements[].rolestring, read by OCRRouter
For text elements: heading, paragraph, line, word, page_header, page_footer and more.Example: "heading"
elements[].textstring, read by OCRRouter
Text of the element.Example: "Total due: $42.50 by December 1."
elements[].locations[].page_numberinteger, read by OCRRouter
Page the location is on.Example: 1
elements[].locations[].bboxobject, read by OCRRouter
Axis-aligned box {left, top, right, bottom} in page coordinates; right and bottom are exclusive.Example: {"left":37,"top":107,"right":401,"bottom":135}
elements[].locations[].polygonPoint[]
Tighter outline when the provider supplies one.
elements[].confidence.scorenumber, read by OCRRouter
Score normalized to 0 to 1.Example: 0.8717
elements[].confidence.scopestring
What the score measures: detection, recognition, classification, geometry, answer or quality.Example: "detection"
elements[].confidence.calibratedboolean
False means scores from different providers or scopes are not comparable probabilities.Example: false
elements[].confidence.source_value / source_scalenumber / string
Original provider value and its scale.Example: 0.8717 / "zero_to_one"
elements[].source.native_id / native_type / native_labelstring
The engine's own ID, type and label for the block. Not in the published schema page; present in responses.Example: "1" / "layout_block" / "text"
elements[].row_count / column_count / cells[]number / array, read by OCRRouter
For table elements: grid size and cells with row_index, column_index, text.
relations[], text_annotations[], assets[]array
Links between elements, span metadata, and page or figure images.Example: []

Real response captured 2026-11-19 from POST /parse on an 800x300 PNG with three lines of text. Trimmed to the first two elements; nothing else edited.

{"output_format": "openparser@1","document_id": "3fd622b1876c999f4f0c3e48a415c085","provenance": {"provider": "baidu","model": "paddleocr-vl-1.6","operation": "layout_parsing"},"text": "## Invoice 2026\n\nTotal due: $42.50 by December …","markdown": "## ## Invoice 2026\n\nTotal due: $42.50 by Decemb…","pages": [{"number": 1,"source_page_number": 1,"width": 800,"height": 300,"unit": "pixel","rotation_degrees": 0,"languages": [],"element_ids": ["3fd622b1876c999f4f0c3e48a415c085-paddle-1-0","3fd622b1876c999f4f0c3e48a415c085-paddle-1-1"],"reading_order": ["3fd622b1876c999f4f0c3e48a415c085-paddle-1-0","3fd622b1876c999f4f0c3e48a415c085-paddle-1-1"]}],"elements": [{"id": "3fd622b1876c999f4f0c3e48a415c085-paddle-1-0","locations": [{"page_number": 1,"bbox": { "left": 38, "top": 28, "right": 247, "bottom": 64 },"polygon": [{ "x": 38, "y": 28 },{ "x": 247, "y": 28 },{ "x": 247, "y": 64 },{ "x": 38, "y": 64 }]}],"confidence": {"score": 0.7849714159965515,"scope": "detection","calibrated": false,"source_value": 0.7849714159965515,"source_scale": "zero_to_one"},"source": {"native_id": "0","native_type": "layout_block","native_label": "paragraph_title"},"kind": "text","role": "heading","text": "## Invoice 2026","spans": [],"languages": []},{"id": "3fd622b1876c999f4f0c3e48a415c085-paddle-1-1","locations": [{"page_number": 1,"bbox": { "left": 37, "top": 107, "right": 401, "bottom": 135 },"polygon": [{ "x": 37, "y": 107.00000762939453 },{ "x": 400.1377258300781, "y": 109.00076293945312 },{ "x": 399.9891052246094, "y": 135.9779052734375 },{ "x": 36.85137939453125, "y": 133.97715759277344 }]}],"confidence": {"score": 0.871687114238739,"scope": "detection","calibrated": false,"source_value": 0.871687114238739,"source_scale": "zero_to_one"},"source": {"native_id": "1","native_type": "layout_block","native_label": "text"},"kind": "text","role": "paragraph","text": "Total due: $42.50 by December 1.","spans": [],"languages": []}],"text_annotations": [],"relations": [],"assets": []}

PaddleOCR-VL native output (pipeline result JSON)

What the PaddleOCR-VL pipeline itself returns per page, from save_to_json(). OpenParser turns parsing_res_list into elements and layout_det_res scores into confidence. OCRRouter never sees this shape directly.

Source: PaddleOCR-VL pipeline docs, retrieved 2026-11-19

input_pathstring
Path of the input image or PDF.
page_indexinteger or null
Current page for a PDF, else None.
page_countinteger or null
Total pages for a PDF, else None.
width / heightinteger
Size of the original input image.
model_settingsobject
Run settings such as use_doc_preprocessor, use_layout_detection, use_chart_recognition, format_block_content.
markdown_ignore_labelsstring[]
Labels left out of Markdown, by default number, footnote, header, header_image, footer, footer_image, aside_text.
parsing_res_list[]array
Parsed blocks; list order is the reading order.
parsing_res_list[].block_labelstring
Region label such as text, table, paragraph_title.
parsing_res_list[].block_contentstring
Recognized content of the region.
parsing_res_list[].block_bboxnumber[4]
Box of the layout region.
parsing_res_list[].block_id / block_orderinteger
Region index, and reading-order position (None when not sorted).
layout_det_res.boxes[]array
Raw layout detections, each with cls_id, label, score and coordinate.
layout_det_res.boxes[].scorenumber
Detection confidence of the box.

Built from the documented field list, with values from the real OpenParser response above. cls_id is illustrative. Not a captured PaddleOCR response.

{"input_path": "paddleocr_vl_demo.png","page_index": null,"page_count": null,"width": 800,"height": 300,"model_settings": {"use_doc_preprocessor": false,"use_layout_detection": true,"use_chart_recognition": false,"format_block_content": false},"parsing_res_list": [{"block_label": "paragraph_title","block_content": "Invoice 2026","block_bbox": [38, 28, 247, 64],"block_id": 0,"block_order": 1}],"layout_det_res": {"input_path": null,"page_index": null,"boxes": [{"cls_id": 17,"label": "paragraph_title","score": 0.785,"coordinate": [38, 28, 247, 64]}]}}

How it maps to OCRRouter output

pages[] sorted by number
One OCRRouter page each
pages[].reading_order (else element_ids)
Order of layout blocks and Markdown on the page
elements[].kind + role
Block type: table, formula, figure/image/picture -> image, heading/title -> heading, else paragraph
elements[].text (or markdown)
Block text. Headings are normalized to one run of #, level 1 to 6
Table cells
Rebuilt as a GitHub-flavoured Markdown table; first row is the header
locations[].bbox
Block bbox [left, top, right, bottom], using the location on the same page
pages[].width, height, unit
Page layout width, height and unit (pixel here)
confidence.score
Block confidence (0 to 1); null when absent
Page Markdown
Block texts joined with blank lines
Document markdown
Fallback only when no element has text: all of it goes on page 1

The unified output is described in Response format.

Example request

curl https://api.ocrrouter.ai/v1/ocr \
  -H "Authorization: Bearer $OCRROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paddle/paddleocr-vl",
    "file_url": "https://example.com/invoice.pdf",
    "format": "json"
  }'

Sources

Vendor documentation read on 2026-11-19.