OCR

Extract document text through a routed OCR model, independently of chat inference.

When to use it

Use OCR for scanned PDFs and document images when you need Markdown, not a chat answer.

For automatic extraction inside a conversation, use the PDF parser instead.

Minimal example

The example selects the first page of a synthetic inline PDF. Replace the document with permitted application data only.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/ocr' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}'

node

const response = await fetch("https://api.tokenlane.de/v1/ocr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());

python

import os
import urllib.request

body = (r'''{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/ocr",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/ocr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());

Request format

Send JSON to POST /v1/ocr with a model and a Mistral-style document:

{
  "model": "<ocr-model>",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,..."
  },
  "pages": [0]
}
FieldValue
documenttype: "document_url" with a Base64 PDF data URL in document_url, or type: "image_url" with image_url
pagesOptional; zero-based page indexes
table_formatOptional; selects the table representation

The result contains pages[].markdown and usage_info. Additional layout data depends on the provider; image positions and dimension data are not invented.

Limits

  • Each request permits 16 OCR calls in total, including retries.
  • Image-chat OCR such as LightOnOCR requires images. PDFs are rendered into page images only when an internal media worker is configured: at most 16 selected pages, 1,000 source pages, 32 MiB, no encryption. Without a renderer, send images or extracted text.
  • File IDs are not resolved.

Remote URLs

HTTP(S) URLs are downloaded by the protected document loader only when the operator enables media_transport.fetch_enabled; otherwise the request is rejected before an OCR call.

  • Every redirect checks host policy and public destination addresses; private, loopback and internal addresses remain blocked.
  • Configured download, aggregate transfer and time limits apply, plus 32 MiB per document.

Choosing a model

Select a current OCR model. OCR is a normal catalog model with provider routes, regional declarations and fallback.

Specialized OCR models and approved vision LLMs can differ in transcription quality, cost and latency; none guarantees perfect reading. Key, provider, country, jurisdiction, privacy and price policies apply before disclosure.

Both native OCR and LLM transcription receive the original document contents, not already redacted data.

Tables

  • Simple HTML tables are converted to Markdown according to the route profile or table_format: "markdown".
  • Complex or malformed tables are preserved.
  • For native OCR, table_format: "html" retains the provider output.

Vision chat models as OCR

An ordinary vision chat model works only when the operator explicitly approves its route with ocr.llm. Image input alone is not OCR approval. For such a model, a request looks like this:

{
  "model": "<operator-approved-vision-model>",
  "document": { "type": "image_url", "image_url": "data:image/png;base64,..." },
  "pages": [0]
}

In the plugin, the equivalent is:

{ "id": "file-parser", "pdf": { "model": "<operator-approved-vision-model>" } }

These are placeholders, not claims that any provider model is available.

  • Direct LLM OCR currently accepts one bounded PNG (omit pages or use [0]), or a PDF through the shared media worker.
  • table_format: "html" is not supported on this path.
  • PDF page images are bounded by the shared worker contract. Without an operator-configured worker, PDF rendering returns 501 feature_unavailable instead of forwarding the PDF to a vision upstream.

Details for operators

  • The same model can power the file-parser plugin through an operator-defined engine mapping.
  • An ocr.llm route must use OpenAI Chat transport with text and image input and text output, JSON Schema output or forced tools, preserved execution controls, reliable token usage and a verified image-token formula.
  • A versioned PageTask defines the prompt, schema and output limits. The bundled ocr-page-extract-v1 requests only a markdown string, with 8,192 output tokens and 128 KiB of structured output.
  • Catalog modalities remain truthful: ?output_modalities=ocr finds native OCR models, while ordinary vision models retain image/text modalities and are not automatically approved for OCR.

Costs

Page-priced routes publish pricing.page, a price per page, not per million tokens. Image-chat OCR such as LightOnOCR is billed at the model's prompt and output token prices. Current prices are in the OCR catalog and on each model page.

PricingBilled quantityCharge
Per pageprocessed pagespages times pricing.page
Per tokeninput and output tokenstokens times the prompt and completion prices

Reservation

  • Page pricing reserves counted or conservatively estimated document pages; an explicit page selection reserves that selection.
  • Token pricing reserves the bounded model context and output allowance before the call.

Receipt

The generation receipt records the model, provider, unit: "page", actual processed pages and cost under preprocessing.

  • For token pricing, token_usage additionally records confirmed prompt_tokens and completion_tokens; pages are not reinterpreted as tokens.
  • For ordinary vision LLMs, execution: "llm_vision_transcribe" and task_version identify the task. unit: "page" remains workload, not the token price basis; token_usage retains actual input, output and cache tokens and costs by price component, including original, customer and purchase costs.

What stays chargeable

  • Paid invalid output and fallback attempts.
  • Missing token usage is not a free successful extraction.
  • Failed later inference does not erase completed OCR charges.

Common errors

A missing OCR model, an unavailable route, invalid document data or a policy block prevents extraction. No OCR route means no automatic extraction.

Inspect every field issue and the error's remedy_hint. A policy block must not be bypassed by switching to the plugin.

Best practice

  • Use inline synthetic documents for development.
  • Restrict document size before sending, and prefer explicit page selections when you need only part of a document.
  • Retain the generation ID for cost investigation.
  • Never log document data URLs or extracted text.

For AI agents

Use the current OCR endpoint reference for the exact schema and model catalog for model IDs. Do not send an OCR model to chat completions or infer a model ID from an engine name.