# PDF-Parser
Die Einstellungen des Plugins file-parser, das Text aus eingebetteten oder geschützt geladenen PDFs vor der Inferenz extrahiert.

## Extraktion aktivieren
Das Plugin an eine Chat-Anfrage anhängen:

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

Das Gateway führt OCR für jedes PDF in den Nachrichten aus und gibt dem Modell stattdessen den Text; das Modell braucht keine Dateieingabe.

Wann OCR statt nativer Dateieingabe sinnvoll ist, was es kostet und was scheitern kann: [PDFs und Dateien](https://tokenlane.de/docs/guides/files.md?lang=de).

## Ein PDF eingebettet senden
Ein Base64-PDF mit Dateinamen in einen `file`-Teil der Nutzernachricht legen. Das Beispiel ist ein minimales synthetisches Dokument.

### 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());
```

## Einstellungen
| Einstellung | Wert |
|---|---|
| `id` | `file-parser` |
| `enabled` | `false` schaltet das Plugin aus; `file`-Teile gehen dann an Modelle mit nativer Dateieingabe. |
| `pdf.engine` | Optional; ohne explizites Modell gilt die konfigurierte Enginezuordnung, standardmäßig `mistral-ocr`. Nicht zugeordnete Engines und unbekannte Pluginfelder werden mit `not_available` abgelehnt. |
| `pdf.model` | Gateway-Erweiterung: explizite Katalogmodell-ID oder Alias, höchstens 256 UTF-8-Bytes. Hat Vorrang vor Plugin-`model` und `pdf.engine`. |
| `model` | Gateway-Erweiterung auf Plugin-Ebene; wird nur verwendet, wenn `pdf.model` fehlt. Leere Namen, `null` und falsche Typen sind Fehler. |

`file.file_data` enthält entweder `data:application/pdf;base64,...` oder eine HTTP(S)-URL.

### Grenzen je Anfrage

- Höchstens 8 PDFs mit je höchstens 1.000 Seiten.
- Zusammen höchstens 4 MiB extrahierter Text.

### Verhalten

- Die Extraktion ist beendet, bevor ein Stream beginnt.
- Sie wird wiederverwendet, wenn der Chat-Aufruf auf einen anderen Anbieter ausweicht.
- Der Betrag steht in `usage.cost_details.ocr_cost`.

### Remote-PDFs

Remote-PDFs werden nur bei aktiviertem `media_transport.fetch_enabled` geladen; sonst ist ein Inline-PDF erforderlich.

- Hostregeln, öffentliche Zieladressen auch nach Weiterleitungen sowie Größen- und Zeitgrenzen werden durchgesetzt.
- Private und lokale Ziele sind gesperrt.
- File-IDs und nicht zugeordnete Engines bleiben nicht verfügbar.

## Explizites Modell
Für eine bestimmte native OCR-Modellroute das Modell in `pdf.model` nennen:

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

Die Form auf Plugin-Ebene ist ebenfalls möglich:

```json
{ "id": "file-parser", "model": "<freigegebenes-ocr-modell>" }
```

Der direkte Endpunkt verwendet `POST /v1/ocr` mit `model` und `document`. Key-, Anbieter-, Länder-, Rechtsraum- und Privacyregeln gelten vor der Dokumentübermittlung. Das OCR-Modell erhält die ursprünglichen Dokumentinhalte, nicht bereits anonymisierten Text.

### Vision-Chatmodelle

Ein gewöhnliches Vision-Chatmodell ist nutzbar, wenn der Betreiber `ocr.llm` auf einer geeigneten Bild-/Textroute ausdrücklich aktiviert. Die Auswahl irgendeines Visionmodells ist keine Freigabe.

```json
{ "id": "file-parser", "pdf": { "model": "<betreiberfreigegebenes-visionmodell>" } }
```

Dies ist ein Platzhalter, kein verfügbarer Anbietermodellname. Der direkte Endpunkt kann dasselbe `model` mit einem PDF-`document` verwenden.

- Der gemeinsame Medienworker rendert PDFs sequenziell in PNG-Seiten; das PDF wird nie an einen Vision-Upstream weitergereicht. Ohne betreiberseitig konfigurierten Worker liefert dieser Weg `501 feature_unavailable`.
- Er akzeptiert höchstens 32 MiB, 1.000 Quellseiten und 16 ausgewählte Seiten, bei insgesamt 16 OCR-Aufrufen einschließlich Wiederholungen.
- Gerenderte PNGs sind höchstens 2048 × 2048 Pixel groß; strengere Byte- und Kontextgrenzen des Modells gelten zusätzlich.
- `table_format: "html"` ist bei LLM-Transkription nicht verfügbar.

### Qualität und Abrechnung

Spezialisierte OCR und LLM-Transkription unterscheiden sich in Qualität, Kosten und Latenz. LLM-Verarbeitung nutzt tatsächliche Tokenpreise statt eines Seitentarifs.

Der Beleg behält `unit: "page"`, Seitenmenge, `execution: "llm_vision_transcribe"`, `task_version` und tatsächliche `token_usage` mit Kostenbestandteilen.

Routenanforderungen, Auftragsgrenzen und direkte Beispiele stehen unter [OCR](https://tokenlane.de/docs/guides/ocr.md?lang=de). Der PII-Anschluss bleibt unverändert; dessen getrennte Tokenabrechnung erklärt der [PII-Leitfaden](https://tokenlane.de/docs/guides/pii.md?lang=de).

## Modelle und Routing
Der Betreiber ordnet jede OCR-Engine über `preprocessing.ocr_engines` einem normalen Katalogmodell zu, etwa mit dem Eintrag `mistral-ocr`. Der Wert ist die Katalogmodell-ID, nicht ein rein interner Upstreamname.

Dieses Modell nutzt dieselben Anbieterrouten und Schlüsselregeln wie eine [direkte OCR-Anfrage](https://tokenlane.de/docs/guides/ocr.md?lang=de). Modell, Anbieter, Seitenmenge und Kosten stehen im Generierungsbeleg.

## Extraktionsfehler beheben
Der Fehler nennt das Feld. Zu prüfen sind:

- das Präfix der Data-URL,
- dass die dekodierten Bytes mit `%PDF-` beginnen,
- die Anzahl der PDFs,
- die Engine.

Ohne zulässige OCR-Modellroute kann das Gateway nicht extrahieren. Eine Richtliniensperre nennt das Plugin-Modell und einen Lösungshinweis; das Modell freizugeben oder eine Engine ohne OCR zu nutzen, kann sie beheben.

Alle Ursachen und Abhilfen stehen in der Fehlertabelle unter [PDFs und Dateien](https://tokenlane.de/docs/guides/files.md?lang=de).
