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]
}
| Field | Value |
|---|---|
document | type: "document_url" with a Base64 PDF data URL in document_url, or type: "image_url" with image_url |
pages | Optional; zero-based page indexes |
table_format | Optional; 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
pagesor 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_unavailableinstead 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.llmroute 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
PageTaskdefines the prompt, schema and output limits. The bundledocr-page-extract-v1requests only amarkdownstring, with 8,192 output tokens and 128 KiB of structured output. - Catalog modalities remain truthful:
?output_modalities=ocrfinds 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.
| Pricing | Billed quantity | Charge |
|---|---|---|
| Per page | processed pages | pages times pricing.page |
| Per token | input and output tokens | tokens 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_usageadditionally records confirmedprompt_tokensandcompletion_tokens; pages are not reinterpreted as tokens. - For ordinary vision LLMs,
execution: "llm_vision_transcribe"andtask_versionidentify the task.unit: "page"remains workload, not the token price basis;token_usageretains actual input, output and cache tokens andcostsby 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.