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 partOCR (plugin file-parser)
Works withmodels that list file in architecture.input_modalitiesevery text model
SourceURL or base64 data URL; a file ID at some providersbase64 PDF data URL, or HTTP(S) when fetching is enabled
The model readsthe document as the provider processes itextracted text from the configured OCR model
Scanned pagesdepends on the modelread by OCR
Limitsper route8 PDFs, 1,000 pages each, 4 MiB of extracted text in total
Costinput tokensOCR per page plus input tokens of the text
Streamingas usualextraction 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..." } }
FieldValue
file.file_dataAn http(s) URL or a base64 data URL data:application/pdf;base64,<data>
file.file_idID of a previously uploaded file; valid only at the issuing provider.
file.filenameOptional; 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 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 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).

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_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, typeCause and fix
404 no_endpointThe model has no file input and the plugin is off. Fix: Add plugins, or choose a model from remedy_hint.
501 feature_unavailableRemote 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_valueThe 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.engineAn unknown engine. Fix: Use a configured engine or omit engine; an unmapped default remains unavailable.
400 context_length_exceededThe 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_largeBody above 50 MiB, or extracted text above 4 MiB. Fix: Send fewer or shorter PDFs.
402 insufficient_creditsThe 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 errorsLoading 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_responseThe 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 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.