# 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`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 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

{}

## Body: 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 (required): 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 (required): s1226

### s1226: string

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

{}

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

- type (required): s1227

### s1227: string

"document_url"

{}

oneOf: s910

### s910: object

One image.

{}

- image_url (required): s1228

### s1228: string

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

{}

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

- type (required): s1229

### s1229: string

"image_url"

{}

- model (required): 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

Distinct zero-based source page indices, at most 1000. Omitted processes all pages.
Image-only OCR renders at most 16 selected PDF pages using the configured internal
media worker; encrypted PDFs are unsupported and retries share the 16-call limit.

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

## Response 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 (required): s346

### s346: string

Gateway generation receipt ID.

{}

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

- model (required): s347

### s347: string

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

{}

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

- pages (required): 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 (required): s912

### s912: integer

Zero-based page index in the original source document.

int64

{"minimum":"0"}

```json
0
```

- markdown (required): 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 (required): s349

### s349: object

Provider-confirmed billable page quantity.

{}

- pages_processed (required): 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.

{}

## Response 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

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```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 (required): s238

### s238: object

What went wrong.

{}

```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 (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

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

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

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

Providers that serve the model (when `provider.only` excluded all of them).

{}

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

### s7: string

{}

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

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

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

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

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```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 (required): s636

### s636: string

Kind of problem, stable for programs.

"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 (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

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

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

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

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

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

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

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

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

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

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

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

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

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

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

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

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"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

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key

## Response 402: application/json

Insufficient customer credit or workspace budget for the page reservation

## Response 403: application/json

An organization, workspace or key policy denies the OCR model

## Response 404: application/json

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

## Response 408: application/json

Request upload, protected download or OCR provider timed out

## Response 409: application/json

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

## Response 413: application/json

Document, request or parsed response exceeds a bounded memory limit

## Response 429: application/json

Customer or provider quota exhausted; respect Retry-After

## Response 500: application/json

Unexpected internal error

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

## Response 502: application/json

OCR provider failed or returned invalid pages

## Response 503: application/json

No provider available, shared service unavailable, or gateway draining
