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:

"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.

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

Einstellungen

EinstellungWert
idfile-parser
enabledfalse schaltet das Plugin aus; file-Teile gehen dann an Modelle mit nativer Dateieingabe.
pdf.engineOptional; ohne explizites Modell gilt die konfigurierte Enginezuordnung, standardmäßig mistral-ocr. Nicht zugeordnete Engines und unbekannte Pluginfelder werden mit not_available abgelehnt.
pdf.modelGateway-Erweiterung: explizite Katalogmodell-ID oder Alias, höchstens 256 UTF-8-Bytes. Hat Vorrang vor Plugin-model und pdf.engine.
modelGateway-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:

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

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

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

{ "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. Der PII-Anschluss bleibt unverändert; dessen getrennte Tokenabrechnung erklärt der PII-Leitfaden.

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