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.
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:
{ "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:
"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 whenmedia_transport.fetch_enabledis 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
filepart; 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.engineis optional (defaultmistral-ocr);"enabled": falseswitches the plugin off.
Details
- Available engines map through
preprocessing.ocr_enginesto ordinary OCR models. Unknown or unmapped engines remain unavailable; missing configuration yieldsfeature_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 for input
fileand 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).
OCR path: OCR models bill per page or per token; the current prices are in the OCR catalog 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_hintdistinguishes 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.
- 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 inmessages[].content[]. - Native part:
{"type":"file","file":{"filename":"x.pdf","file_data":"<url or data:application/pdf;base64,...>"}}; the model needsfileinarchitecture.input_modalities. - OCR: add
"plugins":[{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]; usedata: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, 400invalid_parameter(issue codesnot_available,invalid_value,media_*), 501feature_unavailable, remote media loader errors, 413, 402, 502.