# 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](https://tokenlane.de/docs/guides/pdf-parser.md?lang=en) instead.

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

### curl

```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

```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

```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

```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`:

```json
{
  "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](https://tokenlane.de/models?category=ocr&sovereign=0). 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:

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

In the plugin, the equivalent is:

```json
{ "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](https://tokenlane.de/models?category=ocr&sovereign=0) 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_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](https://tokenlane.de/docs/gateway/post-L29jcg.md?lang=en) for the exact schema and [model catalog](https://tokenlane.de/models?category=ocr&sovereign=0) for model IDs. Do not send an OCR model to chat completions or infer a model ID from an engine name.
