# PDFs und Dateien
Ein Modell zu einem Dokument befragen, nativ oder über OCR: Formate, Grenzen, Kosten und Fehler.

## Wann nutzen
Verträge, Rechnungen, Aufsätze, Scans: Fragen zu einem Dokument stellen, Felder extrahieren, zusammenfassen. Zwei Wege führen zum Modell:

| | Nativer `file`-Teil | OCR (Plugin `file-parser`) |
|---|---|---|
| Funktioniert mit | Modellen, die `file` in `architecture.input_modalities` führen | jedem Textmodell |
| Quelle | URL oder Base64-Data-URL; bei manchen Anbietern eine Datei-ID | Base64-PDF als Data-URL oder HTTP(S) bei aktiviertem Laden |
| Das Modell liest | das Dokument, wie der Anbieter es verarbeitet | extrahierten Text vom konfigurierten OCR-Modell |
| Gescannte Seiten | hängt vom Modell ab | werden per OCR gelesen |
| Grenzen | je Route | 8 PDFs, je 1.000 Seiten, zusammen 4 MiB extrahierter Text |
| Kosten | Eingabe-Tokens | OCR je Seite plus Eingabe-Tokens des Texts |
| Streaming | wie üblich | erst die Extraktion, dann beginnt der Stream |

Den nativen Weg nutzen, wenn ein Modell mit `file`-Eingabe passt. OCR nutzen, wenn das Modell keine Dateieingabe hat oder die Seiten Scans sind. Das Gateway extrahiert nie von selbst: Ein `file`-Teil an ein Modell ohne Dateieingabe scheitert mit 404 `no_endpoint`. Die Einstellungen des Plugins und eine vollständige OCR-Anfrage in curl, Node und Python stehen im [PDF-Parser](https://tokenlane.de/docs/guides/pdf-parser.md?lang=de).

## Minimalbeispiel
Der native Weg: ein Textteil mit der Frage und ein `file`-Teil mit einem einseitigen PDF als Data-URL. Er braucht ein Modell, das `file` als Eingabe führt; hat der Katalog keines, die OCR-Anfrage unten nutzen.



## Anfrageformat
Der Dateiteil:

```json
{ "type": "file", "file": { "filename": "invoice.pdf", "file_data": "data:application/pdf;base64,JVBERi0xLjQK..." } }
```

| Feld | Wert |
|---|---|
| `file.file_data` | Eine `http(s)`-URL oder eine Base64-Data-URL `data:application/pdf;base64,<data>` |
| `file.file_id` | ID einer zuvor hochgeladenen Datei; gilt nur beim ausstellenden Anbieter. |
| `file.filename` | Optional; hilft dem Modell, mehrere Dateien zu unterscheiden. |

`file_data` oder `file_id` ist Pflicht (sonst 400). PDF ist der übertragbare Typ; andere Dokumenttypen hängen von der Route ab.

Eine Route kann Typen, Größe und Anzahl von Dateien begrenzen. Das Gateway prüft eingebettete Daten vor dem Aufruf und nennt Route und Feld in `issues` (`unsupported_media_type`, `media_type_mismatch`, `media_too_large`, `too_many_media`). Natives URL-Material kann bei Bedarf und aktiviertem Laden über den geschützten Medienlader angepasst werden.

Der OCR-Weg ergänzt ein Plugin; dieses Beispiel nutzt Base64:

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

- **Eingabe:** eine Data-URL `data:application/pdf;base64,...`, die dekodiert mit `%PDF-` beginnt, oder eine HTTP(S)-PDF-URL bei aktiviertem `media_transport.fetch_enabled`. Datei-IDs und andere Medientypen bleiben unverfügbar.
- **Anzahl:** höchstens 8 PDFs je Anfrage, je höchstens 1.000 Seiten. Die Body-Grenze von 50 MiB gilt; Base64 macht ein PDF etwa ein Drittel größer.
- **Ergebnis:** extrahierter Text ersetzt den `file`-Teil; übriger Nachrichtentext bleibt. Insgesamt gelten 4 MiB und die Kontextgrenze des Modells.
- **Zeitpunkt:** Extraktion läuft einmal je Anfrage vor dem Stream, auch bei Anbieter-Fallbacks.
- **Engine:** `pdf.engine` ist optional (Standard `mistral-ocr`); `"enabled": false` schaltet das Plugin aus.

### Details

- Verfügbare Engines werden über `preprocessing.ocr_engines` normalen OCR-Modellen zugeordnet. Unbekannte oder nicht zugeordnete Engines bleiben unverfügbar; fehlende Konfiguration ergibt `feature_unavailable`.
- Das Laden prüft Host-Regeln und öffentliche Adressen bei jeder Weiterleitung, mit Redirect-, Byte- und Zeitgrenzen sowie PDF-MIME- und Signaturprüfung.
- Das PDF-Plugin nutzt das Mistral-OCR-Protokoll. Bei Image-Chat-OCR wie LightOnOCR rendert ein konfigurierter interner Medienworker höchstens 16 Seiten als Bilder; ohne ihn bleiben PDFs für diese Route unverfügbar. Verschlüsselte PDFs werden nicht gerendert.

## Modell wählen
- **Nativ:** im [Katalog](https://tokenlane.de/models) nach Eingabe `file` filtern, Route prüfen; sonst OCR nutzen.
- **OCR:** jedes Textmodell mit genug Kontext.

Faustregel: 500 bis 1.000 Tokens je dichter Textseite, bis zu 100.000 für 100 Seiten. Deutscher Text und Tabellen brauchen mehr.

## Kosten
Nativer Weg: Der Anbieter macht aus dem Dokument Eingabe-Tokens (Text und oft Seitenbilder); `usage.prompt_tokens` zeigt, wie viele. Das Gateway kann sie vorab nicht zählen und reserviert das ganze Kontextfenster der Route als Prompt. Reine Bildanfragen können eine verifizierte Schätzung verwenden (siehe [Bildverständnis](https://tokenlane.de/docs/guides/images.md?lang=de)).

OCR-Weg: OCR-Modelle rechnen je Seite oder je Token ab; die aktuellen Preise stehen im [OCR-Katalog](https://tokenlane.de/models?category=ocr&sovereign=0) und auf jeder Modellseite. Der Vorverarbeitungsbeleg nennt die Abrechnungsbasis und optional `token_usage`, sofern der Anbieter diese liefert. `usage.cost_details.ocr_cost` (EUR) mit `ocr_documents` ist in `usage.cost` enthalten, auch bei Chat-Fallbacks nur einmal je Dokument. Extrahierter Text zählt danach als normale Chat-Eingabe.

Eine Anfrage zu einem gescannten PDF hat damit drei Teile: die OCR-Seiten (oder OCR-Tokens), den extrahierten Text als Eingabe-Tokens des Chatmodells und die Antwort als Ausgabe-Tokens. `usage.cost` ist ihre Summe; `cost_details` zeigt die Teile.

### Reservierung vor dem Aufruf

- Ein konsistentes, lesbares eingebettetes PDF bis 8 MiB reserviert seine Seitenzahl plus 10 %, mindestens eine zusätzliche Seite, höchstens 1.000 Seiten. Ein einseitiges PDF reserviert deshalb zwei OCR-Seiten zuzüglich Inferenz.
- Verschlüsselte, beschädigte oder nicht unterstützte PDFs, fehlende Parser-Ressourcen und unbekannte Seitenzahlen behalten die Obergrenze von 1.000 Seiten.
- Native Dateien behalten die Kontextfenster-Reservierung.
- `remedy_hint` unterscheidet bei 402 die Methode.

Bei seitenbasierter OCR zählen danach nur tatsächlich verarbeitete Seiten; tatsächliche Nutzung über der Schätzung bleibt zahlbar.

## Häufige Fehler
| Status, Typ | Ursache und Abhilfe |
|---|---|
| 404 `no_endpoint` | Das Modell hat keine Dateieingabe und das Plugin ist aus. **Abhilfe:** `plugins` ergänzen oder ein Modell aus `remedy_hint` wählen. |
| 501 `feature_unavailable` | Laden entfernter PDFs ist deaktiviert oder die OCR-Modellzuordnung fehlt. **Abhilfe:** Ein eingebettetes PDF senden oder begrenztes Laden und OCR vom Betreiber konfigurieren lassen. |
| 400 `invalid_parameter`, Issue `invalid_value` | Die Daten dekodieren nicht zu einem PDF (`%PDF-`), oder mehr als 8 PDFs. **Abhilfe:** Gültige PDFs senden, höchstens 8. |
| 400 `invalid_parameter`, Issue `not_available` bei `plugins[].pdf.engine` | Eine unbekannte Engine. **Abhilfe:** Eine konfigurierte Engine nutzen oder `engine` weglassen; ein nicht zugeordneter Standard bleibt unverfügbar. |
| 400 `context_length_exceeded` | Der extrahierte Text passt nicht in das Modell. Die OCR ist bereits berechnet. **Abhilfe:** Das Dokument teilen oder ein Modell mit mehr Kontext wählen. |
| 413 `payload_too_large` | Body über 50 MiB oder extrahierter Text über 4 MiB. **Abhilfe:** Weniger oder kürzere PDFs senden. |
| 402 `insufficient_credits` | Die Seitenzahl mit Aufschlag, ersatzweise 1.000 Seiten, oder der native Kontext übersteigt Key-Limit oder Guthaben. **Abhilfe:** `remedy_hint` lesen; Guthaben aufladen, Limit erhöhen oder das Dokument aufteilen. |
| Fehler des Medienladers | Verstoß gegen die Ladegrenzen oben oder Quellfehler. **Abhilfe:** `issues` und `remedy_hint` prüfen; erlaubte öffentliche PDF-URL oder eingebettete Daten nutzen. |
| 502 `provider_error`, `provider_invalid_response` | Der OCR-Dienst ist ausgefallen oder lieferte ein unbrauchbares Ergebnis, etwa mehr als 1.000 Seiten. **Abhilfe:** Einmal wiederholen; das Dokument teilen. |

## Bewährte Praxis
- Ein echtes Dokument auf beiden Wegen testen und Antwortqualität und `usage.cost` vergleichen.
- Nur die benötigten Seiten senden. Das PDF selbst zuschneiden: OCR berechnet je Seite, das Modell je Token.
- Extrahierter Text wird nicht zurückgegeben. Erneutes Senden mit Plugin extrahiert und berechnet erneut. Einmal eine vollständige strukturierte Extraktion erfragen und mit der Antwort weiterarbeiten.
- Dokumenttext ist nicht vertrauenswürdig und kann Anweisungen enthalten. Extrahierte Beträge und Daten vor Nutzung an der Quelle prüfen.
- Bei Seiten, auf die das Layout ankommt (Tabellen, Formulare), die Seite als Bild rendern und mit [Bildverständnis](https://tokenlane.de/docs/guides/images.md?lang=de) vergleichen.
- Dokumente über 1.000 Seiten oder 4 MiB Text aufteilen.

## Für KI-Agenten
- Endpunkt: [`POST /chat/completions`](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=de); das Dokument steht in `messages[].content[]`.
- Nativer Teil: `{"type":"file","file":{"filename":"x.pdf","file_data":"<URL oder data:application/pdf;base64,...>"}}`; das Modell braucht `file` in `architecture.input_modalities`.
- OCR: `"plugins":[{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]` ergänzen; `data:application/pdf;base64,...` oder HTTP(S) bei aktiviertem Laden nutzen; Datei-IDs bleiben unverfügbar; höchstens 8 PDFs, je 1.000 Seiten, zusammen 4 MiB Text.
- Grenzen: Body 50 MiB; der extrahierte Text muss in den Kontext des Modells passen.
- Kosten: native Eingabe-Tokens; OCR in `usage.cost_details.ocr_cost` (EUR) zuzüglich Tokens. Reservierung: lesbare PDF-Seiten plus 10 % (mindestens eine extra, höchstens 1.000); unbekannte Seiten bleiben bei 1.000; native Dateien beim ganzen Kontextfenster. Tatsächliche Nutzung ist zahlbar.
- Fehler: 404 `no_endpoint`, 400 `invalid_parameter` (Issue-Codes `not_available`, `invalid_value`, `media_*`), 501 `feature_unavailable`, Fehler des Medienladers, 413, 402, 502.
