# Extracts text from a PDF or image through an ordinary catalog model

Uses the same provider selection, policy, price caps, shared health and fallback as the
file-parser plugin. A document is a base64 PDF/image data URL; remote HTTP(S) documents
are downloaded by the protected media loader only when enabled by the operator. Pages
are distinct zero-based indices (at most 1000); decoded documents are at most 32 MiB.
PDF page counting is bounded and runs on a memory-budgeted blocking worker.
Image-only OCR routes require a configured internal media worker for PDF rendering,
with at most 16 selected pages and a shared 16-call limit including retries. Encrypted
PDFs cannot be rendered. In addition to native OCR models, this gateway extension accepts
ordinary vision chat routes only with an operator-approved versioned ocr.llm task, structured
output and verified token bounds. Such routes accept PNG pages and Markdown, not HTML tables;
PDFs use the same renderer and mandatory image admission per page, never raw PDF forwarding.
The catalog does not gain file capability. Native page or confirmed LLM token charges are
recorded before returning the response, even when paid output is unusable. Generation receipts
retain pages, execution, task version and actual token costs, never document or extracted text.
Operational logs likewise contain no document, extracted text or data URL.

`POST https://api.tokenlane.de/v1/ocr`

## Authentifizierung

[
  [
    {
      "name": "Authorization",
      "description": "API-Key als Bearer-Token im Header `Authorization`: `Authorization: Bearer sk-tl-v1-…`. Bestehende `sk-eu-`-Keys bleiben gültig. Fehlende, unbekannte oder abgelaufene Keys erhalten 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

## curl

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

## node

```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: `{
  "document": {
    "document_url": "data:application/pdf;base64,JVBERi0xLjQK...",
    "type": "document_url"
  },
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "document": {
    "document_url": "data:application/pdf;base64,JVBERi0xLjQK...",
    "type": "document_url"
  },
  "model": "mistralai/mistral-ocr-4.1",
  "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

```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: `{
  "document": {
    "document_url": "data:application/pdf;base64,JVBERi0xLjQK...",
    "type": "document_url"
  },
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    0
  ],
  "table_format": "markdown"
}`,
});
console.log(await response.text());
```

## Header: Idempotency-Key (optional)

Opt in to encrypted exact response replay for at most 10 minutes. Repeat the identical method, path and body with this key; replay is free and carries Idempotent-Replayed: true. Conflicting reuse returns 409.

### s0: string | null

{}

## Anfrageinhalt: application/json

```json
{
  "document": {
    "document_url": "data:application/pdf;base64,JVBERi0xLjQK...",
    "type": "document_url"
  },
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    0
  ],
  "table_format": "markdown"
}
```

### s26: object

Extracts a bounded PDF or image using a routed OCR model.

{}

```json
{
  "document": {
    "document_url": "data:application/pdf;base64,JVBERi0xLjQK...",
    "type": "document_url"
  },
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    0
  ],
  "table_format": "markdown"
}
```

- document (Pflichtfeld): s341

### s341: oneOf

Base64 data URL, or an HTTP(S) URL loaded only through the protected media downloader.

{}

oneOf: s909

### s909: object

A PDF document.

{}

- document_url (Pflichtfeld): s1226

### s1226: string

Base64 PDF data URL, or a protected HTTP(S) download URL.

{}

```json
"data:application/pdf;base64,JVBERi0xLjQK..."
```

- type (Pflichtfeld): s1227

### s1227: string

"document_url"

{}

oneOf: s910

### s910: object

One image.

{}

- image_url (Pflichtfeld): s1228

### s1228: string

Base64 image data URL, or a protected HTTP(S) download URL.

{}

```json
"data:image/png;base64,iVBORw0KGgo..."
```

- type (Pflichtfeld): s1229

### s1229: string

"image_url"

{}

- model (Pflichtfeld): s342

### s342: string

Public model ID or gateway alias for native OCR or an operator-approved vision task.
Ordinary chat models require explicit ocr.llm profile approval, image input, structured
output and bounded token accounting. The catalog's real modalities remain unchanged.

{}

```json
"mistralai/mistral-ocr-4.1"
```

- pages (optional): s343

### s343: array

Eindeutige, nullbasierte Quellseitenindizes, höchstens 1.000. Ohne Angabe werden alle Seiten verarbeitet. Bildbasierte OCR rendert höchstens 16 ausgewählte PDF-Seiten über den konfigurierten internen Medienworker; verschlüsselte PDFs werden nicht unterstützt, Wiederholungen teilen sich die Grenze von 16 Aufrufen.

{"minItems":"1","maxItems":"1000"}

```json
[
  0,
  2
]
```

### s1073: integer

int32

{"minimum":"0"}

- provider (optional): s344

### s344: object

Ordinary routing preferences, including max_price.page in EUR per processed page.

{}

- table_format (optional): s345

### s345: string

Table representation: markdown or html. Omitted uses the model's default.

{}

```json
"markdown"
```

## Antwort 200: application/json

Mistral-compatible pages, markdown, tables, dimensions and usage_info; x-generation-id identifies the confirmed receipt

```json
{
  "id": "gen-example",
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    {
      "dimensions": {
        "dpi": 200,
        "height": 2200,
        "width": 1700
      },
      "index": 0,
      "markdown": "# Example",
      "tables": []
    }
  ],
  "usage_info": {
    "pages_processed": 1
  }
}
```

### s27: object

Mistral-compatible extraction result; future native fields remain available.

{}

```json
{
  "id": "gen-example",
  "model": "mistralai/mistral-ocr-4.1",
  "pages": [
    {
      "dimensions": {
        "dpi": 200,
        "height": 2200,
        "width": 1700
      },
      "index": 0,
      "markdown": "# Example",
      "tables": []
    }
  ],
  "usage_info": {
    "pages_processed": 1
  }
}
```

- id (Pflichtfeld): s346

### s346: string

Gateway generation receipt ID.

{}

```json
"gen-example"
```

- model (Pflichtfeld): s347

### s347: string

Resolved public model ID, not the provider's private model name.

{}

```json
"mistralai/mistral-ocr-4.1"
```

- pages (Pflichtfeld): s348

### s348: array

Extracted pages in source order; selected pages keep their original indices.

{}

### s174: object

One extracted page in native Mistral form.

{}

- dimensions (optional): s911

### s911: object

Native page dimensions, including dpi, width and height when available.

{}

- index (Pflichtfeld): s912

### s912: integer

Zero-based page index in the original source document.

int64

{"minimum":"0"}

```json
0
```

- markdown (Pflichtfeld): s913

### s913: string

Extracted markdown; table references may point into tables.

{}

```json
"# Example"
```

- tables (optional): s914

### s914: array | null

Native table objects, including their IDs, format and content when available.

{}

### s1230: any

{}

- * (optional): s915

### s915: any

Additional native page fields (for example image metadata).

{}

- usage_info (Pflichtfeld): s349

### s349: object

Provider-confirmed billable page quantity.

{}

- pages_processed (Pflichtfeld): s916

### s916: integer

Confirmed pages processed, between 1 and 1000.

int64

{"minimum":"1","maximum":"1000"}

```json
1
```

- * (optional): s917

### s917: any

Additional native usage fields, for example document_size_bytes.

{}

- * (optional): s350

### s350: any

Additional native provider fields, preserved without using them as billing data.

{}

## Antwort 400: application/json

Malformed JSON or invalid model/document/pages/table_format; metadata.issues lists every validation issue

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Jede Antwort mit HTTP-Status ab 400 hat diese Struktur im Fehlerformat von OpenRouter. Alle Gateway-Erweiterungen stehen unter `error.metadata`, damit OpenRouter-Clients keine unbekannte äußere Struktur erhalten. Der Abschnitt „Fehler“ in der Einführung nennt alle Fehlertypen.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (Pflichtfeld): s238

### s238: object

Fehlerbeschreibung.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (Pflichtfeld): s633

### s633: integer

HTTP-Status der Antwort als Zahl.

int32

{"minimum":"0"}

```json
400
```

- message (Pflichtfeld): s634

### s634: string

Fehlerbeschreibung auf Englisch. Bei mehreren Problemen werden das erste und die Anzahl weiterer genannt. Alle stehen unter `metadata.issues`. Der Text kann sich ändern. Im Code stattdessen `metadata.type` auswerten.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Maschinenlesbare Details: Fehlertyp, Anfrage-ID, alle Probleme, ein Lösungsvorschlag und bei Provider-Fehlern der betroffene Provider. Bei Gateway-Fehlern immer vorhanden.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Provider, die das Modell anbieten, wenn `provider.only` alle ausgeschlossen hat.

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

### s7: string

{}

- docs_url (Pflichtfeld): s640

### s640: string

Link zum Abschnitt dieses Fehlertyps in der Dokumentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

Routing-Schritt, nach dem keine Route übrig blieb. Nur bei Routing-Fehlern.

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Alle erkannten Probleme der Anfrage, damit sie gemeinsam behoben werden können. Höchstens 20 Einträge. Bei Routing-Fehlern ein Eintrag je ausgeschlossener Route, bei `no_provider_available` einer je fehlgeschlagenem Versuch.

{}

### s123: object

Ein Anfrageproblem, ein Ausschlussgrund einer Route oder ein fehlgeschlagener Versuch.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (Pflichtfeld): s636

### s636: string

Art des Problems. Für Programme stabil.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (Pflichtfeld): s637

### s637: string

Problembeschreibung auf Englisch mit dem Feld und, sofern kurz, dem gesendeten Wert.

{}

```json
"temperature must be at most 2, got 5"
```

- path (Pflichtfeld): s638

### s638: string

Position des Problems: JSONPath des Felds im Anfrageinhalt, beispielsweise `$.messages[2].content[0].image_url.url`, oder `query.<name>` bei einem Abfrageparameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Sichere Provider-Diagnosen, einheitlich für HTTP-Fehler und finale Stream-Ereignisse.

{}

oneOf: s1158

### s1158: object

Provider-Diagnosen ohne vom Provider verfassten Text. HTTP-Fehler und finale SSE-Fehler verwenden dieselbe Struktur. Beliebige Upstream-Meldungen und Metadaten werden verworfen.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (Pflichtfeld): s1299

### s1299: string

Gateway-Klassifizierung anhand von HTTP-Status und erkannten Dialektkennungen.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exakte Kennung aus der festen Liste des konfigurierten Dialekts. Beliebige andere Werte werden entfernt.

{}

```json
"rate_limit_exceeded"
```

- provider_name (Pflichtfeld): s1301

### s1301: string

Konfigurierter Provider-Name. Nie ein Name aus dem Upstream-Antwortinhalt.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Begrenzte Wartezeit in Sekunden aus dem Upstream-Header Retry-After, sofern vorhanden und numerisch.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s1303

### s1303: boolean

Ob der klassifizierte Fehler vorübergehend sein kann. Bei unbekannten Fehlern wird ein sinnvoller erneuter Versuch nicht zugesichert.

{}

- status (optional): s1304

### s1304: integer

Tatsächlich vom Upstream empfangener HTTP-Status, einschließlich 200 bei nativen Fehlern. Fehlt, wenn kein HTTP-Status verfügbar ist.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

Fehlgeschlagener Provider wie im Antwortfeld `provider`. Nur bei Provider-Fehlern.

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserviertes Feld für OpenRouter-Kompatibilität. Das Gateway befüllt es nie. Freier Provider-Text wird bewusst nicht ausgegeben. Stattdessen provider_error verwenden.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

Ein konkreter Lösungsvorschlag, beispielsweise die ähnlichste Modell-ID bei einem Tippfehler.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (Pflichtfeld): s647

### s647: string

Anfrage-ID. Identisch mit dem Antwortheader `x-request-id`. Diese ID bei Supportanfragen angeben.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Unter `provider.only` genannte Provider, wenn dadurch alle Routen ausgeschlossen wurden.

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Wartezeit vor einem erneuten Versuch in Sekunden. Wird bei 429 und 503 auch als Header `Retry-After` gesendet.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s650

### s650: boolean

Ob dieselbe unveränderte Anfrage bei einem erneuten Versuch erfolgreich sein kann, beispielsweise nach einer Zeitüberschreitung oder einem Anfragelimit. Im Gegensatz zu Fehlern, die eine geänderte Anfrage erfordern.

{}

- routing_funnel (optional): s651

### s651: array

Eingrenzung der Provider durch das Routing. Jeder Schritt nennt die Anzahl verbleibender Routen. Nur bei Routing-Fehlern, im selben Format wie bei OpenRouter.

{}

### s200: object

Ein Routing-Schritt wie unter `routing_funnel` von OpenRouter.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (Pflichtfeld): s979

### s979: integer

Anzahl der nach diesem Schritt verbleibenden Routen beziehungsweise Modell-Provider.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

Anfragefeld, nach dem der Schritt gefiltert hat.

{}

```json
"provider.only"
```

- step (Pflichtfeld): s981

### s981: string

Name des Schritts wie bei OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (Pflichtfeld): s652

### s652: string

Stabiler Fehlertyp für die Auswertung im Code. Siehe „Fehler“ in der Einführung. Meldungen können sich ändern, der Typ bleibt stabil.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organisation des API-Keys, sofern der Key erkannt wurde.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Antwort 401: application/json

API-Key fehlt, ist ungültig oder abgelaufen.

## Antwort 402: application/json

Insufficient customer credit or workspace budget for the page reservation

## Antwort 403: application/json

An organization, workspace or key policy denies the OCR model

## Antwort 404: application/json

No OCR route satisfies provider, region, privacy or price restrictions

## Antwort 408: application/json

Request upload, protected download or OCR provider timed out

## Antwort 409: application/json

Idempotency conflict, operation in progress, or replay unavailable; see remedy_hint

## Antwort 413: application/json

Document, request or parsed response exceeds a bounded memory limit

## Antwort 429: application/json

Customer or provider quota exhausted; respect Retry-After

## Antwort 500: application/json

Unerwarteter interner Fehler

## Antwort 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Antwort 502: application/json

OCR provider failed or returned invalid pages

## Antwort 503: application/json

No provider available, shared service unavailable, or gateway draining
