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 --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
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
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
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
{
"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:
nandtransformsare validated and recorded as requested, but remain listed inx-ignored-paramsand do not affect execution. The gateway continues to request a single generation without message transforms. - Output bound:
max_tokensandmax_completion_tokensexpress 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: trueexcludes 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_priceis in EUR per million tokens ({"prompt": 0.5, "completion": 2}), not USD; costs inusageare EUR as well. Price limits andprovider.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(400invalid_parameter). Requests OpenRouter passes on and lets the provider reject (unknown role, unknownresponse_format, broken tool schema,tool_choicenaming 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-paramsresponse header, so typos do not go unnoticed.usage: {"include": true}is accepted silently: usage is always included. - Provider slugs in
provider.only,provider.ignoreandprovider.orderare 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: falsemaps toreasoning.exclude: true(true maps to false); an explicitreasoning.excludewins. A route unable to disable reasoning still hides its output and charges actual tokens; the unfulfilled control (reasoning.effort,reasoning.enabledorreasoning.max_tokens) is named inx-ignored-paramsfor the answering route. Messages and stream deltas exposereasoning_detailsalongside 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:**pricesorts by EUR prompt-plus-completion price.latencyandthroughputuse shared Valkey measurements across gateway instances: the median of the last 32 answers per provider within 30 minutes. Unmeasured providers come last.exactois accepted but preserves configured order, not Balanced selection. - Soft performance preferences:
provider.preferred_max_latency(seconds) andprovider.preferred_min_throughput(output tokens/second) accept a non-negative number for p50, or an object withp50,p75,p90,p99thresholds. 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:
:nitroselects throughput sorting and:floorprice sorting; an explicitprovider.sortwins. The primary model's variant sets sorting for the whole request, including fallback models. Variants are removed before model-policy checks; they do not bypassallowed_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: truerequires a route with parallel tool support.falsealso 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 acceptauto/none; without require_parameters, choice is forwarded subject to the route's ordinary parameter mapping. - Sessions:
session_id(or thex-session-idheader; the field wins) groups generations, listed byGET /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 400invalid_parameter. - Assistant reasoning history:
reasoning(orreasoning_content) is text;reasoning_detailsis 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.excludeonly affects new output. - Limits: the body may have at most 50 MiB; see "Limits" in the introduction.
- Plugins and server tools:
pluginsnever reaches the provider.response-healingandfile-parserrun in the gateway.web(web search) works only with a model whose provider offers it and a key whose policy allowsweb_search; it takesmax_results(1 to 20),max_uses(1 to 100, capped by the provider route) andengine(autoornative), 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 intools(e.g.openrouter:web_search), atool_choicenaming one, andweb_search_optionsfail with 400invalid_parameter(issue codenot_available) instead of running unbilled; a plugin withenabled: falseis accepted.stop_server_tools_whenis ignored (named inx-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 requiremedia_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 totokenlane/pdf-text, the gateway's own media worker reads the PDF text layer instead of OCR (receipt kindtext_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'sfallback. - Tool calls are checked by default (
tool-call-healing; unlike OpenRouter, which passes them unchanged): withtools, every returned call must name one of them, carry a JSON object as arguments and include the schema'srequiredarguments. 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 502provider_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) whenresponse_formatisjson_objectorjson_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.
{}
{
"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).
{}
{
"content": "What is the capital of Portugal?",
"role": "user"
}
oneOf: s540
s540: object
Instructions that steer the whole conversation.
{}
{
"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.
{}
{
"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"
{}
"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"
{}
"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.
{}
{
"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.
{}
{
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
},
"type": "image_url"
}
oneOf: s525
s525: object
A piece of text.
{}
{
"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.
{}
{
"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.
{}
{
"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.
{}
"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"
{}
"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.
{}
{
"input_audio": {
"data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"format": "wav"
},
"type": "input_audio"
}
- input_audio (required): s516
s516: object
Audio as base64 data with its format.
{}
{
"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.
{}
"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"
{}
"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.
{}
{
"type": "input_video",
"video_url": {
"url": "https://storage.example.eu/clips/demo.mp4"
}
}
- type (required): s823
s823: string
Always input_video.
"input_video"
{}
"input_video"
- video_url (required): s824
s824: object
The video as an http(s) URL or a base64 data URL.
{}
{
"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.
{}
{
"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"
{}
"video_url"
- video_url (required): s535
s535: object
A video as an http(s) URL or a base64 data URL.
{}
{
"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.
{}
{
"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.
{}
{
"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"
{}
"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"
{}
"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).
{}
{
"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"
{}
"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.
{}
{
"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"
{}
"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.
{}
{
"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"
{}
"tool"
- tool_call_id (required): s561
s561: string
The id of the tool call this message answers, from the assistant's tool_calls.
{}
"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.
{}
"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.
{}
[
"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.
{}
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.
{
"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.
{}
{
"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.
{}
{
"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
{}
"stop"
- index (required): s513
s513: integer
Position of the choice, starting at 0.
int32
{"minimum":"0"}
0
- message (required): s514
s514: object
The answer.
{}
{
"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
{}
1792352796
- id (required): s285
s285: string
ID of this generation.
{}
"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.
{}
"deepseek/deepseek-v4.1-flash"
- object (required): s287
s287: string
Always chat.completion.
"chat.completion"
{}
"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.
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.
{}
{
"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.
{}
{
"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.
{}
{
"delta": {
"content": " of Portugal is Lisbon."
},
"finish_reason": null,
"index": 0
}
- delta (required): s545
s545: object
The new part of the answer.
{}
{
"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"
{}
"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
{}
1792352796
- id (required): s549
s549: string
ID of the generation, the same in every chunk of the stream.
{}
"gen-1792352796-wrVYATCfa7dAoZzZ5w8J"
- model (required): s550
s550: string
The model that answers, as a public model ID.
{}
"deepseek/deepseek-v4.1-flash"
- object (required): s551
s551: string
Always chat.completion.chunk.
"chat.completion.chunk"
{}
"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
{
"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.
{}
{
"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.
{}
{
"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"}
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.
{}
"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.
{}
{
"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).
{}
[
"deepinfra",
"open-inference"
]
- docs_url (required): s640
s640: string
Link to the section of this error type in the documentation.
{}
"/docs#description/model-not-found"
- failed_routing_step (optional): s641
s641: string
The routing step that left no route (routing errors only).
{}
"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.
{}
{
"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"
{}
"out_of_range"
- message (required): s637
s637: string
The problem in English, naming the field and, if short, the value sent.
{}
"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.
{}
"$.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.
{}
{
"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"
{}
"rate_limited"
- code (optional): s1300
s1300: string
Exact identifier from the configured dialect's fixed list; arbitrary values vanish.
{}
"rate_limit_exceeded"
- provider_name (required): s1301
s1301: string
Configured provider name, never a name supplied by the upstream body.
{}
"deepinfra"
- retry_after (optional): s1302
s1302: integer
Bounded seconds from the upstream Retry-After header, when present and numeric.
int64
{"minimum":"0"}
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"}
429
oneOf: s588
- provider_name (optional): s644
s644: string
The provider that failed, as in the response field provider (provider errors only).
{}
"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.
{}
""
- remedy_hint (optional): s646
s646: string
A concrete fix, for example the closest model ID to a mistyped one.
{}
"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.
{}
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
- requested_providers (optional): s648
s648: array
Providers named in provider.only (when it excluded all routes).
{}
[
"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"}
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.
{}
{
"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"}
2
- reason (optional): s980
s980: string
The request field the step filtered on.
{}
"provider.only"
- step (required): s981
s981: string
Name of the step, as at OpenRouter.
{}
"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"
{}
"invalid_parameter"
- user_id (optional): s239
s239: string | null
Organization of the API key, if the key was recognized.
{}
"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)