# Create a chat completion

Sends the conversation to the model and returns its answer, as one JSON response or, with
`stream: true`, as server-sent events while it is generated. Same format as OpenRouter.

The gateway picks a European provider of the model (respecting `provider` preferences) and,
if it fails before sending output, tries the next one and then the `models` fallbacks.
The body is validated completely before any provider is called; every problem is listed
in `error.metadata.issues`. Unknown parameters are ignored and named in `x-ignored-params`.
`usage.cost` is the price of the request in EUR. For a provider with prices in another
currency, `usage.cost_details.original` adds its costs in that currency and the exchange
rate (version and time) the EUR amounts were converted with.

**PDFs:** If no selected chat route accepts file input, PDFs are automatically
extracted through file-parser when bridge mode, provider policy, data class and the
automatic reservation ceiling permit it. OCR must match the compliance and ZDR of every
admitted chat target. `plugins: [{"id":"file-parser","enabled":false}]` opts out unless
locked by policy. Refused/failed automatic work preserves the native 404; `bridge_failed`
names data_class, cost_cap, format or bridge_error. Explicit
`plugins: [{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]` extracts
up to eight PDFs before inference through the engine's configured OCR model. Inline
base64 PDFs are accepted; remote HTTP(S) PDFs require `media_transport.fetch_enabled`.
The protected loader checks hosts and public addresses at every redirect, byte limits
and deadlines. Disabled fetching, file IDs and unmapped engines fail with field issues
and a remedy hint. Extracted text is limited to 4 MiB and checked against
the model's context. Extraction runs once across fallbacks, costs `usage.cost_details.ocr_cost`
in EUR (included in total cost), and also works before streaming. With missing inference
usage, the known OCR charge is returned without inventing a total or token counts.
With fetching enabled, allowed automatic URL file bridges load once only when native
admission lacks file input; explicit file-parser also runs on native file models.
Content-Type and signature must agree; names are not
type evidence. Fetch failures keep media errors; unsupported formats keep the native 404
with bridge_failed=format. Loading is free and adds no bridge entry.
UTF-8 files of type text/plain, text/markdown, text/html, text/csv or application/json
use the same file-parser policy and opt-out, automatically only when native file admission
fails, or explicitly through the plugin. They are decoded locally for free, without OCR:
the text part is `[File <name>, <mime>]` followed by a newline and the content. A UTF-8 BOM
is removed; HTML is unchanged. All text files together may contain at most 4 MiB.
Executed file-parser bridges are announced in `x-tokenlane-bridges` before any response body,
including SSE. `usage.cost_details.bridge_cost` is their EUR aggregate (currently equal
to the compatibility field `ocr_cost`), not an additional charge. `bridges[]` contains
the same `GenerationPreprocessing` entries as `GET /v1/generation`: `id=file-parser`,
model, provider, unit, quantity and exact `cost_pico_eur`. No bridge means no new fields.

**Audio:** `plugins: [{"id":"media"}]` transcribes inline `input_audio` for a model
without audio input over the cheapest permitted configured transcription route, before
the first byte, into a text part `[Audio transcript] …`; billed per started second as a
`bridges[]` entry `id=media`, `kind=transcription`, `unit=second`. Models with audio
input receive the audio natively. A failed transcription keeps the original 404 with
`bridge_failed`. As for OCR, only paid provider work is billed: transcriptions the
provider charged in this request (earlier audio parts, or a paid invalid result) remain
billed, own fees are waived on the failed request.

**PII:** `plugins: [{"id":"pii-redact","entities":["email"],"restore":true}]` scans
bounded text conversations with the configured approved EU detector. Key/organization
rules can enforce redaction per route; fallbacks reevaluate those rules. Input is limited
to 64 KiB and 128 text parts; tools, unextracted media and unscanned free-text options fail
closed. `usage.cost_details` includes `pii_cost`, `pii_characters`, `pii_calls` and
`pii_duration_ms`. Text output can be restored across stream chunks with bounded memory.
For `json_object` content, restored entities are JSON-escaped, including across chunks.
Detector failures block by default; optional fail-open never bypasses enforced policies.

**Broken JSON:** by default (no plugin needed) and with `response_format` `json_object` or
`json_schema`, a non-streaming answer whose content is not valid JSON (code fences,
trailing commas, cut-off output) is repaired; valid JSON and content that cannot be
repaired are returned unchanged, and streams are never changed.
`plugins: [{"id": "response-healing", "enabled": false}]` turns the repair off.

**Unusable answers:** a well-formed non-streaming answer that finished with `stop` but has
no content, tool call or refusal (only reasoning, or nothing), or that repeats itself until
the output limit, counts as a failed attempt: the next route is tried and the route's
circuit breaker counts a failure. Without another route the error is
`provider_invalid_response`; the customer is not charged for it (C-333). An answer cut
off at the output limit before any content is
legitimate (too small `max_tokens`) and returned with an `x-remedy-hint` header. The rules
are configuration data (`answer_checks`).

**Which provider is tried first:** `provider.sort` orders the providers of the model by
`price` (lowest price of one input plus one output token, in EUR), `latency` (shortest time
until the first byte of a streamed answer) or `throughput` (most output tokens per second).
Providers named in `provider.order` still come first. If a provider fails before sending
output, the next one is tried, unless `provider.allow_fallbacks` is `false`.

**Tariff variants:** a provider may offer a model in several tariffs, for example a cache
tariff with cheap cache reads but higher base prices. Each variant is a route of its own
with the endpoint tag `<provider>/<variant>` (`GET /v1/models` lists it as `routes[].tag`,
e.g. `grunden/cache`). A variant serves a request only when `provider.only` or
`provider.order` names its tag; it never takes part in fallback or `provider.sort` and is
excluded from the model-wide catalog price unless the model has no standard route.
A provider ID alone names the standard route;
in `provider.ignore` it excludes the variants as well. The object form
`{"by": "price", "partition": "none"}` sorts the providers of `model` and of all `models`
fallbacks together, so a cheaper fallback model may answer first; the default
`"partition": "model"` keeps fallback models behind `model`. Differences from OpenRouter:
latency and throughput are shared across gateway nodes through Valkey, as the
median of each provider's last 32 answers within 30 minutes; only streamed answers count
for latency, and providers without measurements come after measured ones, in the gateway's
default order. `exacto` is accepted but keeps the default order (no ranking by tool-calling
quality yet).

`POST https://api.tokenlane.de/v1/chat/completions`

## 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/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "max_tokens": 200,
  "messages": [
    {
      "content": "Answer in one sentence.",
      "role": "system"
    },
    {
      "content": "What is the capital of Portugal?",
      "role": "user"
    }
  ],
  "model": "deepseek/deepseek-v4-flash-0731",
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  },
  "temperature": 0.2
}'
```

## node

```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({
  "max_tokens": 200,
  "messages": [
    {
      "content": "Answer in one sentence.",
      "role": "system"
    },
    {
      "content": "What is the capital of Portugal?",
      "role": "user"
    }
  ],
  "model": "deepseek/deepseek-v4-flash-0731",
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  },
  "temperature": 0.2
}, {});
console.log(response);
```

## python

```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'''{
  "max_tokens": 200,
  "messages": [
    {
      "content": "Answer in one sentence.",
      "role": "system"
    },
    {
      "content": "What is the capital of Portugal?",
      "role": "user"
    }
  ],
  "model": "deepseek/deepseek-v4-flash-0731",
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  },
  "temperature": 0.2
}''')
response = client.chat.completions.create(
    model=body["model"],
    messages=body["messages"],
    max_tokens=body["max_tokens"],
    temperature=body["temperature"],
    extra_body=json.loads(r'''{
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  }
}''')
)
print(response)
```

## vercel

```vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
  model: tokenlane("deepseek/deepseek-v4-flash-0731"),
  system: "Answer in one sentence.",
  messages: [
  {
    "content": "What is the capital of Portugal?",
    "role": "user"
  }
],
  maxOutputTokens: 200,
  temperature: 0.2,
  providerOptions: { tokenlane: {
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  }
} },
});
console.log(result.text);
```

## header: Idempotency-Key (optional)

Explicit opt-in to encrypted response replay across gateway nodes. One 1..=255 printable ASCII value per logical operation, scoped to this API key ID. Reuse the same method, path and normalized body. Completed responses are retained for at most 10 minutes; replay is free and creates no generation. Conflicting content or unavailable replay returns 409. A successful replay carries Idempotent-Replayed: true and preserves the original request and generation IDs. See /docs/guides/idempotency.

### s0: string | null

{}

## header: x-session-id (optional)

Groups the generation into a session, listed by `GET /v1/sessions/{id}`; 1 to 256 characters from letters, digits, `-`, `_`, `.` and `:`. The body field `session_id` takes precedence.

## Body: application/json

```json
{
  "max_tokens": 200,
  "messages": [
    {
      "content": "Answer in one sentence.",
      "role": "system"
    },
    {
      "content": "What is the capital of Portugal?",
      "role": "user"
    }
  ],
  "model": "deepseek/deepseek-v4-flash-0731",
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  },
  "temperature": 0.2
}
```

### s11: object

A conversation and its generation options, in OpenRouter's format: existing OpenRouter and
OpenAI clients work by changing only the base URL and the API key.

Besides the fields listed here, every parameter of OpenRouter's chat API is accepted, for
example `max_tokens` (upper limit of output tokens), `temperature` (0 to 2), `top_p`,
`stop`, `seed`, `tools` and `tool_choice`, `response_format` (`json_object` or
`json_schema`), `reasoning` (`effort`, `max_tokens`, `exclude`) and `provider` (routing
preferences: `only`, `ignore`, `order`, `allow_fallbacks`, `require_parameters`,
`max_price`, `sort`). Differences from OpenRouter:

- **Requested controls in receipts:** `n` and `transforms` are validated and recorded
  as requested, but remain listed in `x-ignored-params` and do not affect execution.
  The gateway continues to request a single generation without message transforms.
- **Output bound:** `max_tokens` and `max_completion_tokens` express one upper bound,
  reasoning included. With two valid positive integers the smaller wins; with one,
  that value wins. Suitable routes receive one native field with this bound, including
  after aliases, renames and fallback. A string or zero remains a tolerated ignored input.
  `provider.require_parameters: true` excludes routes whose mappings cannot preserve
  total-output semantics. Reservation uses the effective bound, not the larger alias;
  actual provider usage is settled separately and is not truncated to the reservation.
- **Prices in EUR:** `provider.max_price` is in EUR per million tokens
  (`{"prompt": 0.5, "completion": 2}`), not USD; costs in `usage` are EUR as well.
  Price limits and `provider.sort: "price"` use exact exchange-rate quotients before
  rounding; a zero price limit excludes every positive price.
- **Checked before any provider is called:** the whole body is validated first, and every
  problem is listed in `error.metadata.issues` (400 `invalid_parameter`). Requests
  OpenRouter passes on and lets the provider reject (unknown role, unknown
  `response_format`, broken tool schema, `tool_choice` naming an undefined tool, invalid
  media URL or base64) fail here at once, without cost.
  Response and tool schemas are structurally checked within 32 JSON levels, 4,096
  values and 256 KiB of content; field names are limited to 256 bytes. References must
  resolve locally. Boolean subschemas and recursive local references are supported;
  unknown vocabulary keywords remain provider-specific. This is not instance validation.
  Locally available PNG/JPEG/GIF/WebP headers and dimensions are checked within 64 KiB,
  including the first PNG chunk's CRC; compressed pixel data is not decoded.
- **Mixed provider failures:** a definitive content rejection plus only unclassified
  failures returns 400 with per-provider issues and no Retry-After. Explicitly profiled
  outages and transport timeouts retain retryable service-failure semantics.
- **Unknown parameters** are ignored, as on OpenRouter, and named in the
  `x-ignored-params` response header, so typos do not go unnoticed.
  `usage: {"include": true}` is accepted silently: usage is always included.
- **Provider slugs** in `provider.only`, `provider.ignore` and `provider.order` are
  matched case-insensitively, including variant tags. Failed only/order filters suggest
  a close serving slug when one exists; unknown optional preferences remain harmless.
- **Reasoning compatibility:** legacy `include_reasoning: false` maps to
  `reasoning.exclude: true` (true maps to false); an explicit `reasoning.exclude` wins.
  A route unable to disable reasoning still hides its output and charges actual tokens;
  the unfulfilled control (`reasoning.effort`, `reasoning.enabled` or
  `reasoning.max_tokens`) is named in `x-ignored-params` for the answering route.
  Messages and stream deltas expose `reasoning_details` alongside reasoning text:
  plain text becomes an indexed reasoning.text block; original structured blocks and
  their signatures, IDs and order are preserved, never replaced with synthesized text.
  Excluding reasoning removes both views.
- **Balanced routing:** without a request or policy sort and without `provider.order`,
  otherwise equivalent routes are sampled without replacement using inverse-square weights
  of their EUR prompt-plus-completion token price. Routes without a failure in the last
  30 seconds are preferred. Existing eligibility and routing tiers still apply.
- **`provider.sort`:** `price` sorts by EUR prompt-plus-completion price. `latency` and
  `throughput` use shared Valkey measurements across gateway instances: the median of the
  last 32 answers per provider within 30 minutes. Unmeasured providers come last.
  `exacto` is accepted but preserves configured order, not Balanced selection.
- **Soft performance preferences:** `provider.preferred_max_latency` (seconds) and
  `provider.preferred_min_throughput` (output tokens/second) accept a non-negative number
  for p50, or an object with `p50`, `p75`, `p90`, `p99` thresholds. Shared measurements use
  the last 32 answers within five minutes. Missing measurements or any missed threshold
  move a route behind otherwise equivalent matching routes, never exclude it. Latency is
  evaluated at millisecond precision, throughput at thousandths of a token/second.
- **Routing variants:** `:nitro` selects throughput sorting and `:floor` price sorting;
  an explicit `provider.sort` wins. The primary model's variant sets sorting for the whole
  request, including fallback models. Variants are removed before model-policy checks;
  they do not bypass `allowed_models`. Responses name the resolved base model, while
  generation receipts retain the requested suffix.
- **Required parallel tool calls:** with `provider.require_parameters: true`,
  `parallel_tool_calls: true` requires a route with parallel tool support. `false` also
  permits serial tool routes, provided the parameter reaches the provider. Null or an
  absent field imposes no parallel-tool requirement.
- **Required tool choice:** with `provider.require_parameters: true`, `tool_choice: "required"`
  or a named function excludes routes marked as unable to enforce forced choice. Such
  routes may still accept `auto`/`none`; without require_parameters, choice is forwarded
  subject to the route's ordinary parameter mapping.
- **Sessions:** `session_id` (or the `x-session-id` header; the field wins) groups
  generations, listed by `GET /v1/sessions/{id}`, and is never sent to the provider. It
  must have 1 to 256 characters from letters, digits, `-`, `_`, `.` and `:`, otherwise the
  request fails with 400 `invalid_parameter`.
- **Assistant reasoning history:** `reasoning` (or `reasoning_content`) is text;
  `reasoning_details` is an ordered array of reasoning.text, reasoning.summary and
  reasoning.encrypted blocks. Only assistant messages may carry these fields. A route
  maps plaintext or explicitly accepts the original provider-bound details; otherwise
  unsupported reasoning is removed before sending. Text mappings never expose opaque
  or summary blocks as plaintext. `reasoning.exclude` only affects new output.
- **Limits:** the body may have at most 50 MiB; see "Limits" in the introduction.
- **Plugins and server tools:** `plugins` never reaches the provider. `response-healing`
  and `file-parser` run in the gateway. `web` (web search) works only with a model whose
  provider offers it and a key whose policy allows `web_search`; it takes `max_results`
  (1 to 20), `max_uses` (1 to 100, capped by the provider route) and `engine` (`auto` or
  `native`), and each search is charged on top of the tokens. Explicit max_uses and
  max_results are hard routing requirements even with provider.require_parameters false:
  a route must translate them or be excluded before any upstream call. If no route can
  enforce them, 404 no_endpoint identifies the unsupported limits and suggests a remedy.
  Missing or null limits use route defaults; a disabled plugin requests no search.
  Other OpenRouter plugins,
  server tools in `tools` (e.g. `openrouter:web_search`), a `tool_choice` naming one, and
  `web_search_options` fail with 400 `invalid_parameter` (issue code `not_available`)
  instead of running unbilled; a plugin with `enabled: false` is accepted.
  `stop_server_tools_when` is ignored (named in `x-ignored-params`).
- **PDF extraction:** `plugins: [{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]`
  converts up to eight PDF file parts into text before inference, using the engine's
  configured OCR model. Missing pdf/engine defaults to mistral-ocr. Inline base64 PDFs
  are accepted; remote HTTP(S) PDFs require `media_transport.fetch_enabled`. The protected
  loader enforces host policy, public destination addresses at every redirect, byte limits
  and deadlines. Disabled fetching, file IDs, unmapped engines and non-PDF media fail with
  collected issues and a remedy hint. The extracted text is limited to 4 MiB per request,
  is checked against the model's context,
  and is reused across fallbacks. OCR costs are included in usage.cost and separately in
  usage.cost_details.ocr_cost (EUR), with ocr_documents. With missing inference usage,
  only the known OCR detail is returned; no token counts or total cost are invented.
  Streams begin after extraction and then pass through without buffering. Disabled
  file-parser leaves file parts to routes with native file support.
  Where the operator maps an engine to `tokenlane/pdf-text`, the gateway's own media worker
  reads the PDF text layer instead of OCR (receipt kind `text_layer`). Unlike OCR, this
  includes text that is invisible on the rendered page (white or hidden text, OCR layers of
  scans). Automatic selection uses it first and falls back to OCR for documents with pages
  without enough text or mostly scanned pages, named by the receipt's `fallback`.
- **Tool calls are checked by default** (`tool-call-healing`; unlike OpenRouter, which
  passes them unchanged): with `tools`, every returned call must name one of them, carry a
  JSON object as arguments and include the schema's `required` arguments. Unambiguous
  defects are repaired (leaked model-format markers such as `</arg_value>` in names or
  arguments, `<arg_key>`/`<arg_value>` pairs, almost-JSON); valid calls stay byte-identical.
  A call that cannot be repaired is a failed attempt: the next route is tried, otherwise
  502 `provider_invalid_response`. Streams are checked at the end; a call that is not
  valid as sent ends the stream with an error event.
  `plugins: [{"id": "tool-call-healing", "enabled": false}]` passes tool calls unchanged.
- **Broken JSON is repaired by default** (`response-healing`, no plugin needed; unlike
  OpenRouter, where it is opt-in) when
  `response_format` is `json_object` or `json_schema`: it removes Markdown code fences and
  text around the JSON, trailing, doubled and missing commas, escapes raw line breaks in
  strings, and completes output that was cut off (closes strings and brackets, drops an
  unfinished member). Valid JSON is never changed. Content that cannot be repaired is
  returned unchanged. Only for non-streaming requests: streams are passed on unchanged,
  because repairing them would hold back the answer.
  `plugins: [{"id": "response-healing", "enabled": false}]` turns it off for the request.

{}

```json
{
  "max_tokens": 200,
  "messages": [
    {
      "content": "Answer in one sentence.",
      "role": "system"
    },
    {
      "content": "What is the capital of Portugal?",
      "role": "user"
    }
  ],
  "model": "deepseek/deepseek-v4.1-flash",
  "provider": {
    "max_price": {
      "completion": 2,
      "prompt": 0.5
    }
  },
  "temperature": 0.2
}
```

- messages (required): s278

### s278: array

The conversation so far, oldest message first. At least one message; the model answers
the last one.

{}

### s86: oneOf

One message of the conversation; `role` decides which fields it has. User and tool messages
may contain images, audio, video and files if the model accepts them
(`architecture.input_modalities` in `GET /v1/models`).

{}

```json
{
  "content": "What is the capital of Portugal?",
  "role": "user"
}
```

oneOf: s540

### s540: object

Instructions that steer the whole conversation.

{}

```json
{
  "content": "Answer in one sentence.",
  "role": "system"
}
```

- content (required): s556

### s556: anyOf

Text as a string, or as an array of text parts (for example to mark a long, unchanging
part for prompt caching with `cache_control`).

{}

anyOf: s7

### s7: string

{}

anyOf: s1139

### s1139: array

{}

### s83: object

A piece of text.

{}

```json
{
  "text": "What is shown in this picture?",
  "type": "text"
}
```

- text (required): s531

### s531: string

A piece of text.

{}

- type (required): s532

### s532: string

Kind of the part; names the field that carries the content.

"text"

{}

```json
"text"
```

- * (optional): s533

### s533: any

Further fields (for example `cache_control`), passed to the provider as sent.

{}

- role (required): s557

### s557: string

Who speaks: decides how the model treats the message.

"system"

{}

```json
"system"
```

- * (optional): s558

### s558: any

Further message fields (for example `name` or `cache_control`), passed to the
provider as sent.

{}

oneOf: s541

### s541: object

What the user says or asks.

{}

```json
{
  "content": "What is the capital of Portugal?",
  "role": "user"
}
```

- content (required): s563

### s563: anyOf

Text as a string, or an array of parts that mixes text with images, audio, video and
files. Media need a model that accepts them (`architecture.input_modalities` in
`GET /v1/models`); otherwise the request fails with 404 `no_endpoint`.

{}

anyOf: s7

anyOf: s1141

### s1141: array

{}

### s82: oneOf

One part of a message; `type` decides which field carries the content. Media URLs are
checked before any provider is called: they must be `http(s)` URLs with a host or base64
data URLs (`data:<media type>;base64,<data>`), otherwise 400 `invalid_parameter` names the
part, for example `$.messages[0].content[1].image_url.url`.

{}

```json
{
  "image_url": {
    "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
  },
  "type": "image_url"
}
```

oneOf: s525

### s525: object

A piece of text.

{}

```json
{
  "text": "What is shown in this picture?",
  "type": "text"
}
```

- text (required): s531

A piece of text.

- type (required): s532

Kind of the part; names the field that carries the content.

- * (optional): s533

Further fields (for example `cache_control`), passed to the provider as sent.

oneOf: s526

### s526: object

An image by URL or as a data URL.

{}

```json
{
  "image_url": {
    "detail": "auto",
    "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
  },
  "type": "image_url"
}
```

- image_url (required): s522

### s522: object

An image as an http(s) URL or a base64 data URL. Its size is limited only by the 50 MiB request body; large images are better sent as URLs.

{}

```json
{
  "detail": "low",
  "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
}
```

- url (required): s830

### s830: string

An `http(s)` URL with a host, which the provider downloads, or a base64 data URL
(`data:image/png;base64,...`). Anything else fails with 400 `invalid_parameter`
(`invalid_url` or `invalid_base64`). Inline PNG/JPEG/GIF/WebP also require readable
headers and nonzero dimensions within 64 KiB; PNG checks the IHDR CRC. This header
check does not decompress or certify the compressed pixel data.

{}

```json
"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
```

- * (optional): s831

### s831: any

Further options, passed to the provider as sent, for example `detail` (`low`, `high`,
`auto`) for images.

{}

- type (required): s523

### s523: string

Kind of the part; names the field that carries the content.

"image_url"

{}

```json
"image_url"
```

- * (optional): s524

### s524: any

Further fields (for example `cache_control`), passed to the provider as sent.

{}

oneOf: s527

### s527: object

Audio as base64 data.

{}

```json
{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "type": "input_audio"
}
```

- input_audio (required): s516

### s516: object

Audio as base64 data with its format.

{}

```json
{
  "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
  "format": "wav"
}
```

- data (required): s780

### s780: string

The audio file, base64-encoded (no data URL prefix). Invalid base64 fails with 400
`invalid_parameter` before any provider is called.

{}

- format (required): s781

### s781: string

Format of the audio, for example `wav` or `mp3`; which formats work depends on the
provider.

{}

```json
"wav"
```

- * (optional): s782

### s782: any

Further options, passed to the provider as sent.

{}

- type (required): s517

### s517: string

Kind of the part; names the field that carries the content.

"input_audio"

{}

```json
"input_audio"
```

- * (optional): s518

### s518: any

Further fields (for example `cache_control`), passed to the provider as sent.

{}

oneOf: s528

### s528: object

A video with the older `input_video` type.

{}

```json
{
  "type": "input_video",
  "video_url": {
    "url": "https://storage.example.eu/clips/demo.mp4"
  }
}
```

- type (required): s823

### s823: string

Always `input_video`.

"input_video"

{}

```json
"input_video"
```

- video_url (required): s824

### s824: object

The video as an http(s) URL or a base64 data URL.

{}

```json
{
  "detail": "low",
  "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
}
```

- url (required): s830

An `http(s)` URL with a host, which the provider downloads, or a base64 data URL
(`data:image/png;base64,...`). Anything else fails with 400 `invalid_parameter`
(`invalid_url` or `invalid_base64`). Inline PNG/JPEG/GIF/WebP also require readable
headers and nonzero dimensions within 64 KiB; PNG checks the IHDR CRC. This header
check does not decompress or certify the compressed pixel data.

- * (optional): s831

Further options, passed to the provider as sent, for example `detail` (`low`, `high`,
`auto`) for images.

- * (optional): s825

### s825: any

Further fields, passed to the provider as sent.

{}

oneOf: s529

### s529: object

A video by URL or as a data URL.

{}

```json
{
  "type": "video_url",
  "video_url": {
    "url": "https://storage.example.eu/clips/demo.mp4"
  }
}
```

- type (required): s534

### s534: string

Kind of the part; names the field that carries the content.

"video_url"

{}

```json
"video_url"
```

- video_url (required): s535

### s535: object

A video as an http(s) URL or a base64 data URL.

{}

```json
{
  "detail": "low",
  "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
}
```

- url (required): s830

An `http(s)` URL with a host, which the provider downloads, or a base64 data URL
(`data:image/png;base64,...`). Anything else fails with 400 `invalid_parameter`
(`invalid_url` or `invalid_base64`). Inline PNG/JPEG/GIF/WebP also require readable
headers and nonzero dimensions within 64 KiB; PNG checks the IHDR CRC. This header
check does not decompress or certify the compressed pixel data.

- * (optional): s831

Further options, passed to the provider as sent, for example `detail` (`low`, `high`,
`auto`) for images.

- * (optional): s536

### s536: any

Further fields (for example `cache_control`), passed to the provider as sent.

{}

oneOf: s530

### s530: object

A document such as a PDF, by URL, data URL or file ID.

{}

```json
{
  "file": {
    "file_data": "https://storage.example.eu/docs/invoice.pdf",
    "filename": "invoice.pdf"
  },
  "type": "file"
}
```

- file (required): s519

### s519: object

A document such as a PDF.

{}

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

- file_data (optional): s657

### s657: string

The file as an `http(s)` URL or a base64 data URL (`data:application/pdf;base64,...`).
The file-parser plugin accepts at most eight PDFs per request: inline base64, or
remote HTTP(S) when `media_transport.fetch_enabled` is enabled. The protected loader
checks host policy, public destination addresses at every redirect, byte limits and
deadlines. Disabled fetching, file IDs and unmapped engines fail before OCR is called.

{}

- file_id (optional): s658

### s658: string

ID of a file uploaded to the provider beforehand.

{}

- filename (optional): s659

### s659: string

File name, which helps the model to tell several files apart.

{}

- * (optional): s660

### s660: any

Further options, passed to the provider as sent.

{}

- type (required): s520

### s520: string

Kind of the part; names the field that carries the content.

"file"

{}

```json
"file"
```

- * (optional): s521

### s521: any

Further fields (for example `cache_control`), passed to the provider as sent.

{}

- role (required): s564

### s564: string

Who speaks: decides how the model treats the message.

"user"

{}

```json
"user"
```

- * (optional): s565

### s565: any

Further message fields (for example `name` or `cache_control`), passed to the
provider as sent.

{}

oneOf: s542

### s542: object

Instructions from the application developer (like `system`).

{}

```json
{
  "content": "Reply in German.",
  "role": "developer"
}
```

- content (required): s537

### s537: anyOf

Text as a string, or as an array of text parts (for example to mark a long, unchanging
part for prompt caching with `cache_control`).

{}

anyOf: s7

anyOf: s1137

### s1137: array

{}

- role (required): s538

### s538: string

Who speaks: decides how the model treats the message.

"developer"

{}

```json
"developer"
```

- * (optional): s539

### s539: any

Further message fields (for example `name` or `cache_control`), passed to the
provider as sent.

{}

oneOf: s543

### s543: object

An earlier answer of the model, sent back to continue the conversation.

{}

```json
{
  "content": null,
  "role": "assistant",
  "tool_calls": [
    {
      "function": {
        "arguments": "{\"city\": \"Lisbon\"}",
        "name": "get_weather"
      },
      "id": "call_8f2c1d",
      "type": "function"
    }
  ]
}
```

- content (optional): s509

### s509: anyOf

Text as a string, or an array of parts that mixes text with images, audio, video and
files. Media need a model that accepts them (`architecture.input_modalities` in
`GET /v1/models`); otherwise the request fails with 404 `no_endpoint`.

{}

anyOf: s7

anyOf: s1136

### s1136: array

{}

anyOf: s588

### s588: null

{}

- role (required): s510

### s510: string

Always `assistant`.

"assistant"

{}

```json
"assistant"
```

- * (optional): s511

### s511: any

Further fields: `tool_calls` (tools the model wants called, with JSON `arguments` as a
string), `refusal`, and `reasoning` with `reasoning_details` (the model's reasoning,
under this name for every provider; left out with `reasoning.exclude`). Chat providers
may return `images`: an array of `{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}`.
The optional type and image URL survive response filtering; provider-only fields do not.
This passthrough does not add a native Images API adapter or a megapixel tariff.

{}

oneOf: s544

### s544: object

The result of a tool the model asked to call.

{}

```json
{
  "content": "{\"temperature_c\": 18}",
  "role": "tool",
  "tool_call_id": "call_8f2c1d"
}
```

- content (required): s559

### s559: anyOf

Text as a string, or an array of parts that mixes text with images, audio, video and
files. Media need a model that accepts them (`architecture.input_modalities` in
`GET /v1/models`); otherwise the request fails with 404 `no_endpoint`.

{}

anyOf: s7

anyOf: s1140

### s1140: array

{}

- role (required): s560

### s560: string

Always `tool`.

"tool"

{}

```json
"tool"
```

- tool_call_id (required): s561

### s561: string

The `id` of the tool call this message answers, from the assistant's `tool_calls`.

{}

```json
"call_8f2c1d"
```

- * (optional): s562

### s562: any

Further fields, passed to the provider as sent.

{}

- model (optional): s279

### s279: string | null

Model to use, with the same ID as on OpenRouter, e.g. `deepseek/deepseek-v4.1-flash`,
or an alias of the gateway: `eu/fast` follows the current recommended version,
`eu/fast@2026-10` stays pinned to one model. The response's `model` field names the model
an alias resolved to, and a key limited to certain models may use an alias only if that
model is allowed (aliases are not part of OpenRouter). `GET /v1/models` lists all IDs and
aliases; an unknown ID fails with 400 `model_not_found` and a suggestion in
`remedy_hint`. Suffixes `:nitro` (throughput) and `:floor` (price) choose request-wide
routing unless `provider.sort` is explicit; a fallback model's suffix does not change
the primary choice. Suffixes are stripped before `allowed_models` checks. Responses
name the resolved base model; generation receipts keep the requested suffix.
Required unless `models` is given.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- models (optional): s280

### s280: array | null

Fallback models (IDs or aliases), tried in this order after `model` when every provider
of the previous model failed before sending output. The response's `model` field names
the model that answered.

{}

```json
[
  "deepseek/deepseek-v4.1-flash",
  "qwen/qwen3.7-flash"
]
```

- stream (optional): s281

### s281: boolean | null

`true` streams the answer as server-sent events while it is generated, ending with
`data: [DONE]`; the last event before it carries `usage` with the cost in EUR.
Default `false`: one JSON response once the answer is complete.

{}

```json
false
```

- * (optional): s282

### s282: any

Other supported OpenRouter parameters. Observability fields are consumed locally:
user (up to 256 characters), metadata (16 string pairs, key 1..64 and value 0..512
characters), trace (21 pairs, names up to 512 characters, unchanged string IDs, custom values
up to 512 JSON bytes). Null observability fields are absent. Debug never reaches a provider.
Only a tenant-scoped user HMAC is sent when capabilities.parameters explicitly lists user.
cache_control, prompt_cache_key and prompt_cache_options also require explicit listing.
Attribution headers: HTTP-Referer (2048 characters), User-Agent (512),
X-OpenRouter-Title / X-Title (256, preferred title wins), X-Trace-Id (body wins, bounded by HTTP header and local storage limits).
Duplicate or oversized attribution headers produce catalog issues. Local attribution
has a 4096-byte text limit and a shared 16-MiB allocation budget; truncation is visible
in the generation.

{}

## Response 200: application/json

The answer as JSON, or as server-sent events ending with `data: [DONE]`. Streams carry `usage` (with the cost in EUR) in their last event before [DONE] whenever the provider reports token counts, with or without `stream_options.include_usage`. A stream that fails after its first byte ends with an event carrying `error` and `finish_reason: "error"`. During long pauses (for example while the model reasons with `reasoning.exclude`) streams carry SSE comments (`: keepalive`), which SSE parsers ignore.

```json
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The capital of Portugal is Lisbon.",
        "reasoning": "Simple geography question.",
        "role": "assistant"
      },
      "native_finish_reason": "stop"
    }
  ],
  "created": 1792352796,
  "id": "gen-1792352796-wrVYATCfa7dAoZzZ5w8J",
  "model": "deepseek/deepseek-v4.1-flash",
  "object": "chat.completion",
  "provider": "deepinfra",
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 16,
    "completion_tokens_details": {
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 6
    },
    "cost": 0.0020198,
    "cost_details": {
      "bridge_cost": 0.002,
      "bridges": [
        {
          "cost_pico_eur": "2000000000",
          "exchange_rate": null,
          "id": "file-parser",
          "kind": "ocr",
          "model": "mock/ocr",
          "original_cost": {
            "currency": "EUR",
            "picos": "2000000000"
          },
          "price_version": "saved-tariff-hash",
          "provider": "mock",
          "quantity": 1,
          "unit": "page"
        }
      ],
      "currency": "EUR",
      "ocr_cost": 0.002,
      "upstream_inference_completions_cost": 0.0000128,
      "upstream_inference_cost": 0.0000198,
      "upstream_inference_prompt_cost": 0.000007
    },
    "currency": "EUR",
    "is_byok": false,
    "prompt_tokens": 35,
    "total_tokens": 51
  }
}
```

### s12: object

The complete answer of a non-streaming request, as on OpenRouter.

Besides the fields below it carries `provider` (the provider that served the request) and
`usage`: `prompt_tokens`, `completion_tokens` (including reasoning tokens, also when
`reasoning.exclude` hides the reasoning), `total_tokens` and `cost`, the price of the
request in **EUR** (OpenRouter: USD), with `currency: "EUR"` and the split into input and
output in `cost_details`. Disjoint line items are `prompt_cost`, `cache_read_cost`,
`cache_write_cost`, `completion_cost`, `reasoning_cost`, `media_cost`, `request_cost`,
`server_tool_cost` and optional `ocr_cost`/`pii_cost`; their exact sum is `cost`. Inference totals
are overlapping aggregates, not additional charges. With OCR, `bridge_cost` is an EUR
aggregate equal to `ocr_cost`, never added again. `bridges[]` contains the same
`GenerationPreprocessing` receipts as the generation lookup, with `id: "file-parser"`,
`model`, `provider`, `unit: "page"`, `quantity` and exact EUR `cost_pico_eur` strings.
Both extensions are omitted without a bridge. Prices use the actual total prompt
tokens (including cache) and the request's UTC arrival instant. With web search, `cost`
includes the searches at the route's
price, shown in `cost_details.server_tool_cost` (EUR) next to the token cost in
`upstream_inference_cost`, and `server_tool_use_details.web_search_requests` counts them.
OCR preprocessing adds `cost_details.ocr_cost` (EUR) and `ocr_documents`; it is charged
once per document even if inference falls back. With an OpenRouter extraction service,
this charge includes its auxiliary inference as well as Mistral OCR. `cost` is missing
when inference token usage is unknown; known OCR details remain available.
For a provider with prices in another currency, `cost_details.original` holds `currency`,
its costs in that currency (`upstream_inference_cost`, `upstream_inference_prompt_cost`,
`upstream_inference_completions_cost`, with web search `server_tool_cost`) and the
`exchange_rate` (`per_eur`, `markup`, `version`, `as_of`); each EUR part is
`cost × (1 + markup) / per_eur`, rounded down to whole picos, and `cost` is their sum.

{}

```json
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The capital of Portugal is Lisbon.",
        "reasoning": "Simple geography question.",
        "role": "assistant"
      },
      "native_finish_reason": "stop"
    }
  ],
  "created": 1792352796,
  "id": "gen-1792352796-wrVYATCfa7dAoZzZ5w8J",
  "model": "deepseek/deepseek-v4.1-flash",
  "object": "chat.completion",
  "provider": "deepinfra",
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 16,
    "completion_tokens_details": {
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 6
    },
    "cost": 0.0020198,
    "cost_details": {
      "bridge_cost": 0.002,
      "bridges": [
        {
          "cost_pico_eur": "2000000000",
          "exchange_rate": null,
          "id": "file-parser",
          "kind": "ocr",
          "model": "mock/ocr",
          "original_cost": {
            "currency": "EUR",
            "picos": "2000000000"
          },
          "price_version": "saved-tariff-hash",
          "provider": "mock",
          "quantity": 1,
          "unit": "page"
        }
      ],
      "currency": "EUR",
      "ocr_cost": 0.002,
      "upstream_inference_completions_cost": 0.0000128,
      "upstream_inference_cost": 0.0000198,
      "upstream_inference_prompt_cost": 0.000007
    },
    "currency": "EUR",
    "is_byok": false,
    "prompt_tokens": 35,
    "total_tokens": 51
  }
}
```

- choices (required): s283

### s283: array

The answers, one per choice (normally exactly one).

{}

### s77: object

One answer of the model and why it ended.

{}

```json
{
  "finish_reason": "stop",
  "index": 0,
  "message": {
    "content": "The capital of Portugal is Lisbon.",
    "role": "assistant"
  },
  "native_finish_reason": "stop"
}
```

- finish_reason (required): s512

### s512: string | null

Why the answer ended, the same for every provider: provider-specific values are mapped to
these five, and the provider's own value is kept in `native_finish_reason`.

"tool_calls", "stop", "length", "content_filter", "error", null

{}

```json
"stop"
```

- index (required): s513

### s513: integer

Position of the choice, starting at 0.

int32

{"minimum":"0"}

```json
0
```

- message (required): s514

### s514: object

The answer.

{}

```json
{
  "content": null,
  "role": "assistant",
  "tool_calls": [
    {
      "function": {
        "arguments": "{\"city\": \"Lisbon\"}",
        "name": "get_weather"
      },
      "id": "call_8f2c1d",
      "type": "function"
    }
  ]
}
```

- content (optional): s509

- role (required): s510

Always `assistant`.

- * (optional): s511

Further fields: `tool_calls` (tools the model wants called, with JSON `arguments` as a
string), `refusal`, and `reasoning` with `reasoning_details` (the model's reasoning,
under this name for every provider; left out with `reasoning.exclude`). Chat providers
may return `images`: an array of `{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}`.
The optional type and image URL survive response filtering; provider-only fields do not.
This passthrough does not add a native Images API adapter or a megapixel tariff.

- * (optional): s515

### s515: any

Further fields, such as `native_finish_reason` (the provider's own value) and
`logprobs`.

{}

- created (required): s284

### s284: integer

When the answer was created, in Unix seconds.

int64

{}

```json
1792352796
```

- id (required): s285

### s285: string

ID of this generation.

{}

```json
"gen-1792352796-wrVYATCfa7dAoZzZ5w8J"
```

- model (required): s286

### s286: string

The model that answered, as a public model ID. With `models` fallbacks this can differ
from the requested `model`.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- object (required): s287

### s287: string

Always `chat.completion`.

"chat.completion"

{}

```json
"chat.completion"
```

- system_fingerprint (required): s288

### s288: string | null

The provider's system fingerprint, or null if it sends none.

{}

- * (optional): s289

### s289: any

Public OpenRouter fields plus `provider` and exact EUR usage extensions.
Unknown provider envelope fields are removed before serialization.

{}

## Response 200: text/event-stream

The answer as JSON, or as server-sent events ending with `data: [DONE]`. Streams carry `usage` (with the cost in EUR) in their last event before [DONE] whenever the provider reports token counts, with or without `stream_options.include_usage`. A stream that fails after its first byte ends with an event carrying `error` and `finish_reason: "error"`. During long pauses (for example while the model reasons with `reasoning.exclude`) streams carry SSE comments (`: keepalive`), which SSE parsers ignore.

```text
data: {"choices":[{"delta":{"content":"The capital","role":"assistant"},"finish_reason":null,"index":0}],"created":1792352796,"id":"gen-1792352796-wrVYATCfa7dAoZzZ5w8J","model":"deepseek/deepseek-v4.1-flash","object":"chat.completion.chunk","provider":"deepinfra"}


```

### s13: object

One server-sent event of a stream (`stream: true`): a line `data: <chunk as JSON>`. The
stream ends with `data: [DONE]`. Lines starting with `:` (`: keepalive` during long pauses)
are comments that SSE parsers skip.

{}

```json
{
  "data": {
    "choices": [
      {
        "delta": {
          "content": "The capital",
          "role": "assistant"
        },
        "finish_reason": null,
        "index": 0
      }
    ],
    "created": 1792352796,
    "id": "gen-1792352796-wrVYATCfa7dAoZzZ5w8J",
    "model": "deepseek/deepseek-v4.1-flash",
    "object": "chat.completion.chunk",
    "provider": "deepinfra"
  }
}
```

- data (required): s290

### s290: object

The chunk carried by the event.

{}

```json
{
  "choices": [
    {
      "delta": {
        "content": " of Portugal is Lisbon."
      },
      "finish_reason": null,
      "index": 0
    }
  ],
  "created": 1792352796,
  "id": "gen-1792352796-wrVYATCfa7dAoZzZ5w8J",
  "model": "deepseek/deepseek-v4.1-flash",
  "object": "chat.completion.chunk",
  "provider": "deepinfra"
}
```

- choices (required): s547

### s547: array

What each choice adds; usually empty in the final usage chunk.

{}

### s87: object

What one choice adds in this chunk.

{}

```json
{
  "delta": {
    "content": " of Portugal is Lisbon."
  },
  "finish_reason": null,
  "index": 0
}
```

- delta (required): s545

### s545: object

The new part of the answer.

{}

```json
{
  "content": "The capital",
  "role": "assistant"
}
```

- content (optional): s553

### s553: string | null

Text to append to the answer. Provider arrays of text parts are joined within
each chunk; part-local metadata is ignored. Non-text parts cannot be represented
here and produce a terminal `provider_invalid_response` error.

{}

- role (optional): s554

### s554: allOf

{}

allOf: s69

### s69: string

Role of a model message.

"assistant"

{}

```json
"assistant"
```

allOf: s1138

### s1138: object

`assistant`, normally only in the first chunk.

{}

- * (optional): s555

### s555: any

Further fields: `reasoning` and `reasoning_details` (pieces of the model's reasoning),
`tool_calls` (pieces of tool calls, joined by their `index`), and `images` (complete
image URL objects, in the same shape as message.images). Image deltas are forwarded
when received, not accumulated or moved to a different event. The existing 1 MiB
provider-event limit applies to the entire event, including base64 data URLs.

{}

- finish_reason (required): s512

Why the answer ended, the same for every provider: provider-specific values are mapped to
these five, and the provider's own value is kept in `native_finish_reason`.

- index (required): s513

Position of the choice, starting at 0.

- * (optional): s546

### s546: any

Further fields, such as `native_finish_reason` and `logprobs`.

{}

- created (required): s548

### s548: integer

When the answer was started, in Unix seconds.

int64

{}

```json
1792352796
```

- id (required): s549

### s549: string

ID of the generation, the same in every chunk of the stream.

{}

```json
"gen-1792352796-wrVYATCfa7dAoZzZ5w8J"
```

- model (required): s550

### s550: string

The model that answers, as a public model ID.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- object (required): s551

### s551: string

Always `chat.completion.chunk`.

"chat.completion.chunk"

{}

```json
"chat.completion.chunk"
```

- * (optional): s552

### s552: any

Public fields: `provider`, `usage` (final chunk) and the gateway catalog
`error` (failed stream). Provider-only events and fields are removed.

{}

## Response 400: application/json

Recognized upstream 400/422 request rejections return non-retryable client errors with safe public field paths. Invalid request: broken JSON (`invalid_request`), invalid fields (including the session ID in `session_id` or `x-session-id`) with every problem in `issues` (`invalid_parameter`), an unknown model ID with a suggestion in `remedy_hint` (`model_not_found`), or a prompt too long for the model (`context_length_exceeded`). Plugins, server tools and `web_search_options` the gateway does not offer fail with issue code `not_available`

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

- 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

- 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 (`authentication`). Expiry is checked when a request starts; a stream that is already running finishes.

## Response 402: application/json

The API key spending limit, the workspace budget (`workspace_budget_exceeded`) or the organization prepaid balance cannot cover the estimated request reservation, including fees, media and concurrent reservations (`insufficient_credits` for key and organization). No paid upstream call starts without a reservation.

## Response 403: application/json

The organization, workspace or key policy does not allow the model in `model` (`permission_denied`); `issues` names every requested model the key may not use and `remedy_hint` the models it may use. Fallbacks in `models` the key may not use are skipped. Web search (the `web` plugin) needs `web_search` in the policy's `server_tools`.

## Response 404: application/json

The model exists, but none of its providers fits the request: `provider` filters, `max_price`, media the model does not accept, or web search the model does not offer. `issues` names the reason per provider (`no_endpoint`)

## Response 408: application/json

The provider did not connect, did not start a stream, or did not finish a non-streaming response within the route's time limit, or the request body stopped arriving (`timeout`)

## Response 409: application/json

idempotency_conflict: this key has different request content; use a new key. idempotency_in_progress: the original is running; respect Retry-After. idempotency_unavailable: no safe replay is possible; do not silently recompute. See remedy_hint.

## Response 413: application/json

The request body is larger than 50 MiB, or its parsed JSON structure excluding JSON string values would need more than 20 MiB, as with hundreds of thousands of small objects (`payload_too_large`)

## Response 429: application/json

Customer quota or upstream rate limit exhausted (`rate_limited`)

## Response 500: application/json

Unexpected gateway error (`internal`)

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

The only provider tried failed (`provider_error`, with `provider_name` and structured `provider_error` diagnostics; provider text is withheld) or sent a response that could not be interpreted, larger than 32 MiB or too complex to parse (`provider_invalid_response`)

## Response 503: application/json

Every route and fallback failed, no exchange rate is available for the prices of the model's providers, the gateway is busy with other large request bodies, or this gateway instance is shutting down (`no_provider_available`)
