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

```json
"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](https://tokenlane.de/docs/guides/files.md?lang=en).

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

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

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

```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
| Setting | Value |
|---|---|
| `id` | `file-parser` |
| `enabled` | `false` switches the plugin off; `file` parts then go to models with native file input. |
| `pdf.engine` | Optional; 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.model` | Gateway extension: explicit catalog model ID or alias, at most 256 UTF-8 bytes. Takes precedence over plugin-level `model` and `pdf.engine`. |
| `model` | Gateway 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`:

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

The plugin-level form is also accepted:

```json
{ "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.

```json
{ "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](https://tokenlane.de/docs/guides/ocr.md?lang=en) for route requirements, task bounds and direct examples. PII integration is unchanged; its separate token billing is described in the [PII guide](https://tokenlane.de/docs/guides/pii.md?lang=en).

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