# PDFs and files
Ask a model about a document, natively or through OCR: formats, limits, costs and errors.

## When to use it
Contracts, invoices, papers, scans: ask questions about a document, extract fields, summarize. Two paths lead to the model:

| | Native `file` part | OCR (plugin `file-parser`) |
|---|---|---|
| Works with | models that list `file` in `architecture.input_modalities` | every text model |
| Source | URL or base64 data URL; a file ID at some providers | base64 PDF data URL, or HTTP(S) when fetching is enabled |
| The model reads | the document as the provider processes it | extracted text from the configured OCR model |
| Scanned pages | depends on the model | read by OCR |
| Limits | per route | 8 PDFs, 1,000 pages each, 4 MiB of extracted text in total |
| Cost | input tokens | OCR per page plus input tokens of the text |
| Streaming | as usual | extraction first, then the stream starts |

Use the native path when a model with `file` input fits. Use OCR when the model has no file input or the pages are scans. The gateway never extracts on its own: a `file` part sent to a model without file input fails with 404 `no_endpoint`. The plugin settings and a complete OCR request in curl, Node and Python are in [PDF parser](https://tokenlane.de/docs/guides/pdf-parser.md?lang=en).

## Minimal example
The native path: a text part with the question and a `file` part with a one-page PDF as data URL. It needs a model that lists `file` as input; if the catalog has none, use the OCR request below.



## Request format
The file part:

```json
{ "type": "file", "file": { "filename": "invoice.pdf", "file_data": "data:application/pdf;base64,JVBERi0xLjQK..." } }
```

| Field | Value |
|---|---|
| `file.file_data` | An `http(s)` URL or a base64 data URL `data:application/pdf;base64,<data>` |
| `file.file_id` | ID of a previously uploaded file; valid only at the issuing provider. |
| `file.filename` | Optional; helps the model tell several files apart. |

`file_data` or `file_id` is required (400 otherwise). PDF is the portable type; other document types depend on the route.

A route may limit types, size and count of files. The gateway checks inline data before the call and names the route and field in `issues` (`unsupported_media_type`, `media_type_mismatch`, `media_too_large`, `too_many_media`). Native URL transport may adapt files through the protected loader when required and enabled.

The OCR path adds a plugin; this example uses base64:

```json
"plugins": [{ "id": "file-parser", "pdf": { "engine": "mistral-ocr" } }]
```

- **Input:** a data URL `data:application/pdf;base64,...` that starts with `%PDF-` once decoded, or an HTTP(S) PDF URL when `media_transport.fetch_enabled` is enabled. File IDs and other media types remain unavailable.
- **Count:** at most 8 PDFs per request, at most 1,000 pages each. The body limit of 50 MiB applies; base64 makes a PDF about a third larger.
- **Result:** extracted text replaces the `file` part; other message text stays. The total must fit 4 MiB and the model's context.
- **Timing:** extraction runs once per request before streaming, including provider fallbacks.
- **Engine:** `pdf.engine` is optional (default `mistral-ocr`); `"enabled": false` switches the plugin off.

### Details

- Available engines map through `preprocessing.ocr_engines` to ordinary OCR models. Unknown or unmapped engines remain unavailable; missing configuration yields `feature_unavailable`.
- Remote loading checks host policy and public addresses at every redirect, with redirect, byte and timeout limits and PDF MIME/signature checks.
- The PDF plugin uses the Mistral OCR protocol. For image-chat OCR such as LightOnOCR, a configured internal media worker renders at most 16 pages as images; without it, PDFs remain unavailable for that route. Encrypted PDFs are not rendered.

## Choosing a model
- **Native:** filter the [catalog](https://tokenlane.de/models) for input `file` and check the route; otherwise use OCR.
- **OCR:** any text model with enough context.

Rule of thumb: 500 to 1,000 tokens per dense text page, up to 100,000 for 100 pages. German text and tables use more.

## Costs
Native path: the provider turns the document into input tokens (text and often page images); `usage.prompt_tokens` shows how many. The gateway cannot count them in advance and reserves the route’s whole context window as prompt. Image-only requests can use a verified estimate (see [Image understanding](https://tokenlane.de/docs/guides/images.md?lang=en)).

OCR path: OCR models bill per page or per token; the current prices are in the [OCR catalog](https://tokenlane.de/models?category=ocr&sovereign=0) and on each model page. The preprocessing receipt records the billing basis and, when supplied by the provider, optional `token_usage`. `usage.cost_details.ocr_cost` (EUR) with `ocr_documents` is included in `usage.cost`, once per document even across chat fallbacks. Extracted text then counts as ordinary chat input.

A request over a scanned PDF therefore has three parts: the OCR pages (or OCR tokens), the extracted text as input tokens of the chat model, and the answer as output tokens. `usage.cost` is their sum; `cost_details` shows the parts.

### Reservation before the call

- A consistent, readable inline PDF of at most 8 MiB reserves its page count plus 10%, at least one extra page, capped at 1,000 pages. A one-page PDF therefore reserves two pages of OCR, plus inference.
- Encrypted, damaged or unsupported PDFs, unavailable parser resources, and unknown page counts retain the 1,000-page ceiling.
- Native files keep the context-window reservation.
- `remedy_hint` distinguishes the method on 402.

For page-based OCR, only actual processed pages are charged afterwards; actual usage beyond the estimate remains payable.

## Common errors
| Status, type | Cause and fix |
|---|---|
| 404 `no_endpoint` | The model has no file input and the plugin is off. **Fix:** Add `plugins`, or choose a model from `remedy_hint`. |
| 501 `feature_unavailable` | Remote PDF fetching is disabled or the OCR model mapping is missing. **Fix:** Send an inline PDF, or ask the operator to enable bounded fetching and configure OCR. |
| 400 `invalid_parameter`, issue `invalid_value` | The data does not decode to a PDF (`%PDF-`), or more than 8 PDFs. **Fix:** Send valid PDFs, at most 8. |
| 400 `invalid_parameter`, issue `not_available` at `plugins[].pdf.engine` | An unknown engine. **Fix:** Use a configured engine or omit `engine`; an unmapped default remains unavailable. |
| 400 `context_length_exceeded` | The extracted text does not fit the model. OCR is charged already. **Fix:** Split the document or choose a model with more context. |
| 413 `payload_too_large` | Body above 50 MiB, or extracted text above 4 MiB. **Fix:** Send fewer or shorter PDFs. |
| 402 `insufficient_credits` | The padded page estimate, fallback 1,000-page ceiling, or native context reservation exceeds the key limit or credits. **Fix:** Read `remedy_hint`; top up credits, raise the limit, or split the document. |
| Remote media loader errors | Loading limits above or source failures. **Fix:** Check `issues` and `remedy_hint`; use a permitted public PDF URL or inline data. |
| 502 `provider_error`, `provider_invalid_response` | The OCR service failed or returned an unusable result, for example more than 1,000 pages. **Fix:** Retry once; split the document. |

## Best practice
- Test one real document on both paths and compare answer quality and `usage.cost`.
- Send only the pages you need. Cut the PDF on your side: OCR bills per page, the model per token.
- Extracted text is not returned. Resending the PDF with the plugin extracts and charges again. Ask for a complete structured extract once and continue from that answer.
- Document text is untrusted and may contain instructions. Verify extracted amounts and dates against the source before use.
- For pages where layout matters (tables, forms), render the page as an image and compare with [Image understanding](https://tokenlane.de/docs/guides/images.md?lang=en).
- Split documents above 1,000 pages or 4 MiB of text.

## For AI agents
- Endpoint: [`POST /chat/completions`](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=en); the document sits in `messages[].content[]`.
- Native part: `{"type":"file","file":{"filename":"x.pdf","file_data":"<url or data:application/pdf;base64,...>"}}`; the model needs `file` in `architecture.input_modalities`.
- OCR: add `"plugins":[{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]`; use `data:application/pdf;base64,...` or HTTP(S) with fetching enabled; file IDs remain unavailable; at most 8 PDFs, 1,000 pages each, 4 MiB of text in total.
- Limits: body 50 MiB; extracted text must fit the model's context.
- Cost: native input tokens; OCR in `usage.cost_details.ocr_cost` (EUR) plus tokens. Reservation: readable PDF pages plus 10% (at least one extra, at most 1,000); unknown pages retain 1,000; native files retain the full context window. Actual usage is payable.
- Errors: 404 `no_endpoint`, 400 `invalid_parameter` (issue codes `not_available`, `invalid_value`, `media_*`), 501 `feature_unavailable`, remote media loader errors, 413, 402, 502.
