{ "openapi": "3.1.0", "info": { "title": "llm.buzz model API", "version": "1", "description": "The inference, model and account routes of the llm.buzz model API, in the OpenAI, Anthropic and OpenRouter wire formats, and the keyless public catalog. Request and response bodies follow each provider's official SDK types; this document lists the fields llm.buzz acts on." }, "servers": [ { "url": "https://api.llm.buzz" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Inference", "description": "Generate text, embeddings, images and audio, and read what a finished request cost." }, { "name": "Models", "description": "The models a key can call and the providers that serve them." }, { "name": "Account", "description": "The key you send, your organization's credit, and your inference keys, in OpenRouter's key and credits shapes." }, { "name": "Public catalog", "description": "The keyless, read-only catalog the llm.buzz website is built from. It is the website's data, not a stable API: its fields can change without notice, so build on `GET /api/v1/models` and the endpoints route." } ], "paths": { "/api/v1/chat/completions": { "post": { "operationId": "chat-completions", "summary": "Chat Completions", "description": "Send a conversation, get the next message. OpenAI's Chat Completions API: the OpenAI and OpenRouter SDKs call it unchanged. Set `stream: true` for server-sent events, which end with a usage chunk and `data: [DONE]`.", "tags": [ "Inference" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SessionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "A model's name from `GET /api/v1/models`, such as `deepseek/deepseek-v4.1-flash`. A suffix changes one request: `:floor` tries the cheapest provider first and `:nitro` the fastest. On Chat Completions and Responses `:online` asks for a web search, which llm.buzz does not run today: the request is served without one and `x-sgr-ignored-parameters` names `web_search->dropped(search_unavailable)`, or for an organization whose requests llm.buzz keeps in the EU it answers 400 `web_search_unavailable_in_region`. On Messages `:online` does nothing and is named as `model:online`." }, "messages": { "type": "array", "description": "The conversation, as OpenAI's message objects: `system`, `user`, `assistant` and `tool` roles. A user message may carry `image_url` parts for models that read images, and a `text` part may carry `prompt_cache_breakpoint`, OpenAI's explicit cache mark.", "items": { "type": "object" } }, "stream": { "type": "boolean", "default": false, "description": "Stream the answer as server-sent events." }, "max_tokens": { "type": "integer", "description": "The most tokens the answer may use. Also bounds what the request holds of your balance while it runs." }, "temperature": { "type": "number", "description": "Sampling temperature. A model that takes none drops it and names it in `x-sgr-ignored-parameters`." }, "tools": { "type": "array", "description": "Functions the model can call, in OpenAI's shape. `{\"type\": \"openrouter:tool_search\"}` declares a tool search, and a tool with `defer_loading: true` beside `function` waits for it.", "items": { "type": "object" } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "type": "object" } ], "description": "`auto`, `none`, `required`, or an object naming one function." }, "response_format": { "type": "object", "description": "`{\"type\": \"json_schema\", ...}` asks for an answer in a JSON schema; `{\"type\": \"json_object\"}` for any JSON object." }, "reasoning": { "type": "object", "description": "Reasoning controls, translated for each provider.", "properties": { "effort": { "type": "string", "description": "How hard the model thinks. An effort the model does not take becomes the nearest one it does, named in `x-sgr-ignored-parameters`." }, "max_tokens": { "type": "integer", "description": "A reasoning budget in tokens." }, "enabled": { "type": "boolean", "description": "Turn reasoning on or off." }, "exclude": { "type": "boolean", "description": "Keep the reasoning text out of the answer while the model still reasons." } } }, "include_reasoning": { "type": "boolean", "description": "OpenRouter's older switch: `true` is `reasoning: {}`, `false` is `reasoning: {exclude: true}`." }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "session_id": { "type": "string", "description": "A name for the conversation, 1 to 256 characters, so its turns stay on the provider that holds its cache." }, "cache_control": { "type": "object", "description": "Anthropic's prompt-cache marker, `{\"type\": \"ephemeral\"}` with an optional `ttl` of `\"5m\"` or `\"1h\"`. llm.buzz passes it on and never adds one. Claude models cache only where a request marks it." }, "prompt_cache_options": { "type": "object", "description": "OpenAI's explicit caching, for GPT-5.6 and later models: `mode` `implicit` (OpenAI's default) or `explicit` (OpenAI writes the cache only at a `prompt_cache_breakpoint`), and `ttl` `30m`." }, "prompt_cache_retention": { "type": "string", "enum": [ "in_memory", "24h" ], "description": "OpenAI's cache retention. `24h` with `provider.zdr`, `provider.data_collection: \"deny\"` or your organization's no-retention policy is a 400 `invalid_request`." }, "web_search_options": { "type": "object", "description": "Asks for a web search, as the `:online` suffix does. llm.buzz runs none today: the request is served without a search, nothing is billed for one, and `x-sgr-ignored-parameters` names it as `web_search->dropped(search_unavailable)`. An organization whose requests llm.buzz keeps in the EU gets 400 `web_search_unavailable_in_region` instead." } } }, "example": { "model": "deepseek/deepseek-v4.1-flash", "messages": [ { "role": "user", "content": "Say hello in one word." } ] } } } }, "responses": { "200": { "description": "The answer. `provider` names the provider that answered, and `usage.cost` is the request's cost in US dollars when every part of it is known.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The completion's ID." }, "model": { "type": "string", "description": "The model that answered." }, "provider": { "type": "string", "description": "The display name of the provider that answered, after any failover: `llm.buzz` for llm.buzz's own provider." }, "choices": { "type": "array", "description": "The answer. `message.reasoning` carries readable reasoning when the model returns it, and `message.images` the images a model that makes images returns.", "items": { "type": "object" } }, "usage": { "type": "object", "description": "Token counts; cache reads in `prompt_tokens_details.cached_tokens` and writes in its `cache_write_tokens` (`cache_write_1h_tokens` for the one-hour part, when the provider reports it); and `cost` in US dollars. Omitted when the provider reported no counts." }, "x-sgr-ignored-parameters": { "type": "array", "description": "Fields llm.buzz dropped instead of failing the request, such as `temperature->dropped(unsupported_by_provider)`.", "items": { "type": "string" } } } }, "example": { "id": "chatcmpl-...", "object": "chat.completion", "model": "deepseek/deepseek-v4.1-flash", "provider": "Prime Intellect", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop", "native_finish_reason": "stop" } ], "usage": { "prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15, "cost": 0.0000072 }, "system_fingerprint": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.llm.buzz/api/v1\", api_key=os.environ[\"LLM_BUZZ_KEY\"])\nreply = client.chat.completions.create(\n model=\"deepseek/deepseek-v4.1-flash\",\n messages=[{\"role\": \"user\", \"content\": \"Say hello in one word.\"}],\n)\nprint(reply.choices[0].message.content)" }, { "lang": "ts", "label": "TypeScript", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({ baseURL: \"https://api.llm.buzz/api/v1\", apiKey: process.env.LLM_BUZZ_KEY });\nconst reply = await client.chat.completions.create({\n model: \"deepseek/deepseek-v4.1-flash\",\n messages: [{ role: \"user\", content: \"Say hello in one word.\" }],\n});\nconsole.log(reply.choices[0].message.content);" } ] } }, "/api/v1/responses": { "post": { "operationId": "responses", "summary": "Responses", "description": "OpenAI's Responses API. Continue a conversation with `previous_response_id`. Set `stream: true` for Responses stream events.", "tags": [ "Inference" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/SessionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "A model's name from `GET /api/v1/models`, such as `deepseek/deepseek-v4.1-flash`. A suffix changes one request: `:floor` tries the cheapest provider first and `:nitro` the fastest. On Chat Completions and Responses `:online` asks for a web search, which llm.buzz does not run today: the request is served without one and `x-sgr-ignored-parameters` names `web_search->dropped(search_unavailable)`, or for an organization whose requests llm.buzz keeps in the EU it answers 400 `web_search_unavailable_in_region`. On Messages `:online` does nothing and is named as `model:online`." }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "A string, or a list of input items in OpenAI's shape. An `input_text` part may carry `prompt_cache_breakpoint`, OpenAI's explicit cache mark." }, "instructions": { "type": "string", "description": "A system message for this turn." }, "previous_response_id": { "type": "string", "description": "Continue from an earlier response." }, "stream": { "type": "boolean", "default": false, "description": "Stream Responses events." }, "reasoning": { "type": "object", "description": "`effort`, translated for each provider." }, "tools": { "type": "array", "description": "Function tools in the Responses shape; `{\"type\": \"tool_search\"}` declares a tool search over tools marked `defer_loading: true`.", "items": { "type": "object" } }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "session_id": { "type": "string", "description": "A name for the conversation, 1 to 256 characters, so its turns stay on the provider that holds its cache." }, "cache_control": { "type": "object", "description": "Anthropic's prompt-cache marker, `{\"type\": \"ephemeral\"}` with an optional `ttl` of `\"5m\"` or `\"1h\"`. llm.buzz passes it on and never adds one. Claude models cache only where a request marks it." }, "prompt_cache_options": { "type": "object", "description": "OpenAI's explicit caching, for GPT-5.6 and later models: `mode` `implicit` (OpenAI's default) or `explicit` (OpenAI writes the cache only at a `prompt_cache_breakpoint`), and `ttl` `30m`." }, "prompt_cache_retention": { "type": "string", "enum": [ "in_memory", "24h" ], "description": "OpenAI's cache retention. `24h` with `provider.zdr`, `provider.data_collection: \"deny\"` or your organization's no-retention policy is a 400 `invalid_request`." } } }, "example": { "model": "deepseek/deepseek-v4.1-flash", "input": "Say hello in one word." } } } }, "responses": { "200": { "description": "A response object. Cache reads show in `usage.input_tokens_details.cached_tokens` and writes in its `cache_write_tokens`; readable reasoning arrives as a reasoning item's `summary_text`.", "content": { "application/json": { "example": { "id": "resp_...", "object": "response", "model": "deepseek/deepseek-v4.1-flash", "status": "completed", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Hello!" } ] } ], "usage": { "input_tokens": 12, "output_tokens": 3, "total_tokens": 15, "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 }, "cost": 0.0000072 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/Throttled" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.llm.buzz/api/v1\", api_key=os.environ[\"LLM_BUZZ_KEY\"])\nresponse = client.responses.create(model=\"deepseek/deepseek-v4.1-flash\", input=\"Say hello in one word.\")\nprint(response.output_text)" } ] }, "get": { "operationId": "responses-websocket", "summary": "Responses WebSocket", "description": "The same Responses API over a WebSocket, the transport the Codex CLI uses. Send `response.create` frames; each Responses stream event arrives as one text frame, and a request that fails arrives as an `{\"type\": \"error\", ...}` frame. The key is checked before the upgrade is accepted. A `GET` without an upgrade answers 426.", "tags": [ "Inference" ], "parameters": [ { "name": "Upgrade", "in": "header", "required": true, "description": "`websocket`.", "schema": { "type": "string" } } ], "responses": { "101": { "description": "The connection switches to the WebSocket." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "426": { "description": "A `GET` without a well-formed upgrade. Clients such as Codex fall back to `POST /api/v1/responses`." } } } }, "/api/v1/messages": { "post": { "operationId": "messages", "summary": "Messages", "description": "Anthropic's Messages API, for the Anthropic SDK and the tools built on it. The key may also come in `x-api-key`. Errors keep Anthropic's error body.", "tags": [ "Inference" ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "A model's name from `GET /api/v1/models`, such as `deepseek/deepseek-v4.1-flash`. A suffix changes one request: `:floor` tries the cheapest provider first and `:nitro` the fastest. On Chat Completions and Responses `:online` asks for a web search, which llm.buzz does not run today: the request is served without one and `x-sgr-ignored-parameters` names `web_search->dropped(search_unavailable)`, or for an organization whose requests llm.buzz keeps in the EU it answers 400 `web_search_unavailable_in_region`. On Messages `:online` does nothing and is named as `model:online`." }, "max_tokens": { "type": "integer", "description": "The most tokens the answer may use." }, "messages": { "type": "array", "description": "The conversation, as Anthropic's message objects.", "items": { "type": "object" } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The system prompt: a string, or a list of text blocks, which may carry `cache_control`." }, "stream": { "type": "boolean", "default": false, "description": "Stream Anthropic's server-sent events." }, "tools": { "type": "array", "description": "Tools in Anthropic's shape. `{\"type\": \"tool_search_tool_bm25\"}` or `{\"type\": \"tool_search_tool_regex\"}` declares a tool search over tools marked `defer_loading: true`.", "items": { "type": "object" } }, "reasoning": { "type": "object", "description": "Reasoning controls, translated for each provider.", "properties": { "effort": { "type": "string", "description": "How hard the model thinks. An effort the model does not take becomes the nearest one it does, named in `x-sgr-ignored-parameters`." }, "max_tokens": { "type": "integer", "description": "A reasoning budget in tokens." }, "enabled": { "type": "boolean", "description": "Turn reasoning on or off." }, "exclude": { "type": "boolean", "description": "Keep the reasoning text out of the answer while the model still reasons." } } }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "session_id": { "type": "string", "description": "A name for the conversation, 1 to 256 characters, so its turns stay on the provider that holds its cache." } } }, "example": { "model": "anthropic/claude-haiku-5.5", "max_tokens": 256, "messages": [ { "role": "user", "content": "Say hello in one word." } ] } } } }, "responses": { "200": { "description": "Anthropic's message object. `usage` always carries `cache_creation_input_tokens` and `cache_read_input_tokens`, and `cost` in US dollars; readable reasoning arrives as a `thinking` block.", "content": { "application/json": { "example": { "id": "msg_...", "type": "message", "role": "assistant", "model": "anthropic/claude-haiku-5.5", "content": [ { "type": "text", "text": "Hello!" } ], "stop_reason": "end_turn", "usage": { "input_tokens": 14, "output_tokens": 4, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cost": 0.0000034 } } } } }, "400": { "$ref": "#/components/responses/AnthropicBadRequest" }, "401": { "$ref": "#/components/responses/AnthropicError" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "import os\nfrom anthropic import Anthropic\n\nclient = Anthropic(base_url=\"https://api.llm.buzz/api\", api_key=os.environ[\"LLM_BUZZ_KEY\"])\nmessage = client.messages.create(\n model=\"anthropic/claude-haiku-5.5\",\n max_tokens=256,\n messages=[{\"role\": \"user\", \"content\": \"Say hello in one word.\"}],\n)\nprint(message.content[0].text)" }, { "lang": "ts", "label": "TypeScript", "source": "import Anthropic from \"@anthropic-ai/sdk\";\n\nconst client = new Anthropic({ baseURL: \"https://api.llm.buzz/api\", apiKey: process.env.LLM_BUZZ_KEY });\nconst message = await client.messages.create({\n model: \"anthropic/claude-haiku-5.5\",\n max_tokens: 256,\n messages: [{ role: \"user\", content: \"Say hello in one word.\" }],\n});" } ] } }, "/api/v1/messages/count_tokens": { "post": { "operationId": "count-tokens", "summary": "Count tokens", "description": "An estimate of a Messages request's input tokens, from llm.buzz's own tokenizer, never the provider's. It costs nothing and is not refused for a key's spending limit. The body names the estimate in `x-sgr-ignored-parameters` as `input_tokens->estimated(gateway_tokenizer)`.", "tags": [ "Inference" ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "A model's name from `GET /api/v1/models`, such as `deepseek/deepseek-v4.1-flash`. A suffix changes one request: `:floor` tries the cheapest provider first and `:nitro` the fastest. On Chat Completions and Responses `:online` asks for a web search, which llm.buzz does not run today: the request is served without one and `x-sgr-ignored-parameters` names `web_search->dropped(search_unavailable)`, or for an organization whose requests llm.buzz keeps in the EU it answers 400 `web_search_unavailable_in_region`. On Messages `:online` does nothing and is named as `model:online`." }, "messages": { "type": "array", "description": "The conversation, as on Messages.", "items": { "type": "object" } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The system prompt: a string, or a list of text blocks, which may carry `cache_control`." }, "tools": { "type": "array", "description": "Tools, as on Messages.", "items": { "type": "object" } } } }, "example": { "model": "anthropic/claude-haiku-5.5", "messages": [ { "role": "user", "content": "Say hello in one word." } ] } } } }, "responses": { "200": { "description": "The estimate.", "content": { "application/json": { "example": { "input_tokens": 14, "x-sgr-ignored-parameters": [ "input_tokens->estimated(gateway_tokenizer)" ] } } } }, "401": { "$ref": "#/components/responses/AnthropicError" } } } }, "/api/v1/embeddings": { "post": { "operationId": "embeddings", "summary": "Embeddings", "description": "OpenAI's Embeddings API, for embeddings models: vectors for one or more inputs, never streamed. A call bills the input tokens the provider reports at that provider's input price, with no output. A request without `dimensions` gets vectors of the model's declared dimensions. Send no `stream`, or `false`; unknown fields are dropped. There is no answer store: `Idempotency-Key` is ignored, so a retry is a new, billed call. `GET /api/v1/embeddings/models` lists the embeddings models your key can call.", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "An embeddings model from `GET /api/v1/embeddings/models`, such as `qwen/qwen3-embedding-8b`." }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer" } }, { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } } ], "description": "A string, a list of strings, a list of token IDs, or a list of such lists. Token IDs must match the model's tokenizer." }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "description": "How the vectors come back." }, "dimensions": { "type": "integer", "description": "The vectors' size, sent to the provider as given." }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "user": { "type": "string", "description": "Your end user's label, recorded and never forwarded." } } }, "example": { "model": "qwen/qwen3-embedding-8b", "input": "The quick brown fox" } } } }, "responses": { "200": { "description": "One vector per input, exactly as the provider returned it, with `provider` and `usage`, whose `cost` is in US dollars.", "content": { "application/json": { "example": { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0123, -0.0456 ] } ], "model": "qwen/qwen3-embedding-8b", "provider": "DeepInfra", "usage": { "prompt_tokens": 4, "total_tokens": 4, "cost": 4e-8 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/api/v1/images": { "post": { "operationId": "images", "summary": "Images", "description": "OpenRouter's Image API: a text prompt in, images out, never streamed. The request resolves to one size the model declares: an explicit `size`; else `resolution` keeps the sizes of that tier and `aspect_ratio` picks the first of them with that ratio; with neither, the model's first size. Only the parameters the model declares reach the provider. A provider may return fewer images than `n`, and you pay for the images returned: a model priced per image bills each image, one priced per token the tokens the provider reports. A high-quality image can take minutes, so allow a long client timeout. `GET /api/v1/images/models` lists the image models your key can call and the values each takes.", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "An image model from `GET /api/v1/images/models`, such as `qwen/qwen-image-3`; a chat or embeddings model is a 400 on `model`. The `:floor` and `:nitro` suffixes work as on chat." }, "prompt": { "type": "string", "description": "What to draw, 1 to 32,000 characters." }, "n": { "type": "integer", "default": 1, "description": "How many images, 1 to 10 and at most the model's most images per request." }, "size": { "type": "string", "description": "A size the model declares, `WIDTHxHEIGHT` or `auto`, or a resolution tier such as `1K` or `2K`, read as `resolution`." }, "aspect_ratio": { "type": "string", "description": "A ratio the model declares, such as `16:9`: the first declared size with that ratio." }, "resolution": { "type": "string", "description": "A tier the model declares, such as `1K` or `2K`." }, "quality": { "type": "string", "description": "A value the model declares; a model that declares none ignores the field." }, "background": { "type": "string", "description": "A value the model declares; a model that declares none ignores the field." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "A format the model declares; a model that declares none ignores the field." }, "output_compression": { "type": "integer", "description": "0 to 100, forwarded only to a model that takes it." }, "seed": { "type": "integer", "description": "Forwarded only to a model that takes it." }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "user": { "type": "string", "description": "Your end user's label, recorded and never forwarded." } } }, "example": { "model": "qwen/qwen-image-3", "prompt": "A honeycomb engraved on a copper plate", "aspect_ratio": "16:9" } } } }, "responses": { "200": { "description": "The images, each as `b64_json` with the `media_type` its bytes show (PNG, JPEG or WebP), and `usage`, whose `cost` is in US dollars. The `X-Generation-Id` header names the call's generation record, `GET /api/v1/generation`.", "content": { "application/json": { "example": { "created": 1792900000, "data": [ { "b64_json": "iVBORw0...", "media_type": "image/png" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 4175, "total_tokens": 4175, "cost": 0.03 } } } } }, "400": { "$ref": "#/components/responses/ImageBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/api/v1/images/generations": { "post": { "operationId": "image-generations", "summary": "Image generation", "description": "OpenAI's Images API, generations only, for the OpenAI SDK: a prompt in, images out as `b64_json`, never streamed. It serves the same models and checks the same declarations as `POST /api/v1/images`: `model` and `prompt` suffice, and the model's first declared size is the default. `style` is accepted and never forwarded, the SDK's `standard` and `hd` qualities match no declared quality, and unknown fields are dropped. `GET /api/v1/images/models` lists the image models your key can call.", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "An image model from `GET /api/v1/images/models`, such as `qwen/qwen-image-3`; a chat or embeddings model is a 400 on `model`. The `:floor` and `:nitro` suffixes work as on chat." }, "prompt": { "type": "string", "description": "What to draw, 1 to 32,000 characters." }, "n": { "type": "integer", "default": 1, "description": "How many images, 1 to 10 and at most the model's most images per request." }, "size": { "type": "string", "description": "A size the model declares, `WIDTHxHEIGHT` or `auto`." }, "quality": { "type": "string", "description": "A value the model declares; a model that declares none ignores the field." }, "background": { "type": "string", "description": "A value the model declares; a model that declares none ignores the field." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "A format the model declares; a model that declares none ignores the field." }, "output_compression": { "type": "integer", "description": "0 to 100, forwarded only to a model that takes it." }, "moderation": { "type": "string", "description": "Forwarded only to a model that takes it." }, "response_format": { "type": "string", "enum": [ "b64_json" ], "description": "Every image is answered as `b64_json`; `url` is a 400." }, "provider": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "user": { "type": "string", "description": "Your end user's label, recorded and never forwarded." } } }, "example": { "model": "qwen/qwen-image-3", "prompt": "A honeycomb engraved on a copper plate" } } } }, "responses": { "200": { "description": "The images as `b64_json` (with any `revised_prompt`), the rendering facts the provider echoes (`background`, `output_format`, `quality`, `size`), and `usage` in OpenAI's names, whose `cost` is in US dollars. The `X-Generation-Id` header names the call's generation record, `GET /api/v1/generation`.", "content": { "application/json": { "example": { "created": 1792900000, "data": [ { "b64_json": "iVBORw0..." } ], "usage": { "input_tokens": 0, "output_tokens": 4175, "total_tokens": 4175, "input_tokens_details": { "image_tokens": 0, "text_tokens": 0 }, "cost": 0.03 } } } } }, "400": { "$ref": "#/components/responses/ImageBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/api/v1/audio/transcriptions": { "post": { "operationId": "audio-transcriptions", "summary": "Speech to text", "description": "OpenRouter's speech-to-text API: one audio file in, its text out, never streamed. Send the audio as base64 in `input_audio`, or as an OpenAI multipart upload with the audio in a `file` part and every other field as a text part. The file is at most 25 MiB in `wav`, `mp3`, `flac`, `ogg`, `webm`, `m4a`, `aac` or `pcm`; its duration is measured before any provider is called, and a file that cannot be read is a 400, never billed. A call bills the seconds of audio. `GET /api/v1/models?output_modalities=transcription` lists the models your key can call, each with `verbose_json`.", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input_audio" ], "properties": { "model": { "type": "string", "description": "A speech-to-text model from `GET /api/v1/models?output_modalities=transcription`, such as `openai/whisper-large-v3-turbo`." }, "input_audio": { "type": "object", "description": "`data` (the audio in base64) and `format`. A `url` is a 400: send the bytes." }, "response_format": { "type": "string", "enum": [ "json", "verbose_json" ], "description": "`json` (the default: `text` and `usage`) or `verbose_json`, which adds `task`, `language`, `duration`, `segments` and `words`, on a model whose `verbose_json` is `true`." }, "language": { "type": "string", "description": "An ISO-639-1 code such as `en`; omitted, the provider detects it." }, "temperature": { "type": "number", "description": "0 to 1." }, "timestamp_granularities": { "type": "array", "items": { "type": "string", "enum": [ "segment", "word" ] }, "description": "Sent with `verbose_json` only." }, "provider": { "type": "object", "description": "The audio routes read only the data policy fields; `order`, `only`, `ignore`, `allow_fallbacks` and `sort` are accepted and ignored. With the OpenAI SDK, send it in `extra_body`.", "properties": { "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } } } }, "example": { "model": "openai/whisper-large-v3-turbo", "input_audio": { "data": "BASE64_AUDIO", "format": "mp3" } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The audio file." }, "model": { "type": "string" } } } } } }, "responses": { "200": { "description": "The text, with `usage.seconds` (what the call billed) and `usage.cost` in US dollars. The `X-Generation-Id` header names the call's generation record.", "content": { "application/json": { "example": { "text": "Thanks for calling.", "usage": { "seconds": 12.48, "cost": 0.000041558 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The file is over 25 MiB (`request_too_large`). Send a shorter file." } } } }, "/api/v1/audio/speech": { "post": { "operationId": "audio-speech", "summary": "Text to speech", "description": "OpenRouter's text-to-speech API: one text in, the whole audio out as MP3 or raw PCM, never streamed. A call bills the input's characters, and settles before the first byte is sent. The answer has no JSON body, so its cost is in the generation record that `X-Generation-Id` names. `GET /api/v1/models?output_modalities=speech` lists the models your key can call, each with its `supported_voices`, `default_voice` and `speech_speed`.", "tags": [ "Inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "A text-to-speech model from `GET /api/v1/models?output_modalities=speech`, such as `hexgrad/kokoro-82m`." }, "input": { "type": "string", "description": "1 to 4,096 characters. An array of turns (several speakers) is a 400." }, "voice": { "type": "string", "description": "One of the model's `supported_voices`; omitted, its `default_voice`." }, "response_format": { "type": "string", "enum": [ "pcm", "mp3" ], "description": "`pcm` (the default: signed 16-bit little-endian mono) or `mp3`." }, "speed": { "type": "number", "description": "0.25 to 4.0, on a model whose `speech_speed` is `true`." }, "provider": { "type": "object", "description": "The audio routes read only the data policy fields; `order`, `only`, `ignore`, `allow_fallbacks` and `sort` are accepted and ignored. With the OpenAI SDK, send it in `extra_body`.", "properties": { "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } } } }, "example": { "model": "hexgrad/kokoro-82m", "input": "Your order has shipped.", "voice": "af_heart", "response_format": "mp3" } } } }, "responses": { "200": { "description": "The audio: `audio/mpeg`, or `audio/pcm` at the provider's rate, with `Cache-Control: no-store` and the `X-Generation-Id` header." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/generation": { "get": { "operationId": "get-generation", "summary": "Get a generation", "description": "One finished request's record and cost, by its generation ID: the `X-Generation-Id` an image or audio answer carries, or for any request `gen-` and the 32 hex digits of its `x-request-id`, which is `request-` and the same digits. It reads any finished request of your key's organization. `total_cost` and `usage` are what you were charged in US dollars; `api_type` is `completions` (Chat Completions, Responses and Messages), `embeddings`, `image`, `stt` or `tts`. Never cached.", "tags": [ "Inference" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The generation ID, such as `gen-` and 32 hex digits.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OpenRouter's `GenerationResponse`, as `{\"data\": ...}`, with `model`, `provider_name`, `latency` and `generation_time` in milliseconds, and `data_region` (`europe` for a provider in the EU, else `global`).", "content": { "application/json": { "example": { "data": { "id": "gen-...", "model": "hexgrad/kokoro-82m", "api_type": "tts", "provider_name": "DeepInfra", "total_cost": 0.00002277, "is_byok": false, "upstream_inference_cost": null } } } } }, "400": { "description": "No `id` (`invalid_parameter` on `id`)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Another organization's ID, a malformed one, or one whose request has not finished." } } } }, "/api/v1/models": { "get": { "operationId": "list-models", "summary": "List models", "description": "The models your key can call, in OpenRouter's shape. Prices are decimal strings in US dollars per token. An audio model's `prompt` price is per second of audio or per character of input; an image model lists its output price in `image_output`, and a model priced per image adds `image_token`. With a key, a model carries `reasoning_efforts` where its provider lists them. A speech-to-text model carries `verbose_json`, and a text-to-speech model `supported_voices`, `default_voice` and `speech_speed`. Without an `Authorization` header it lists the public models, priced at each model's first-ranked public provider.", "tags": [ "Models" ], "security": [ { "bearer": [] }, {} ], "parameters": [ { "name": "output_modalities", "in": "query", "description": "`text` by default; `all` lists every model, and a comma list such as `text,embeddings` lists models that produce any of them. The values are `text`, `image`, `embeddings`, `transcription` (speech to text) and `speech` (text to speech).", "schema": { "type": "string", "default": "text" } }, { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer" } }, { "name": "region", "in": "query", "description": "`eu` lists only models with an EU provider, priced over those providers. It changes the listing, never how a call routes.", "schema": { "type": "string", "enum": [ "eu" ] } } ], "responses": { "200": { "description": "`data`, `total_count` (the matches before paging) and `links`.", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "deepseek/deepseek-v4.1-flash", "canonical_slug": "deepseek/deepseek-v4.1-flash", "name": "DeepSeek: DeepSeek V4.1 Flash", "description": "DeepSeek V4.1 Flash is a sparse mixture-of-experts model from DeepSeek...", "created": 1792497912, "context_length": 1048576, "architecture": { "input_modalities": [ "text", "image" ], "output_modalities": [ "text" ], "modality": "text+image->text" }, "pricing": { "prompt": "0.0000002", "completion": "0.0000006", "input_cache_read": "0.000000006" }, "top_provider": { "is_moderated": false, "context_length": 1048576, "max_completion_tokens": 131072 }, "per_request_limits": null, "supported_parameters": [ "max_tokens", "response_format", "structured_outputs", "temperature", "tool_choice", "tools" ], "links": { "details": "/api/v1/models/deepseek/deepseek-v4.1-flash/endpoints" } } ], "total_count": 54, "links": { "next": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/models/{author}/{slug}": { "get": { "operationId": "get-model", "summary": "Get a model", "description": "One model, as the bare model object. A model whose name has no `/` is `GET /api/v1/models/{model_id}`, and `GET /api/v1/model/{author}/{slug}` answers the same model wrapped as `{\"data\": ...}`. Works without a key for a public model.", "tags": [ "Models" ], "security": [ { "bearer": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/Author" }, { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "The model.", "content": { "application/json": { "example": { "id": "deepseek/deepseek-v4.1-flash", "canonical_slug": "deepseek/deepseek-v4.1-flash", "name": "DeepSeek: DeepSeek V4.1 Flash", "description": "DeepSeek V4.1 Flash is a sparse mixture-of-experts model from DeepSeek...", "created": 1792497912, "context_length": 1048576, "architecture": { "input_modalities": [ "text", "image" ], "output_modalities": [ "text" ], "modality": "text+image->text" }, "pricing": { "prompt": "0.0000002", "completion": "0.0000006", "input_cache_read": "0.000000006" }, "top_provider": { "is_moderated": false, "context_length": 1048576, "max_completion_tokens": 131072 }, "per_request_limits": null, "supported_parameters": [ "max_tokens", "response_format", "structured_outputs", "temperature", "tool_choice", "tools" ], "links": { "details": "/api/v1/models/deepseek/deepseek-v4.1-flash/endpoints" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/models/{author}/{slug}/endpoints": { "get": { "operationId": "list-endpoints", "summary": "List a model's endpoints", "description": "One endpoint per provider that may serve the model to you, each with its own prices, context length and output limit, its `tag` for `provider.order` and `provider.only`, and its recent uptime, latency and throughput. `pricing.discount` is the fraction a running provider discount takes off, with the prices already discounted. llm.buzz's own provider is one endpoint, `provider_name` `llm.buzz` and `tag` `llm-buzz`, priced at the lowest live direct price of each component. `GET /api/v1/models/{model_id}/endpoints` for a name with no `/`.", "tags": [ "Models" ], "security": [ { "bearer": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/Author" }, { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "The model and its endpoints, as `{\"data\": ...}`.", "content": { "application/json": { "example": { "data": { "id": "deepseek/deepseek-v4.1-flash", "name": "DeepSeek: DeepSeek V4.1 Flash", "endpoints": [ { "name": "DeepInfra | DeepSeek: DeepSeek V4.1 Flash", "provider_name": "DeepInfra", "tag": "deepinfra", "context_length": 1048576, "max_completion_tokens": 131072, "quantization": null, "supports_implicit_caching": true, "status": 0, "uptime_last_1d": 100, "latency_last_30m": null, "throughput_last_30m": null, "pricing": { "prompt": "0.0000002", "completion": "0.0000006", "input_cache_read": "0.000000006", "discount": 0 } } ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/embeddings/models": { "get": { "operationId": "embeddings-models", "summary": "List embeddings models", "description": "The model list with `output_modalities=embeddings` fixed, in the shape of `GET /api/v1/models`: with a key, the embeddings models it can call; without one, the public ones. Each lists as `text->embeddings` with its context window and `pricing` `{prompt, completion: \"0\"}` in US dollars per token, no cache prices and empty `supported_parameters`.", "tags": [ "Models" ], "security": [ { "bearer": [] }, {} ], "parameters": [ { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`data`, `total_count` (the matches before paging) and `links`.", "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "qwen/qwen3-embedding-8b", "name": "Qwen: Qwen3 Embedding 8B", "context_length": 32768, "architecture": { "input_modalities": [ "text" ], "output_modalities": [ "embeddings" ], "modality": "text->embeddings" }, "pricing": { "prompt": "0.00000001", "completion": "0" }, "supported_parameters": [] } ], "total_count": 18, "links": { "next": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/images/models": { "get": { "operationId": "image-models", "summary": "List image models", "description": "OpenRouter's image model list: one entry per image model your key may call, with `architecture` (`text` in, `image` out), `supported_parameters`, `supports_streaming` (always `false`) and `endpoints`, the relative URL of its endpoints listing. `supported_parameters` names each field the model takes with its values: `resolution`, `aspect_ratio`, `quality`, `output_format`, `background` and `size` as enums of the declared values, `n` and `output_compression` as ranges, `seed` as a boolean. OpenRouter lists `size` as a boolean; here its enum says which sizes the model accepts. A key is required, and the answer is never cached.", "tags": [ "Models" ], "responses": { "200": { "description": "The image models, as `{\"data\": [...]}`.", "content": { "application/json": { "example": { "data": [ { "id": "qwen/qwen-image-3", "name": "Qwen: Qwen Image 3", "description": "...", "created": 1792900000, "architecture": { "input_modalities": [ "text" ], "output_modalities": [ "image" ] }, "supported_parameters": { "aspect_ratio": { "type": "enum", "values": [ "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3" ] }, "n": { "type": "range", "min": 1, "max": 6 } }, "supports_streaming": false, "endpoints": "/api/v1/images/models/qwen/qwen-image-3/endpoints" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/images/models/{author}/{slug}/endpoints": { "get": { "operationId": "image-model-endpoints", "summary": "List an image model's endpoints", "description": "One endpoint per provider that may serve the image model to you: `provider_name`, `provider_slug`, `provider_tag` (with `/eu` for an EU provider), `supported_parameters` as on the image model list, `allowed_passthrough_parameters` (always `[]`, since every field is checked against the model), `supports_streaming` (`false`) and `pricing` at your rate: an `input_text` and an `output_image` line in US dollars per token for a model priced per token, one `output_image` line with the price of one image for a model priced per image. `GET /api/v1/images/models/{model_id}/endpoints` for a name with no `/`. A key is required, and the answer is never cached.", "tags": [ "Models" ], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The part of the model's name before `/`, such as `qwen`.", "schema": { "type": "string" }, "example": "qwen" }, { "name": "slug", "in": "path", "required": true, "description": "The part after `/`, such as `qwen-image-3`.", "schema": { "type": "string" }, "example": "qwen-image-3" } ], "responses": { "200": { "description": "The model's `id` and its `endpoints`.", "content": { "application/json": { "example": { "id": "qwen/qwen-image-3", "endpoints": [ { "provider_name": "Alibaba", "provider_slug": "alibaba", "provider_tag": "alibaba", "supported_parameters": { "aspect_ratio": { "type": "enum", "values": [ "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3" ] }, "n": { "type": "range", "min": 1, "max": 6 } }, "allowed_passthrough_parameters": [], "supports_streaming": false, "pricing": [ { "billable": "output_image", "unit": "image", "cost_usd": 0.03 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No model has this name or your key may not call it; a model that makes no images answers a 404 naming `GET /api/v1/images/models`." } } } }, "/api/v1/key": { "get": { "operationId": "get-key", "summary": "Get the current key", "description": "The key you send, inference or management, in OpenRouter's current-key shape: its `label`, `limit`, `limit_remaining` and `limit_reset`, its spend over its life (`usage`) and in the current UTC day, week and month, `expires_at`, `is_management_key`, and `is_free_tier`, `true` until your organization has bought credit. A key with a limit has one entry in `budgets`, whose `resets_at` says when its period ends (`null` for a lifetime limit). USD amounts are JSON numbers.", "tags": [ "Account" ], "responses": { "200": { "description": "The key, as `{\"data\": ...}`.", "content": { "application/json": { "example": { "data": { "label": "CI key", "limit": 5, "limit_remaining": 3.75, "limit_reset": "monthly", "include_byok_in_limit": false, "usage": 1.25, "usage_daily": 0.5, "usage_weekly": 1.25, "usage_monthly": 1.25, "is_free_tier": false, "is_management_key": false, "is_provisioning_key": false, "expires_at": null, "budgets": [ { "scope": "key_limit", "limit_usd": 5, "spend_usd": 1.25, "remaining_usd": 3.75, "reset_interval": "monthly", "resets_at": "2026-11-01T00:00:00Z" } ], "workspace_id": "default", "allowed_data_regions": [ "global", "europe", "us" ] } } } } }, "401": { "$ref": "#/components/responses/AccountUnauthorized" } } } }, "/api/v1/credits": { "get": { "operationId": "get-credits", "summary": "Get credits", "description": "Your organization's prepaid credit: `total_credits`, the credit it has added, and `total_usage`, what it has spent, in US dollars. Zeros before any credit.", "tags": [ "Account" ], "responses": { "200": { "description": "The credit, as `{\"data\": ...}`.", "content": { "application/json": { "example": { "data": { "total_credits": 25, "total_usage": 3.25 } } } } }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" } } } }, "/api/v1/keys": { "get": { "operationId": "list-keys", "summary": "List keys", "description": "Your unrevoked inference keys, newest first, 100 per page; never a management key.", "tags": [ "Account" ], "parameters": [ { "name": "offset", "in": "query", "description": "Keys to skip.", "schema": { "type": "integer" } }, { "name": "include_disabled", "in": "query", "description": "`true` adds disabled keys.", "schema": { "type": "boolean", "default": false } }, { "name": "include_expired", "in": "query", "description": "`true` adds expired keys.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The keys, as `{\"data\": [...]}`.", "content": { "application/json": { "example": { "data": [ { "hash": "...", "name": "CI key", "label": "CI key", "disabled": false, "created_at": "...", "updated_at": null, "expires_at": null, "last_used_at": null, "limit": 5, "limit_remaining": 5, "limit_reset": "monthly", "include_byok_in_limit": false, "usage": 0, "usage_daily": 0, "usage_weekly": 0, "usage_monthly": 0, "byok_usage": 0, "byok_usage_daily": 0, "byok_usage_weekly": 0, "byok_usage_monthly": 0, "creator_user_id": "...", "external_user": null, "workspace_id": "default" } ] } } } }, "400": { "$ref": "#/components/responses/AccountBadRequest" }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" } } }, "post": { "operationId": "create-key", "summary": "Create a key", "description": "Creates an inference key of your own. The answer, 201, carries the key object in `data` and the key itself in `key`, which no later answer repeats. OpenRouter's other create fields, such as `include_byok_in_limit` and `workspace_id`, are accepted and ignored, except `external.api_key`, which is a 400: llm.buzz issues its own keys.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "1 to 64 characters." }, "limit": { "type": "number", "description": "A spending limit in US dollars, at most nine decimal places; `null` for none." }, "limit_reset": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "The limit's period in UTC, a week starting on Monday; `null` counts the key's whole life." }, "expires_at": { "type": "string", "description": "When the key expires: ISO 8601 with seconds and an offset, in the future, such as `2027-12-31T23:59:59Z`. Omitted, it never expires." } } }, "example": { "name": "CI key", "limit": 5, "limit_reset": "monthly" } } } }, "responses": { "201": { "description": "The key object and the key.", "content": { "application/json": { "example": { "data": { "hash": "...", "name": "CI key", "label": "CI key", "disabled": false, "created_at": "...", "updated_at": null, "expires_at": null, "last_used_at": null, "limit": 5, "limit_remaining": 5, "limit_reset": "monthly", "include_byok_in_limit": false, "usage": 0, "usage_daily": 0, "usage_weekly": 0, "usage_monthly": 0, "byok_usage": 0, "byok_usage_daily": 0, "byok_usage_weekly": 0, "byok_usage_monthly": 0, "creator_user_id": "...", "external_user": null, "workspace_id": "default" }, "key": "exp_vk_..." } } } }, "400": { "$ref": "#/components/responses/AccountBadRequest" }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" } } } }, "/api/v1/keys/{hash}": { "get": { "operationId": "get-key-by-hash", "summary": "Get a key", "description": "One of your inference keys, by its `hash`.", "tags": [ "Account" ], "parameters": [ { "$ref": "#/components/parameters/KeyHash" } ], "responses": { "200": { "description": "The key, as `{\"data\": ...}`.", "content": { "application/json": { "example": { "data": { "hash": "...", "name": "CI key", "label": "CI key", "disabled": false, "created_at": "...", "updated_at": null, "expires_at": null, "last_used_at": null, "limit": 5, "limit_remaining": 5, "limit_reset": "monthly", "include_byok_in_limit": false, "usage": 0, "usage_daily": 0, "usage_weekly": 0, "usage_monthly": 0, "byok_usage": 0, "byok_usage_daily": 0, "byok_usage_weekly": 0, "byok_usage_monthly": 0, "creator_user_id": "...", "external_user": null, "workspace_id": "default" } } } } }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" }, "404": { "$ref": "#/components/responses/KeyNotFound" } } }, "patch": { "operationId": "update-key", "summary": "Update a key", "description": "Changes a key's `name`, `disabled`, `limit` or `limit_reset`. A body that sets none of them answers 400 `invalid_request`; `include_byok_in_limit` and unknown fields are ignored.", "tags": [ "Account" ], "parameters": [ { "$ref": "#/components/parameters/KeyHash" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "1 to 64 characters." }, "disabled": { "type": "boolean", "description": "`true` disables the key, `false` enables it again." }, "limit": { "type": "number", "description": "A spending limit in US dollars, at most nine decimal places; `null` for none." }, "limit_reset": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "The limit's period in UTC, a week starting on Monday; `null` counts the key's whole life." } } }, "example": { "limit": 10, "limit_reset": "weekly" } } } }, "responses": { "200": { "description": "The changed key, as `{\"data\": ...}`.", "content": { "application/json": { "example": { "data": { "hash": "...", "name": "CI key", "label": "CI key", "disabled": false, "created_at": "...", "updated_at": null, "expires_at": null, "last_used_at": null, "limit": 5, "limit_remaining": 5, "limit_reset": "monthly", "include_byok_in_limit": false, "usage": 0, "usage_daily": 0, "usage_weekly": 0, "usage_monthly": 0, "byok_usage": 0, "byok_usage_daily": 0, "byok_usage_weekly": 0, "byok_usage_monthly": 0, "creator_user_id": "...", "external_user": null, "workspace_id": "default" } } } } }, "400": { "$ref": "#/components/responses/AccountBadRequest" }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" }, "404": { "$ref": "#/components/responses/KeyNotFound" } } }, "delete": { "operationId": "delete-key", "summary": "Revoke a key", "description": "Revokes the key for good. The answer is `{\"deleted\": true}`, also when another request revoked it first.", "tags": [ "Account" ], "parameters": [ { "$ref": "#/components/parameters/KeyHash" } ], "responses": { "200": { "description": "The key is revoked.", "content": { "application/json": { "example": { "deleted": true } } } }, "401": { "$ref": "#/components/responses/AccountUnauthorized" }, "403": { "$ref": "#/components/responses/ManagementKeyRequired" }, "404": { "$ref": "#/components/responses/KeyNotFound" } } } }, "/public/v1/site": { "get": { "operationId": "public-site", "summary": "Site facts", "description": "Counts of public models and providers, the standard rate, and the billing facts: the card fee, the smallest and largest top-up, auto top-up and the refund window. Amounts are in US cents and rates in basis points. It is the website's data, not a stable API.", "tags": [ "Public catalog" ], "security": [ {} ], "responses": { "200": { "description": "The site document.", "content": { "application/json": { "example": { "schema_version": 1, "generated_at": "2026-10-26T03:02:52Z", "revision": 915, "counts": { "models": 85, "providers": 11, "independent_providers": 1, "eu_providers": 3, "tokens_4w": null }, "standard_rate_bps": 0, "provider_cut_bps": 0, "billing": { "enforced": true, "purchases": true, "fee_bps": 550, "fee_minimum_cents": 80, "minimum_cents": 500, "maximum_cents": 2500000, "auto_topup": true, "refund_window_hours": 24 }, "minimum_organizations": 5, "provider_performance": true, "provider_usage": true } } } }, "400": { "$ref": "#/components/responses/PublicBadRequest" }, "503": { "$ref": "#/components/responses/PublicBusy" } } } }, "/public/v1/models": { "get": { "operationId": "public-models", "summary": "Public models", "description": "Every public model, at most 1,000, by name, with its price, features, providers, EU and data-policy flags, and published metrics. Prices are decimal strings in US dollars per million units of `price_unit`: `token`, `second` of audio, `character` of input text, or `image`. They are those of the model's first-ranked live provider. It is the website's data, not a stable API.", "tags": [ "Public catalog" ], "security": [ {} ], "responses": { "200": { "description": "The model list.", "content": { "application/json": { "example": { "schema_version": 1, "generated_at": "2026-10-26T03:02:52Z", "revision": 915, "truncated": false, "models": [ { "name": "deepseek/deepseek-v4.1-flash", "display_name": "DeepSeek: DeepSeek V4.1 Flash", "author": "deepseek", "author_name": "DeepSeek", "input_modalities": [ "text", "image" ], "output_modalities": [ "text" ], "context_length": 1048576, "max_output_tokens": 131072, "features": [ "tools", "structured_output", "caching" ], "open_weights": true, "providers": { "live": 3, "paused": 0 }, "provider_names": [ "DeepInfra", "Scaleway", "Prime Intellect" ], "eu_available": true, "free": false, "available": true, "price_varies": true, "price_unit": "token", "price": { "input": "0.2", "output": "0.6", "cache_read": "0.006", "cache_write": "0", "cache_write_1h": "0", "reasoning": "0.6" }, "price_discount": null } ] } } } }, "400": { "$ref": "#/components/responses/PublicBadRequest" }, "503": { "$ref": "#/components/responses/PublicBusy" } } } }, "/public/v1/models/{author}/{slug}": { "get": { "operationId": "public-model", "summary": "Public model", "description": "One public model with its providers in rank order, each with its prices, limits, residency, data policy and metrics, plus the model's uptime, usage, questions and similar models. `auto_price` is `true` on the row of llm.buzz's own provider, whose prices are the lowest live direct price of each component (the Auto price). A model whose name has no `/` is `GET /public/v1/models/{name}`. Send the name's `/` as it is: an encoded `%2F` is a 404. It is the website's data, not a stable API.", "tags": [ "Public catalog" ], "security": [ {} ], "parameters": [ { "$ref": "#/components/parameters/Author" }, { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "The model document.", "content": { "application/json": { "example": { "schema_version": 1, "model": { "name": "deepseek/deepseek-v4.1-flash", "display_name": "DeepSeek: DeepSeek V4.1 Flash", "author": "deepseek", "author_name": "DeepSeek", "input_modalities": [ "text", "image" ], "output_modalities": [ "text" ], "context_length": 1048576, "max_output_tokens": 131072, "features": [ "tools", "structured_output", "caching" ], "open_weights": true, "providers": { "live": 3, "paused": 0 }, "provider_names": [ "DeepInfra", "Scaleway", "Prime Intellect" ], "eu_available": true, "free": false, "available": true, "price_varies": true, "price_unit": "token", "price": { "input": "0.2", "output": "0.6", "cache_read": "0.006", "cache_write": "0", "cache_write_1h": "0", "reasoning": "0.6" }, "price_discount": null }, "providers": [ { "rank": 1, "slug": "deepinfra", "tag": "deepinfra", "display_name": "DeepInfra", "type": "cloud", "residency": "non-eu", "state": "live", "context_length": 1048576, "max_output_tokens": 131072, "prices": { "input": "0.2", "output": "0.6", "cache_read": "0.006", "cache_write": "0", "cache_write_1h": "0", "reasoning": "0.6" }, "discount": null, "auto_price": false, "cache_capable": true, "data_policy": null } ] } } } }, "400": { "$ref": "#/components/responses/PublicBadRequest" }, "404": { "description": "No public model has this name: `no public model named 'acme/nope'; see /public/v1/models`." }, "503": { "$ref": "#/components/responses/PublicBusy" } } } }, "/public/v1/providers": { "get": { "operationId": "public-providers", "summary": "Public providers", "description": "Every public provider: its slug, display name, description, logo, type (`cloud` or `independent`), residency (`eu` or `non-eu`), declared data policy, the number of models it serves live and when it first appeared. `llm-buzz` is llm.buzz's own provider, priced at the lowest live direct price of each component of each model. It is the website's data, not a stable API.", "tags": [ "Public catalog" ], "security": [ {} ], "responses": { "200": { "description": "The provider list.", "content": { "application/json": { "example": { "schema_version": 1, "generated_at": "2026-10-26T03:02:52Z", "revision": 915, "providers": [ { "slug": "llm-buzz", "display_name": "llm.buzz", "description": "llm.buzz's own routes to a model. They bill each model at its best direct provider's price, shown with the Auto tag, and take part in routing and failover like any other provider.", "logo_url": "/public/v1/logos/bbda16277217d4e6bcb4e654d96d6e5a6efd6e4edc7fdd403e1b68d104270c66.svg", "type": "cloud", "residency": "non-eu", "eu": false, "data_policy": null, "models": 36, "first_seen_at": null }, { "slug": "scaleway", "display_name": "Scaleway", "description": "The French cloud provider, part of the iliad group. Its Generative APIs serve open-weight models from data centers in France.", "logo_url": "/public/v1/logos/b8f6af777a33df860fb3629e6247044b9de981f63a85ce1b0a340310f5d3332d.png", "type": "cloud", "residency": "eu", "eu": true, "data_policy": null, "models": 10, "first_seen_at": "2026-10-21T09:23:58Z" } ] } } } }, "400": { "$ref": "#/components/responses/PublicBadRequest" }, "503": { "$ref": "#/components/responses/PublicBusy" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A key from the console's Keys page, as `Authorization: Bearer KEY`: an inference key on the model routes, a management key on `/api/v1/credits` and `/api/v1/keys`." }, "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "An inference key in `x-api-key`, the header the Anthropic SDK sends. Messages and count tokens only." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "A retry with the same key and the same body never runs the request twice: it returns the first answer, or 409 `idempotency_replay_unavailable` when that answer is not stored where the retry arrived. Send the same key again only when the first call got no answer, or after an answer carrying `x-gateway-admission-refused: true`; after any other error answer send a new key. A retry without the key, or with a new one, runs and bills the request again. Reusing a key with a different body answers 409 `idempotency_conflict`.", "schema": { "type": "string" } }, "SessionHeader": { "name": "x-session-id", "in": "header", "description": "Names the conversation, as `session_id` does, so its turns stay on the provider that holds its cache.", "schema": { "type": "string" } }, "Author": { "name": "author", "in": "path", "required": true, "description": "The part of the model's name before `/`, such as `deepseek`.", "schema": { "type": "string" }, "example": "deepseek" }, "Slug": { "name": "slug", "in": "path", "required": true, "description": "The part after `/`, such as `deepseek-v4.1-flash`.", "schema": { "type": "string" }, "example": "deepseek-v4.1-flash" }, "KeyHash": { "name": "hash", "in": "path", "required": true, "description": "The key's `hash`, as `GET /api/v1/keys` lists it.", "schema": { "type": "string" } } }, "schemas": { "ModelName": { "type": "string", "description": "A model's name from `GET /api/v1/models`, such as `deepseek/deepseek-v4.1-flash`. A suffix changes one request: `:floor` tries the cheapest provider first and `:nitro` the fastest. On Chat Completions and Responses `:online` asks for a web search, which llm.buzz does not run today: the request is served without one and `x-sgr-ignored-parameters` names `web_search->dropped(search_unavailable)`, or for an organization whose requests llm.buzz keeps in the EU it answers 400 `web_search_unavailable_in_region`. On Messages `:online` does nothing and is named as `model:online`." }, "SessionId": { "type": "string", "description": "A name for the conversation, 1 to 256 characters, so its turns stay on the provider that holds its cache." }, "CacheControl": { "type": "object", "description": "Anthropic's prompt-cache marker, `{\"type\": \"ephemeral\"}` with an optional `ttl` of `\"5m\"` or `\"1h\"`. llm.buzz passes it on and never adds one. Claude models cache only where a request marks it." }, "PromptCacheOptions": { "type": "object", "description": "OpenAI's explicit caching, for GPT-5.6 and later models: `mode` `implicit` (OpenAI's default) or `explicit` (OpenAI writes the cache only at a `prompt_cache_breakpoint`), and `ttl` `30m`." }, "PromptCacheRetention": { "type": "string", "enum": [ "in_memory", "24h" ], "description": "OpenAI's cache retention. `24h` with `provider.zdr`, `provider.data_collection: \"deny\"` or your organization's no-retention policy is a 400 `invalid_request`." }, "AnthropicSystem": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The system prompt: a string, or a list of text blocks, which may carry `cache_control`." }, "EndUser": { "type": "string", "description": "Your end user's label, recorded and never forwarded." }, "ImageModelName": { "type": "string", "description": "An image model from `GET /api/v1/images/models`, such as `qwen/qwen-image-3`; a chat or embeddings model is a 400 on `model`. The `:floor` and `:nitro` suffixes work as on chat." }, "ImagePrompt": { "type": "string", "description": "What to draw, 1 to 32,000 characters." }, "ImageCount": { "type": "integer", "default": 1, "description": "How many images, 1 to 10 and at most the model's most images per request." }, "ImageChoice": { "type": "string", "description": "A value the model declares; a model that declares none ignores the field." }, "ImageFormat": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "description": "A format the model declares; a model that declares none ignores the field." }, "KeyLimit": { "type": "number", "description": "A spending limit in US dollars, at most nine decimal places; `null` for none." }, "KeyLimitReset": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "The limit's period in UTC, a week starting on Monday; `null` counts the key's whole life." }, "Reasoning": { "type": "object", "description": "Reasoning controls, translated for each provider.", "properties": { "effort": { "type": "string", "description": "How hard the model thinks. An effort the model does not take becomes the nearest one it does, named in `x-sgr-ignored-parameters`." }, "max_tokens": { "type": "integer", "description": "A reasoning budget in tokens." }, "enabled": { "type": "boolean", "description": "Turn reasoning on or off." }, "exclude": { "type": "boolean", "description": "Keep the reasoning text out of the answer while the model still reasons." } } }, "ProviderPreferences": { "type": "object", "description": "Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.", "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "Try these providers first, in this order, then the others. At most 64 names." }, "only": { "type": "array", "items": { "type": "string" }, "description": "Use only these providers." }, "ignore": { "type": "array", "items": { "type": "string" }, "description": "Never use these providers." }, "allow_fallbacks": { "type": "boolean", "description": "`false` stops moving to other providers." }, "sort": { "type": "string", "enum": [ "price", "throughput", "latency", "smart" ], "description": "The order to try providers in. Ignored when `order` is set." }, "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "AudioProviderPreferences": { "type": "object", "description": "The audio routes read only the data policy fields; `order`, `only`, `ignore`, `allow_fallbacks` and `sort` are accepted and ignored. With the OpenAI SDK, send it in `extra_body`.", "properties": { "zdr": { "type": "boolean", "description": "`true` keeps the request on providers that declare 0 days of retention." }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` keeps the request on providers that declare no training and 0 days of retention." } } }, "Error": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } } }, "responses": { "BadRequest": { "description": "A field is missing or malformed (`invalid_request`, with `metadata.param`), or the model cannot do what the request asks (`unsupported_capability`).", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 400, "message": "...", "metadata": { "error_type": "invalid_request", "gateway_code": "invalid_request", "param": "messages" } } } } } }, "ImageBadRequest": { "description": "Before any provider call: a field is missing or malformed, or names a size, ratio, tier or value the model does not declare, or `n` is above its most images. `metadata.param` names the field, and the message what to send. A chat or embeddings model, `input_references`, `stream: true`, `output_format: \"svg\"` and `response_format: \"url\"` are refused the same way.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 400, "message": "qwen/qwen-image-3 serves aspect_ratio 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3; resend with one of them.", "metadata": { "error_type": "invalid_request", "gateway_code": "invalid_parameter", "param": "aspect_ratio" } } } } } }, "Unauthorized": { "description": "No key, or the key is unknown, expired, revoked or disabled.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 401, "message": "A valid gateway Bearer key is required. Send the virtual key as 'Authorization: Bearer '.", "metadata": { "error_type": "authentication", "gateway_code": "invalid_key" } } } } } }, "PaymentRequired": { "description": "Your balance is spent and the model is not free, or the request could cost more than your balance.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 402, "message": "...", "metadata": { "error_type": "payment_required", "gateway_code": "insufficient_credits" } } } } } }, "NotFound": { "description": "No model has this name, or your key may not call it.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 404, "message": "The requested model does not exist or is not granted to this key. GET /api/v1/models lists the model aliases available to this key.", "metadata": { "error_type": "not_found", "gateway_code": "model_not_found", "param": "model" } } } } } }, "Conflict": { "description": "The `Idempotency-Key` was used before. `idempotency_replay_unavailable`: the first request was accepted, and its answer is not stored where this retry arrived, so it was not run again; retry with the same key after a short backoff first, when the first call got no answer, and send a new key to run the request again (it is billed again) or after an error answer. `idempotency_conflict`: the key came with a different body; use a new key for each distinct request. Neither runs the request again.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 409, "message": "...", "metadata": { "error_type": "invalid_request", "gateway_code": "idempotency_replay_unavailable", "param": "Idempotency-Key" } } } } } }, "Throttled": { "description": "Providers are throttling, or the model is at capacity (`unavailable_route`): retry after `Retry-After` seconds. Or a free offer's allowance is used (`free_allowance_exceeded`): your organization's tokens, or your key's requests per minute. Choose a paid model, or for the per-minute limit retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 429, "message": "...", "metadata": { "error_type": "rate_limit_exceeded", "gateway_code": "unavailable_route" } } } } } }, "AnthropicBadRequest": { "description": "A field is missing or malformed, or the model cannot do what the request asks, in Anthropic's error body as an `invalid_request_error`; the message names the field.", "content": { "application/json": { "example": { "type": "error", "error": { "type": "invalid_request_error", "message": "..." } } } } }, "AnthropicError": { "description": "Messages keeps Anthropic's error body: a 401 is an `authentication_error`, a 402 a `billing_error`, a 403 a `permission_error` and a 429 a `rate_limit_error`.", "content": { "application/json": { "example": { "type": "error", "error": { "type": "authentication_error", "message": "A valid API key is required: send x-api-key or Authorization: Bearer." } } } } }, "AccountUnauthorized": { "description": "No `Authorization` header (`missing_authentication`), or the key is unknown, expired, revoked or disabled (`invalid_key`).", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 401, "message": "Missing Authentication header", "metadata": { "error_type": "authentication", "gateway_code": "missing_authentication" } } } } } }, "ManagementKeyRequired": { "description": "An inference key called a route that takes a management key. Create one on the console's Keys page.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 403, "message": "Only management keys can perform this operation; use a management key, created on the console Keys page", "metadata": { "error_type": "permission_denied", "gateway_code": "management_key_required" } } } } } }, "KeyNotFound": { "description": "The hash names none of your inference keys.", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 404, "message": "No API key has this hash. GET /api/v1/keys lists the keys you manage.", "metadata": { "error_type": "not_found", "gateway_code": "key_not_found", "param": "hash" } } } } } }, "AccountBadRequest": { "description": "The body is not JSON (`invalid_json`), a field or query value is invalid (`invalid_parameter`, with `metadata.param`), or a `PATCH` sets no field (`invalid_request`).", "content": { "application/json": { "schema": { "type": "object", "description": "Every error on a model route. Branch on `metadata.gateway_code`.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status." }, "message": { "type": "string", "description": "What went wrong and what to do." }, "metadata": { "type": "object", "description": "`gateway_code`, `error_type` (OpenRouter's type) and `param`, the field at fault." } } } } }, "example": { "error": { "code": 400, "message": "...", "metadata": { "error_type": "invalid_request", "gateway_code": "invalid_parameter", "param": "limit" } } } } } }, "PublicBadRequest": { "description": "A query string other than `revision`, a whole number. The body is `{\"error\": {\"code\", \"message\"}}`.", "content": { "application/json": { "example": { "error": { "code": 400, "message": "the only query parameter is revision, a whole number" } } } } }, "PublicBusy": { "description": "The public data is busy, or the request pinned a `revision` this server has not published yet. Retry after a second, as `Retry-After: 1` says.", "content": { "application/json": { "example": { "error": { "code": 503, "message": "the public data is busy" } } } } } } } }