PDF parser

The settings of the file-parser plugin, which extracts text from inline or securely downloaded PDFs before inference.

Enable extraction

Add the plugin to a chat request:

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

The gateway runs OCR on every PDF in the messages and gives the model the text instead; the model does not need file input.

When to choose OCR over native file input, what it costs and what can fail: PDFs and files.

Send an inline PDF

Put a base64 PDF into a user-message file part, with its file name. The example is a minimal synthetic document.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this file."
        },
        {
          "type": "file",
          "file": {
            "filename": "example.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
          }
        }
      ]
    }
  ],
  "max_tokens": 400,
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ]
}'

node

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this file."
        },
        {
          "type": "file",
          "file": {
            "filename": "example.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
          }
        }
      ]
    }
  ],
  "max_tokens": 400,
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ]
}, {});
console.log(response);

python

import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this file."
        },
        {
          "type": "file",
          "file": {
            "filename": "example.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
          }
        }
      ]
    }
  ],
  "max_tokens": 400,
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ]
}''')
response = client.chat.completions.create(
    model=body["model"],
    messages=body["messages"],
    max_tokens=body["max_tokens"],
    extra_body=json.loads(r'''{
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ]
}''')
)
print(response)

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this file."
        },
        {
          "type": "file",
          "file": {
            "filename": "example.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
          }
        }
      ]
    }
  ],
  "max_tokens": 400,
  "plugins": [
    {
      "id": "file-parser",
      "pdf": {
        "engine": "mistral-ocr"
      }
    }
  ]
}`,
});
console.log(await response.text());

Settings

SettingValue
idfile-parser
enabledfalse switches the plugin off; file parts then go to models with native file input.
pdf.engineOptional; without an explicit model, uses the configured engine mapping, defaulting to mistral-ocr. Unmapped engines and unknown plugin fields are rejected with not_available.
pdf.modelGateway extension: explicit catalog model ID or alias, at most 256 UTF-8 bytes. Takes precedence over plugin-level model and pdf.engine.
modelGateway extension at plugin level, used only when pdf.model is absent. Empty names, null and incorrect types are errors.

file.file_data contains either data:application/pdf;base64,... or an HTTP(S) URL.

Limits per request

  • At most 8 PDFs, each of at most 1,000 pages.
  • At most 4 MiB of extracted text in total.

Behavior

  • Extraction finishes before a stream starts.
  • It is reused if the chat call falls back to another provider.
  • The charge is reported in usage.cost_details.ocr_cost.

Remote PDFs

Remote PDFs are downloaded only when media_transport.fetch_enabled is enabled; otherwise an inline PDF is required.

  • Host policy, public destination addresses at every redirect, byte limits and deadlines are enforced.
  • Private and loopback destinations are blocked.
  • File IDs and unmapped engines remain unavailable.

Explicit model selection

To pick a specific native OCR route, name the model in pdf.model:

{ "id": "file-parser", "pdf": { "model": "<approved-ocr-model>" } }

The plugin-level form is also accepted:

{ "id": "file-parser", "model": "<approved-ocr-model>" }

The direct endpoint uses POST /v1/ocr with model and document. Key, provider, country, jurisdiction and privacy rules apply before document disclosure. The OCR model receives the original document, not already anonymized text.

Vision chat models

An ordinary vision chat model is usable when the operator explicitly enables ocr.llm on an eligible image/text route. Selecting any vision model is not approval.

{ "id": "file-parser", "pdf": { "model": "<operator-approved-vision-model>" } }

This is a placeholder, not an available provider model name. The direct endpoint can use the same model with a PDF document.

  • The shared media worker renders PDFs sequentially into PNG pages; the PDF is never forwarded to a vision upstream. Without an operator-configured worker this path returns 501 feature_unavailable.
  • It accepts at most 32 MiB, 1,000 source pages and 16 selected pages, with 16 OCR calls including retries.
  • Rendered PNGs are at most 2048 × 2048 pixels; stricter model byte and context limits also apply.
  • table_format: "html" is not available for LLM transcription.

Quality and billing

Specialized OCR and LLM transcription differ in quality, cost and latency. LLM processing uses actual token prices, not a page tariff.

The receipt keeps unit: "page", page count, execution: "llm_vision_transcribe", task_version and actual token_usage with component costs.

See OCR for route requirements, task bounds and direct examples. PII integration is unchanged; its separate token billing is described in the PII guide.

Models and routing

The operator maps each OCR engine to a normal catalog model using preprocessing.ocr_engines, for example the mistral-ocr entry. The value is the catalog model ID, not an upstream-only name.

That model uses the same provider routing and key policies as a direct OCR request. Its model, provider, page quantity and costs appear in the generation receipt.

Fix extraction failures

The error names the field. Check:

  • the data URL prefix,
  • that the decoded bytes start with %PDF-,
  • the number of PDFs,
  • the engine.

Without a permitted OCR model route, the gateway cannot extract. A policy block names the plugin model and includes a remedy hint; allowing the model or using a non-OCR engine can resolve it.

All causes and fixes are in the error table of PDFs and files.