OCRRouter

DeepSeek-OCR API docs

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

Overview

DeepSeek-OCR is an open-weight MIT-licensed vision-language OCR model from DeepSeek that compresses each page into a small number of vision tokens.

OCRRouter calls it through AIHubMix with the grounding prompt, so each block of output carries a type label and a box. That gives you page Markdown plus layout blocks with positions.

Price and limits

Model ID
deepseek/deepseek-ocr
Price
1 credit / page ($1 per 1,000 pages)
Max pages per request
200
Inputs
PDF (rendered to page images); PNG, JPEG and other images AIHubMix accepts as image_url
Languages
100+ languages
Positions (bbox)
Yes, when the upstream returns them
License
MIT
  • Up to 200 pages per job in OCRRouter
  • One image per request; long PDFs take one call per page
  • No confidence scores
  • Known to repeat tokens on some tables (GitHub issues #12 and #16)

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
AIHubMix, OpenAI-compatible
Endpoint
POST https://aihubmix.com/v1/chat/completions
Upstream model
"deepseek-ocr"
Request
One user message per page: the page as a base64 data URL in an image_url part, then the prompt as a text part
PDFs
Rendered to PNG at 150 dpi with poppler pdftoppm, one request per page, 4 pages at a time
Images
Sent as is, one request

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.

model
"deepseek-ocr"
prompt
"<|grounding|>Convert the document to markdown."
temperature
0
PDF render
150 dpi PNG
Concurrency
4 pages at a time
Other parameters
None sent (no max_tokens, no stream, no response_format)
Client options
None. Callers cannot pass model options; OCRRouter fixes the request above.

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 (AIHubMix chat completion)

AIHubMix exposes deepseek-ocr through its OpenAI-compatible POST /v1/chat/completions endpoint. OCRRouter sends one request per page image and gets back a standard chat completion object. Field meanings from OpenAI's chat completion object reference and our test call on 2026-11-19; the field list below is every field in that response.

Source: OpenAI chat completion object, retrieved 2026-11-19

idstring
Unique identifier for the chat completion.Example: "as-ryvg77zszb"
objectstring
Object type, always "chat.completion".Example: "chat.completion"
createdinteger
Unix timestamp in seconds when the completion was created.Example: 1795106679
modelstring
Model that produced the completion.Example: "deepseek-ocr"
choices[]array, read by OCRRouter
List of completion choices. OCRRouter sends no n parameter, so there is one.
choices[].indexinteger
Position of the choice in the list.Example: 0
choices[].message.rolestring
Role of the message author, "assistant".Example: "assistant"
choices[].message.contentstring or null, read by OCRRouter
Text the model generated. For these OCR models this is the page transcription.Example: "<|ref|>sub_title<|/ref|><|det|>[[49, 64, 419, 163]]<|/det|>\n..."
choices[].message.refusalstring or null
Refusal message if the model refused; null otherwise.Example: null
choices[].finish_reasonstring
Why generation stopped: "stop" for a natural end, "length" when the token limit was hit.Example: "stop"
choices[].logprobsobject or null
Log probabilities, only when requested. OCRRouter does not request them.Example: null
usage.prompt_tokensinteger
Tokens in the prompt, including the image.Example: 493
usage.completion_tokensinteger
Tokens in the generated output.Example: 111
usage.total_tokensinteger
Prompt plus completion tokens. AIHubMix bills per token.Example: 604

Real response captured 2026-11-19 by OCRRouter with the exact request shown under Options, on an 800x420 PNG with a heading, a paragraph and a 3x3 table. Nothing edited.

{"id": "as-ryvg77zszb","model": "deepseek-ocr","object": "chat.completion","created": 1795106679,"choices": [{"index": 0,"finish_reason": "stop","logprobs": null,"message": {"role": "assistant","content": "<|ref|>sub_title<|/ref|><|det|>[[49, 64, 419, 1…","refusal": null}}],"usage": {"prompt_tokens": 493,"completion_tokens": 111,"total_tokens": 604}}

DeepSeek-OCR native output (grounding mode)

The model returns one string. With <|grounding|> in the prompt (the default PROMPT in DeepSeek-OCR-vllm/config.py) it writes a <|ref|> label and a <|det|> box before each block. Field meanings from DeepSeek-OCR-vllm/run_dpsk_ocr_image.py and our test call on 2026-11-19: re_match() finds each <|ref|>label<|/ref|><|det|>boxes<|/det|> pair, draw_bounding_boxes() scales each box by x / 999 * image width and y / 999 * image height, image blocks are cropped and replaced with a Markdown image link, and all other markers are stripped to leave the Markdown. The code does not list every label; title, image and the labels below are the ones seen in the code or our test.

Source: DeepSeek-OCR-vllm/run_dpsk_ocr_image.py, retrieved 2026-11-19

<|ref|>...<|/ref|>token span, read by OCRRouter
Block label. The reference code treats image (cropped to a picture) and title (drawn with a thicker box) specially. Our test returned sub_title, text and table.Example: <|ref|>table<|/ref|>
<|det|>[[x0,y0,x1,y1]]<|/det|>token span, list of boxes, read by OCRRouter
One or more boxes as top-left and bottom-right corners, normalised to 0 to 999 of the image width and height. The reference code parses the span as a Python list of boxes and multiplies by size / 999 to get pixels.Example: <|det|>[[49, 377, 728, 744]]<|/det|>
block textstring, read by OCRRouter
Markdown for the block, after the det span. Headings use #, tables come as HTML <table> with no header cells.Example: <table><tr><td>Region</td><td>Q2</td>...

The message.content string from the real response above, captured 2026-11-19.

<|ref|>sub_title<|/ref|><|det|>[[49, 64, 419, 163]]<|/det|>
# Quarterly Report 

<|ref|>text<|/ref|><|det|>[[49, 230, 555, 285]]<|/det|>
Sales grew 12 percent in the third quarter. 

<|ref|>table<|/ref|><|det|>[[49, 377, 728, 744]]<|/det|>
<table><tr><td>Region</td><td>Q2</td><td>Q3</td></tr><tr><td>North</td><td>120</td><td>134</td></tr><tr><td>South</td><td>98</td><td>110</td></tr></table>

How it maps to OCRRouter output

choices[0].message.content
Page text. A wrapping ```markdown fence is stripped.
HTML <table> in content
Rewritten as a GitHub-flavoured Markdown table (htmlTablesToMarkdown); the first row is the header
One response per page
pages[i] in OCRRouter output, in page order
<|ref|>label<|/ref|><|det|>[[x0,y0,x1,y1]]<|/det|>
Starts a layout block. Text up to the next marker becomes the block text
ref label
Block type: contains table -> table, title -> heading, image or figure -> image, formula or equation -> formula, else paragraph
det box
Block bbox [x0, y0, x1, y1] on a 0 to 999 grid; page layout unit is normalized_1000 with width and height 1000
Heading blocks
Get a leading # if the model gave none; level is the count of #
Confidence
null. DeepSeek-OCR gives no scores
Page Markdown
Block texts joined with blank lines, markers removed. If no markers appear, the whole content is the page and there is no layout
Layout for the job
Returned only when every page had markers

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": "deepseek/deepseek-ocr",
    "file_url": "https://example.com/invoice.pdf",
    "format": "json"
  }'

Sources

Vendor documentation read on 2026-11-19.