OCR

Dokumenttext über ein geroutetes OCR-Modell extrahieren, unabhängig von einer Chat-Inferenz.

Wann nutzen

OCR liefert Markdown aus gescannten PDFs und Dokumentbildern, ohne eine Chat-Antwort anzufordern.

Für die automatische Extraktion in einer Unterhaltung dient stattdessen der PDF-Parser.

Minimalbeispiel

Das Beispiel wählt die erste Seite einer synthetischen Inline-PDF. Als Ersatz nur Daten verwenden, deren Verarbeitung zulässig ist.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/ocr' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}'

node

const response = await fetch("https://api.tokenlane.de/v1/ocr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());

python

import os
import urllib.request

body = (r'''{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/ocr",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/ocr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "mistralai/mistral-ocr-4.1",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFszIDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAzMDAgMTUwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA0IDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjIgPj4Kc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFRva2VubGFuZSBkb2N1bWVudGF0aW9uIHNhbXBsZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzMTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjMKJSVFT0YK"
  },
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());

Anfrageformat

JSON an POST /v1/ocr senden, mit model und einem document im Mistral-Format:

{
  "model": "<ocr-modell>",
  "document": {
    "type": "document_url",
    "document_url": "data:application/pdf;base64,..."
  },
  "pages": [0]
}
FeldWert
documenttype: "document_url" mit einer Base64-PDF-Data-URL in document_url oder type: "image_url" mit image_url
pagesOptional; nullbasierte Seitenindizes
table_formatOptional; wählt die Tabellendarstellung

Das Ergebnis enthält pages[].markdown und usage_info. Zusätzliche Layoutdaten hängen vom Anbieter ab; Bildpositionen oder Dimensionsdaten werden nicht erfunden.

Grenzen

  • Insgesamt sind je Anfrage 16 OCR-Aufrufe einschließlich Wiederholungen möglich.
  • Image-Chat-OCR wie LightOnOCR benötigt Bilder. PDFs werden nur mit konfiguriertem internem Medienworker in Seitenbilder gerendert: höchstens 16 ausgewählte Seiten, 1.000 Quellseiten, 32 MiB, ohne Verschlüsselung. Ohne Renderer Bilder oder extrahierten Text senden.
  • File-IDs werden nicht aufgelöst.

Entfernte URLs

HTTP(S)-URLs lädt der geschützte Dokumentlader nur, wenn der Betreiber media_transport.fetch_enabled aktiviert hat; sonst wird die Anfrage vor einem OCR-Aufruf abgelehnt.

  • Jeder Weiterleitungsschritt prüft Hostregeln und öffentliche Zieladressen; private, lokale und interne Adressen bleiben gesperrt.
  • Es gelten die konfigurierten Download-, Gesamtdaten- und Zeitgrenzen, zusätzlich höchstens 32 MiB je Dokument.

Modell wählen

Ein aktuelles OCR-Modell wählen. OCR ist ein normales Katalogmodell mit Anbieterrouten, Regionsangaben und Fallback.

Spezialisierte OCR-Modelle und freigegebene Vision-LLMs können sich in Transkriptionsqualität, Kosten und Latenz unterscheiden; keines garantiert fehlerfreies Lesen. Key-, Anbieter-, Länder-, Rechtsraum-, Privacy- und Preisregeln gelten vor der Übermittlung.

Native OCR und LLM-Transkription erhalten beide die ursprünglichen Dokumentinhalte, nicht bereits geschwärzte Daten.

Tabellen

  • Einfache HTML-Tabellen werden entsprechend dem Routenprofil oder table_format: "markdown" in Markdown umgewandelt.
  • Komplexe oder beschädigte Tabellen bleiben unverändert.
  • Bei nativer OCR erhält table_format: "html" die Anbieterausgabe.

Vision-Chatmodelle als OCR

Ein gewöhnliches Vision-Chatmodell ist nur nutzbar, wenn der Betreiber dessen Route ausdrücklich mit ocr.llm freigibt. Bildeingabe allein ist keine OCR-Freigabe. Für ein solches Modell sieht eine Anfrage so aus:

{
  "model": "<betreiberfreigegebenes-visionmodell>",
  "document": { "type": "image_url", "image_url": "data:image/png;base64,..." },
  "pages": [0]
}

Im Plugin lautet die Entsprechung:

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

Dies sind Platzhalter, keine Verfügbarkeitszusage für ein Anbietermodell.

  • Direkte LLM-OCR akzeptiert aktuell eine begrenzte PNG (pages weglassen oder [0]) oder ein PDF über den gemeinsamen Medienworker.
  • table_format: "html" ist auf diesem Weg nicht unterstützt.
  • Für PDF-Seitenbilder gelten die Grenzen des gemeinsamen Worker-Vertrags. Ohne vom Betreiber konfigurierten Worker liefert PDF-Rendering 501 feature_unavailable, statt das PDF an einen Vision-Upstream weiterzureichen.

Details für Betreiber

  • Dasselbe Modell kann über eine vom Betreiber definierte Engine-Zuordnung den File-Parser versorgen.
  • Eine ocr.llm-Route benötigt OpenAI-Chat-Transport mit Text- und Bildeingabe und Textausgabe, JSON-Schema-Ausgabe oder erzwungene Tools, unveränderte Kontrollfelder, verlässliche Tokenusage und eine bestätigte Bildtokenformel.
  • Ein versionierter PageTask enthält Prompt, Schema und Ausgabegrenzen. Die mitgelieferte Revision ocr-page-extract-v1 fordert ausschließlich einen markdown-String an, mit 8.192 Ausgabetokens und 128 KiB strukturierter Ausgabe.
  • Die Katalogmodalitäten bleiben echt: ?output_modalities=ocr findet native OCR-Modelle, gewöhnliche Visionmodelle behalten Bild-/Textmodalitäten und sind nicht automatisch für OCR freigegeben.

Kosten

Seitenbasierte Routen veröffentlichen pricing.page, einen Preis je Seite, nicht je Million Tokens. Bildbasierte Chat-OCR wie LightOnOCR wird nach den Prompt- und Ausgabetokenpreisen des Modells berechnet. Die aktuellen Preise stehen im OCR-Katalog und auf jeder Modellseite.

AbrechnungAbgerechnete MengeBetrag
Je Seiteverarbeitete SeitenSeiten mal pricing.page
Je TokenEingabe- und AusgabetokensTokens mal Prompt- und Completion-Preis

Reservierung

  • Bei Seitenpreisen werden gezählte oder vorsichtig geschätzte Dokumentseiten reserviert; eine explizite Seitenauswahl reserviert deren Umfang.
  • Bei Tokenpreisen werden vor dem Aufruf der begrenzte Modellkontext und das Ausgabelimit reserviert.

Beleg

Der Generierungsbeleg hält Modell, Anbieter, unit: "page", tatsächliche Seitenmenge und Kosten unter preprocessing fest.

  • Bei Tokenpreisen nennt token_usage zusätzlich die bestätigten prompt_tokens und completion_tokens; die Seitenmenge wird nicht in Tokens umgedeutet.
  • Bei gewöhnlichen Vision-LLMs kennzeichnen execution: "llm_vision_transcribe" und task_version den Auftrag. unit: "page" bleibt die Arbeitsmenge, nicht die Tokenpreisbasis; token_usage hält tatsächliche Input-, Output- und Cachetokens sowie costs nach Preisbestandteil einschließlich Original-, Kunden- und Einkaufskosten fest.

Was kostenpflichtig bleibt

  • Bezahlte ungültige Ausgaben und Fallbackversuche.
  • Fehlende Tokenusage ist kein kostenloser Erfolg.
  • Scheitert eine spätere Inferenz, bleiben die Kosten abgeschlossener OCR-Aufrufe erhalten.

Häufige Fehler

Ein fehlendes OCR-Modell, eine nicht verfügbare Route, ungültige Dokumentdaten oder eine Richtliniensperre verhindern die Extraktion. Ohne OCR-Route gibt es keine automatische Extraktion.

Alle Feldprobleme und den remedy_hint prüfen. Eine Richtliniensperre darf nicht durch den Wechsel zum Plugin umgangen werden.

Bewährte Praxis

  • Für die Entwicklung synthetische Inline-Dokumente nutzen.
  • Die Dokumentgröße vor dem Senden begrenzen und explizite Seitenauswahlen bevorzugen, wenn nur ein Dokumentteil benötigt wird.
  • Die Generierungs-ID für Kostenprüfungen aufbewahren.
  • Dokument-Data-URLs und extrahierten Text niemals protokollieren.

Für KI-Agenten

Die aktuelle OCR-Endpunktreferenz nennt das genaue Schema, der Modellkatalog die Modell-IDs. OCR-Modelle nicht an Chat Completions senden und Modell-IDs nicht aus Engine-Namen ableiten.