{ "openapi": "3.1.0", "info": { "version": "1.4.0", "title": "Vultr Inference API", "description": "Public customer API. Private Vultr integration routes that require the platform key are not included.", "contact": { "email": "support@vultr.com", "name": "", "url": "https://www.vultr.com" }, "x-logo": { "url": "https://api.vultrinference.com/brand/vsi-lockup.svg", "backgroundColor": "#fafafa", "altText": "Vultr Serverless Inference" } }, "servers": [ { "url": "https://api.vultrinference.com/v1" } ], "paths": { "/messages": { "post": { "summary": "Create Message", "tags": [ "Messages" ], "description": "Create a Message using the Anthropic Messages API format. This endpoint accepts Anthropic-native request payloads and returns Anthropic-native responses. The request is adapted internally to the underlying chat completions engine.\n\n**System prompt:** Use the top-level `system` parameter for initial instructions. A later text-only `system` message may follow a `user` message; it may be last or precede an `assistant` message.\n\n**Content blocks:** Message `content` may be a string or an array of typed content blocks (`text`, `image`, `tool_use`, `tool_result`).\n\n**Assistant prefill:** If the final message uses the `assistant` role, the response continues immediately from that content.\n\n**Streaming:** Set `stream: true` to receive server-sent events with typed event names (`message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop`).\n\n**Extended thinking:** `thinking.type: enabled` requires `budget_tokens` below `max_tokens` and a model that supports enforced thinking budgets; other models reject this mode. Check `reasoning.supports_max_tokens` in `/v1/models?format=openrouter` (in the default list, a `max_tokens` property under the text output's `reasoning` parameter). `adaptive` uses the model's own thinking behavior, and `disabled` turns thinking off. Thinking blocks use API-generated signatures, and `display: omitted` hides their text while preserving a signature for continuation.\n\n**System instructions:** A later `system` message keeps its position when forwarded to the model. Turn-scoped `clear_at` and per-message `output_config` are not supported.\n\n**Effort:** Top-level `output_config.effort` maps through the selected model's `reasoning_config`. The `:express` model variant derives a thinking budget when the selected model supports enforced budgets and no budget is supplied.\n\n**Tools:** Tools use `input_schema` (JSON Schema) rather than `parameters`. Tool results are sent as `tool_result` content blocks in subsequent `user` messages.\n\n**Errors:** Errors use Anthropic's body, `{\"type\": \"error\", \"error\": {\"type\", \"message\"}}`. A request the gateway refuses is a 400 `invalid_request_error`; Anthropic has no 422. An unknown model is a 404 `not_found_error`, a rate-limited request a 429 `rate_limit_error` with `Retry-After`, a bad or missing key a 401 `authentication_error`, and a failure on our side or the engine's a 5xx `api_error`.\n", "operationId": "create-message", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-message-request-payload" }, "example": { "model": "deepseek-v4.1-flash", "max_tokens": 1024, "system": "Answer in one sentence.", "messages": [ { "role": "user", "content": "Why is the sky blue?" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-message-response-payload" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/anthropic-message-streaming-response-payload" } } } }, "400": { "description": "Bad Request (`invalid_request_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-error-payload" } } } }, "401": { "description": "Unauthorized (`authentication_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-error-payload" } } } }, "404": { "description": "Model not found (`not_found_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-error-payload" } } } }, "429": { "description": "Rate limited (`rate_limit_error`)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-error-payload" } } } }, "500": { "description": "Server error (`api_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/anthropic-error-payload" } } } } } } }, "/chat/completions": { "post": { "summary": "Create Chat Completion", "tags": [ "Chat" ], "description": "Create Chat Completion on a specified text generation model.\n\n**Continuation:** If the final message has the `assistant` role, the model continues that message instead of starting a new turn (the same convention as Anthropic and OpenRouter). Send a response that ended with `finish_reason` `length` back as the final assistant message to resume it. The message must be non-empty text without `tool_calls`, trailing whitespace is trimmed, thinking is disabled for the continuation, and only the new text is returned.\n\n**Response shape:** Responses follow OpenRouter's chat completion shape whichever engine serves the model. Reasoning is always in `reasoning` (never `reasoning_content`), usage always has `prompt_tokens_details.cached_tokens` and `completion_tokens_details.reasoning_tokens`, ids start with `chatcmpl-` and tool call ids with `call_`, `finish_reason` is one of `stop`, `length`, `tool_calls`, `content_filter` or `error` with the engine's own value in `native_finish_reason`, and engine-specific fields are removed. A `-normalize` model suffix is accepted for compatibility and ignored.\n\n**Errors:** Errors use OpenRouter's envelope, `{\"error\": {\"code\", \"message\", \"type\", \"metadata\": {\"error_type\"}}}`. A streaming request that fails before the first token gets the real HTTP status; one that fails later receives a final chunk carrying `error`.\n\n**Reasoning budget:** Set `reasoning.max_tokens` to limit thinking tokens. This limit must be below `max_completion_tokens` (or the effective context-clipped limit). Models with `reasoning.supports_max_tokens: true` in `/v1/models?format=openrouter` (a `max_tokens` property under the `reasoning` parameter in the default list) enforce the budget; other models accept the field without enforcing it. Requested effort maps through the model's `reasoning_config` when configured. The `:express` model variant derives a budget for models with enforced budget support when no budget is supplied.\n", "operationId": "create-chat-completion", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chat-completion-request-payload" }, "example": { "model": "deepseek-v4.1-flash", "messages": [ { "role": "system", "content": "Answer in one sentence." }, { "role": "user", "content": "Why is the sky blue?" } ], "max_completion_tokens": 512 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chat-completion-response-payload" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/chat-completion-streaming-response-payload" } } } }, "400": { "description": "Bad Request, including `context_length_exceeded`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. Wait at least this long before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "504": { "description": "The model timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "404": { "description": "No model by that name exists, or its row is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "503": { "$ref": "#/components/responses/models-unavailable" } } } }, "/responses": { "post": { "summary": "Create Response", "tags": [ "Responses" ], "description": "Create an OpenAI-compatible response. `reasoning.effort` maps through the selected model's `reasoning_config` when configured. `reasoning.max_tokens` caps thinking tokens when the model advertises `reasoning.supports_max_tokens: true` in `/v1/models?format=openrouter` (a `max_tokens` property under the `reasoning` parameter in the default list); other models accept the budget without enforcing it. `reasoning.context` and `reasoning.mode` are accepted but ignored. The `:express` model variant derives a budget for models with enforced budget support when no budget is supplied.\n\n**Response shape:** Responses follow OpenAI's Responses API object whichever engine serves the model, with the fields OpenRouter's SDKs require always present: `completed_at` is a unix timestamp once the response has finished, `error` is `null` or `{code, message}`, and `text` is an object. Function call ids start with `call_`, and engine-internal fields (`kv_transfer_params`, `input_messages`, `output_messages`, ...) are removed from the response and from every streamed event.\n\n**Tools:** `function`, `custom` and `namespace` tools, as Codex CLI sends them. A `custom` tool's call is a `custom_tool_call` item whose `input` is the raw text; its `format` grammar is described to the model, not enforced. A call to a tool of a `namespace` is a `function_call` with `namespace` set. Hosted tools (`web_search`, `file_search`, `code_interpreter`, `mcp`, ...) are refused with a 400 naming the type.\n\n**Stored responses:** Nothing is stored. `store` is accepted and ignored. `previous_response_id`, `conversation` and `background: true` are refused with a 400; send the whole conversation in `input`. [`GET`](#operation/get-response) and [`DELETE`](#operation/delete-response) on `/v1/responses/{id}` answer a 404 saying so.\n\n**Context window:** If input plus `max_output_tokens` passes the model's context length, `max_output_tokens` is reduced to fit; if the input alone does not fit the request is a 400 with `metadata.error_type` `context_length_exceeded`.\n\n**Errors:** Errors use OpenRouter's envelope, `{\"error\": {\"code\", \"message\", \"type\", \"metadata\": {\"error_type\"}}}`. A streaming request that fails before the first event gets the real HTTP status and the JSON envelope; one that fails later ends the stream with an `error` event and a `response.failed` event.\n", "operationId": "create-response", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response-create-request-payload" }, "example": { "model": "deepseek-v4.1-flash", "instructions": "Answer in one sentence.", "input": "Why is the sky blue?", "max_output_tokens": 512 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response-create-response-payload" } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of typed Responses API events, each `event: ` followed by `data: {...}`. The stream ends with `response.completed`, `response.incomplete` or `response.failed`." } } } }, "400": { "description": "Bad Request, including an unsupported tool type, `previous_response_id`, and `context_length_exceeded`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Unknown model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. Wait at least this long before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "504": { "description": "The model timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/responses/{id}": { "get": { "summary": "Get Response", "tags": [ "Responses" ], "description": "Always a 404. Responses are not stored, so there is nothing to retrieve; the error says so, for SDK calls that would otherwise get a bare \"no such endpoint\".", "operationId": "get-response", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/response-id" } ], "responses": { "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Responses are not stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "delete": { "summary": "Delete Response", "tags": [ "Responses" ], "description": "Always a 404. Responses are not stored, so there is nothing to delete.", "operationId": "delete-response", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/response-id" } ], "responses": { "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Responses are not stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/embeddings": { "post": { "summary": "Create Embeddings", "tags": [ "Embeddings" ], "description": "Embed text in OpenRouter's embeddings shape, which is OpenAI's with `input_type` and an `id` added.\n\n**Batches:** Up to 2048 inputs per request. The API splits them into batches the model's engine accepts and returns the embeddings in input order.\n\n**Queries and documents:** Instruction-aware models such as `qwen3-embedding-4b` retrieve better when queries carry an instruction. Set `input_type` to `search_query` on queries and the model's instruction is prepended; documents (`search_document`, or no `input_type`) are sent unchanged. A query that already starts with the instruction's marker (e.g. `Instruct:`) is not prefixed again. The prefix's tokens are billed.\n\n**Long inputs:** An input longer than the model's maximum input length is truncated to it, not rejected.\n", "operationId": "create-embeddings", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddings-request-payload" }, "example": { "model": "qwen3-embedding-4b", "input": [ "What is the capital of France?" ], "input_type": "search_query" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddings-response-payload" } } } }, "400": { "description": "The request body is not a JSON object, the model rejected the request, or an input is longer than the model's context length (`metadata.error_type` `context_length_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. Wait at least this long before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model could not be reached or returned an unusable response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "504": { "description": "The model timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "The request body is over 16 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/embeddings/models": { "get": { "summary": "List Embedding Models", "tags": [ "Embeddings" ], "description": "The live embedding models in OpenRouter's public model shape (`data`, `total_count`, `links`), for OpenRouter's `embeddings.listModels()`. Each entry has `output_modalities: [\"embeddings\"]`, the context length and the price per input token in `pricing.prompt`, the same as `GET /v1/models` lists for it. Public like `GET /v1/models`.", "operationId": "list-embedding-models", "security": [], "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Models to skip. Offset and limit both omitted is the whole list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Models per page, once offset or limit is set.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/openrouter-public-models-response" } } } }, "400": { "description": "Invalid offset or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "$ref": "#/components/responses/catalog-unavailable" } } } }, "/systemone": { "post": { "summary": "Create Decision", "tags": [ "Decisions" ], "description": "Answer typed questions about a state with a decision (\"System One\") model, in TypeSafe's `/v1/systemone` shape, so clients written for TypeSafe work by changing their base URL and key.\n\nA decision model reads the state once per question and generates no text: each answer is a probability distribution over the question's allowed answers.\n\n**Question types:** `noul` (yes/no) answers `noul`, the probability of yes. `choice` picks one of 1 to 255 options and answers the most likely `choice`, every option's `probabilities` and a `confidence`. `score` rates on 1 to 10 ordered levels and answers `score`, the probability-weighted level (it can land between levels), with a `legend`, `probabilities` and `confidence`.\n\n**Confidence** is 1 when the distribution is on one answer and 0 when it is spread evenly: (k * p_max - 1) / (k - 1) for k answers. `noul` answers carry none; read `noul` itself.\n\n**Long inputs** over the model's maximum input length are rejected with 422, never truncated.\n\n**Billing:** every question's prompt (the state, the question and its options) is billed as input tokens, so questions on a long state each bill the state. No output tokens are billed.\n", "operationId": "create-systemone", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/systemone-request-payload" }, "example": { "model": "mica-v0.1-4b", "state": { "ticket": "Everything is down and we have a demo at noon." }, "questions": { "urgent": { "type": "noul", "instructions": "Does the customer need a reply within the hour?" }, "department": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "invoices, payments, refunds", "technical": "bugs, outages, errors" } }, "frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": [ "Calm", "Frustrated", "Very angry" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/systemone-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "422": { "description": "The request failed validation, the model is not a decision model, or an input is over the model's length", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. Wait at least this long before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model returned an unusable response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "529": { "description": "The model is overloaded or unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/rerank": { "post": { "summary": "Rerank Documents", "tags": [ "Rerank" ], "description": "Rank documents by relevance to a query. Requests and responses follow OpenRouter's rerank schema whichever engine serves the model.", "operationId": "create-rerank", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rerank-request-payload" }, "example": { "model": "bge-reranker-v2-m3", "query": "What is the capital of France?", "documents": [ "Berlin is the capital of Germany.", "Paris is the capital of France." ], "top_n": 1 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rerank-response-payload" }, "example": { "id": "rerank-3f1c9a0d2b7e4c6a8d5e1f02", "model": "bge-reranker-v2-m3", "results": [ { "index": 1, "relevance_score": 0.9998499, "document": { "text": "Paris is the capital of France." } } ], "usage": { "total_tokens": 36 } } } } }, "400": { "description": "The request body is not a JSON object, `top_n` is over 100, the model rejected the request, or the input is longer than the model's context length (`metadata.error_type` `context_length_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model could not be reached or returned an unusable response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "504": { "description": "The model timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "The request body is over 16 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/chat/completions/RAG": { "post": { "summary": "RAG Chat Completion", "tags": [ "Chat" ], "description": "Create a chat completion with context retrieved from items or files in a vector store collection. Reasoning effort, thinking budget, and the express variant follow the Chat Completions behavior.", "operationId": "rag-chat-completion", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chat-rag-request-payload" }, "example": { "model": "deepseek-v4.1-flash", "collection": "handbook", "messages": [ { "role": "user", "content": "How many vacation days do new hires get?" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chat-completion-response-payload" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/chat-completion-streaming-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/audio/models": { "get": { "summary": "List Audio Models", "tags": [ "Audio" ], "deprecated": true, "description": "The speech and transcription models the API serves, with their price per second. Deprecated: `GET /v1/models?output_modalities=speech` (or `transcription`) lists the same models with everything they accept.", "operationId": "list-audio-models", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/audio-models-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/audio/speech": { "post": { "summary": "Create Speech", "tags": [ "Audio" ], "description": "Generate speech from text. OpenAI's request shape plus OpenRouter's, so both SDKs work unchanged. The response body is the audio itself.\n\n**Voices:** `voice` selects the mode as well as the voice. A built-in speaker (`GET /v1/audio/voices?model=` lists them) speaks the input, and `instructions` can direct its style. `design` creates a new voice from the description in `instructions`. `clone` (or leaving `voice` out) with `input_references` speaks in the voice of a reference clip: send it base64-encoded in `input_audio.data`, with its transcript in a `text` part for the closest match. Clip URLs are not accepted. A cloned voice cannot follow `instructions`.\n\n**Formats:** `response_format` is `mp3` (the default), `opus`, `flac`, `wav` or `pcm` (24 kHz 16-bit mono, labelled `audio/pcm;rate=24000;channels=1`). `aac` returns 400.\n\n**Streaming:** `stream_format` `audio` (the default) returns the audio; `pcm` at `speed` 1 streams as it is generated. `sse` returns `speech.audio.delta` events with base64 audio and a final `speech.audio.done` event with usage; `pcm` at `speed` 1 streams, other formats arrive as one delta. A failure mid-stream ends an SSE stream with a `speech.audio.error` event.\n\n**Billing:** Per second of audio generated, before `speed`, rounded up. The seconds and cost are in the `X-Usage-Seconds` and `X-Usage-Cost` headers, or in the `speech.audio.done` usage; a raw `pcm` stream reports neither.\n\nOpenRouter's `provider`, `user`, `session_id` and `trace` are accepted and ignored, except that `provider.options` under our OpenRouter slug can carry `instructions`, `language`, `speed`, `seed`, `temperature`, `top_p` and `top_k`.\n", "operationId": "create-speech", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/text-to-speech-request-payload" }, "example": { "model": "qwen3-tts-12hz-1.7b", "input": "Welcome to Vultr Serverless Inference.", "voice": "aiden", "instructions": "Warm and upbeat, like a radio host." } } } }, "responses": { "200": { "description": "The audio, or SSE events when `stream_format` is `sse`.", "headers": { "X-Generation-Id": { "schema": { "type": "string" } }, "X-Usage-Seconds": { "description": "Seconds billed. Absent on streamed responses.", "schema": { "type": "integer" } }, "X-Usage-Cost": { "description": "Cost in USD. Absent on streamed responses.", "schema": { "type": "string" } } }, "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request, such as an unknown voice or a voice that does not fit the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "$ref": "#/components/responses/rate-limited" } } } }, "/audio/transcriptions": { "post": { "summary": "Create Transcription", "tags": [ "Audio" ], "description": "Transcribe audio. The request can be OpenRouter's JSON form, with the audio base64-encoded in `input_audio`, or OpenAI's `multipart/form-data` upload with the audio in `file`. Both return the same response, so the OpenAI and OpenRouter SDKs work unchanged.\n\n**Audio:** Up to 25 MB after decoding and 4 hours long. Audio URLs are not accepted.\n\n**Formats:** `response_format` is `json` (the default) or `text`, which returns the bare transcript as `text/plain`. `verbose_json`, `timestamp_granularities`, `srt` and `vtt` are not supported and return 400.\n\n**Streaming:** With `stream: true` the response is OpenAI's server-sent events: `transcript.text.delta` events with each piece of the transcript as it is decoded, then one `transcript.text.done` with the whole `text` and the same `usage` as the JSON response. A failure after the stream began ends it with a `transcript.text.error` event in the error envelope. The upload still completes before decoding starts; this is not live audio.\n\n**Billing:** Per second of audio, rounded up, as reported in `usage.seconds`.\n", "operationId": "create-transcription", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transcription-json-request-payload" }, "example": { "model": "whisper-large-v3-turbo", "input_audio": { "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YQAAAAA=", "format": "wav" }, "language": "en" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/transcription-multipart-request-payload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transcription-response-payload" } }, "text/plain": { "schema": { "type": "string", "description": "The transcript, when `response_format` is `text`." } }, "text/event-stream": { "schema": { "type": "string", "description": "With `stream: true`, `data:` lines of `{\"type\": \"transcript.text.delta\", \"delta\": \"...\"}`, then `{\"type\": \"transcript.text.done\", \"text\": \"...\", \"usage\": {\"type\": \"duration\", \"seconds\": 10}}`." } } } }, "400": { "description": "The request body is neither JSON nor multipart, or the model could not decode the audio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "The audio is larger than 25 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. Wait at least this long before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model could not be reached or returned an unusable response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "504": { "description": "The model timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/audio/voices": { "get": { "summary": "List Audio Voices", "tags": [ "Audio" ], "description": "A speech model's voices: its built-in speakers, and the `design` and `clone` voices that select voice design and cloning.", "operationId": "list-audio-voices", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "model", "in": "query", "required": true, "description": "The text-to-speech model, e.g. `qwen3-tts-12hz-1.7b`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/audio-voices-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/files": { "get": { "summary": "List Files", "tags": [ "Files" ], "description": "The account's uploaded files that have not expired, newest first.", "operationId": "list-files", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-files-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "post": { "summary": "Upload File", "tags": [ "Files" ], "description": "Uploads a document once, to use in any number of requests by its `id`. The file is converted to text ahead of\ntime: its `status` is `processing` until then, `processed` when it can be used, or `error` with the reason in\n`status_details`. Poll `GET /files/{id}` for the status. Reference a processed file as `{\"type\": \"file\", \"file\":\n{\"file_id\": \"file-...\"}}` in chat, `{\"type\": \"input_file\", \"file_id\": \"file-...\"}` in Responses, or a document\nblock with `{\"type\": \"file\", \"file_id\": \"file-...\"}` as its source in Messages: the stored text is used, with no\nconversion in the request. Documents only (the types listed under `chat-content-part`), up to 100 MB; at most\n1,000 files per account; a file expires 30 days after upload. The file's text counts as prompt tokens in the\nrequests that use it.\n", "operationId": "create-file", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/create-file-request-payload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/file-object" } } } }, "400": { "description": "Bad Request, including a file that is not a document and an account at its file limit. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "413": { "description": "The file is larger than 100 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/files/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "file-6f1d2c9a4b7e8f0a1c2d3e4f" } ], "get": { "summary": "Get File", "tags": [ "Files" ], "description": "A file and its conversion status.", "operationId": "get-file", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/file-object" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "No such file for this account, or it has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "delete": { "summary": "Delete File", "tags": [ "Files" ], "description": "Deletes a file and its converted text.", "operationId": "delete-file", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delete-file-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "No such file for this account, or it has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/vector_store": { "get": { "summary": "List Collections", "tags": [ "Vector Store" ], "description": "Retrieve a list of vector store collections.", "operationId": "list-vector-stores", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-vector-stores-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "post": { "summary": "Create Collection", "tags": [ "Vector Store" ], "description": "Creates a vector store collection for searchable embeddings.", "operationId": "create-vector-store", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-vector-store-request-payload" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/vector_store/{id}": { "get": { "summary": "Get Collection", "tags": [ "Vector Store" ], "description": "Retrieve a vector store collection by the ID.", "operationId": "get-vector-store", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "patch": { "summary": "Update Collection", "tags": [ "Vector Store" ], "description": "Updates a vector store collection record.", "operationId": "update-vector-store", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-vector-store-request-payload" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "delete": { "summary": "Delete Collection", "tags": [ "Vector Store" ], "description": "Deletes a vector store collection record. This will also remove all items in the collection.", "operationId": "delete-vector-store", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "responses": { "204": { "description": "OK" }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/vector_store/{id}/search": { "post": { "summary": "Search Collection", "tags": [ "Vector Store" ], "description": "Searches items in a vector store collection for the closest embeddings matches.", "operationId": "search-vector-store", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search-vector-store-request-payload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search-vector-store-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "502": { "description": "The embeddings service failed to embed the input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "503": { "description": "The embeddings service is unavailable; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/vector_store/{id}/items": { "get": { "summary": "List Collection Items", "tags": [ "Vector Store" ], "description": "Retrieve a list of items within a vector store collections.", "operationId": "list-vector-store-items", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-vector-store-items-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "post": { "summary": "Add Collection Item", "tags": [ "Vector Store" ], "description": "Adds an item to a vector store collection.", "operationId": "add-vector-store-item", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add-vector-store-item-request-payload" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/add-vector-store-item-response-payload" }, { "$ref": "#/components/schemas/add-vector-store-item-chunked-response-payload" } ] } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "502": { "description": "The embeddings service could not process the item or its chunks. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/vector_store/{id}/items/{itemid}": { "get": { "summary": "Get Collection Item", "tags": [ "Vector Store" ], "description": "Retrieve a vector store collection item by the ID.", "operationId": "get-vector-store-item", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" }, { "$ref": "#/components/parameters/vector-store-item-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-item-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "No such item in the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "patch": { "summary": "Update Collection Item", "tags": [ "Vector Store" ], "description": "Updates a vector store collection item record.", "operationId": "update-vector-store-item", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" }, { "$ref": "#/components/parameters/vector-store-item-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-vector-store-item-request-payload" } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-item-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "delete": { "summary": "Delete Collection Item", "tags": [ "Vector Store" ], "description": "Deletes a vector store collection item record.", "operationId": "delete-vector-store-item", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" }, { "$ref": "#/components/parameters/vector-store-item-id" } ], "responses": { "204": { "description": "OK" }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/vector_store/{id}/files": { "get": { "summary": "List Collection Files", "tags": [ "Vector Store" ], "description": "Retrieve a list of files within a vector store collections.", "operationId": "list-vector-store-files", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-vector-store-files-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "post": { "summary": "Add Collection File", "tags": [ "Vector Store" ], "description": "Adds a file to a vector store collection.", "operationId": "add-vector-store-file", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file object to be uploaded to the vector store collection." } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add-vector-store-file-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "413": { "description": "The upload is over 100 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/vector_store/{id}/files/{fileid}": { "get": { "summary": "Get Collection File", "tags": [ "Vector Store" ], "description": "Retrieve a vector store collection file by the ID.", "operationId": "get-vector-store-file", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" }, { "$ref": "#/components/parameters/vector-store-file-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-vector-store-file-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } }, "delete": { "summary": "Delete Collection File", "tags": [ "Vector Store" ], "description": "Deletes a vector store collection file record.", "operationId": "delete-vector-store-file", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/vector-store-id" }, { "$ref": "#/components/parameters/vector-store-file-id" } ], "responses": { "204": { "description": "OK" }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field) and a collection, item or file that does not exist. The body is the error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/images/models": { "get": { "summary": "List Image Models", "tags": [ "Images" ], "description": "The image models currently served, in OpenRouter's image model list shape, for `images.listModels()` in OpenRouter's SDKs. Each entry names the parameters the model accepts (`supported_parameters`: `enum`, `range` and `boolean` descriptors) and links its endpoint record in `endpoints`. Everything comes from the model's capability spec, so the limits listed are the limits enforced.\n\n`size` is a constraint, not a list: a `WxH` string whose sides are multiples of `multiple_of`, whose area is between `min_area` and `max_area` pixels, and whose longer side is at most `max_ratio` times the shorter; where `max_total_area` is there, the `n` images of one request together may cover at most that many pixels (a model that renders them in one pass runs out of memory on more). A range parameter that also takes values outside its range lists them as `also` (qwen-image-2.1's `steps`: 20 to 50, or 6). `aspect_ratio` and `resolution` are enums, and `resolution.sizes` is the table of the size each aspect ratio and resolution gives. Prices are on `GET /v1/models` (per megapixel).", "operationId": "list-image-models", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/image-models-response" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "502": { "$ref": "#/components/responses/catalog-unavailable" } } } }, "/images/models/{author}/{slug}/endpoints": { "get": { "summary": "List Image Model Endpoints", "tags": [ "Images" ], "description": "The endpoint record of one image model, the `endpoints` link of its list entry. `author` is not checked; the gateway's model ids have none, and `vultr` is the documented one. `allowed_passthrough_parameters` are the names the model takes under `provider.options` (`vultr` or any other slug, flat or under `parameters`; OpenRouter's SDKs keep only `stealth`): every declared parameter and alias, `steps` included. They are also accepted at the top level of the request.", "operationId": "list-image-model-endpoints", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string", "example": "vultr" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "example": "z-image-turbo" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/image-model-endpoints-response" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "The model does not exist or is not currently served", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "$ref": "#/components/responses/catalog-unavailable" }, "503": { "description": "The model is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/images": { "post": { "summary": "Generate Image (OpenRouter)", "tags": [ "Images" ], "description": "OpenRouter's image endpoint, for `images.generate()` in OpenRouter's SDKs (set the base URL to this gateway's `/v1`). It is the same implementation as `/v1/images/generations` and `/v1/images/edits`; what differs is the default answer: **base64** (`response_format` `b64_json`), because OpenRouter's SDKs require `b64_json` in every item. Send `input_references` to edit with a model that has reference editing.\n\nModel-specific settings (`steps`, `guidance_scale`, `negative_prompt`) go at the top level, or under `provider.options` for an SDK that cannot add fields: OpenRouter's SDKs keep only the slugs on their closed list, so use `provider.options.stealth` there. A key the model does not declare is a 400 naming it.\n\nBilling is output megapixels only (`usage.megapixels`, at the model's price per megapixel in `usage.cost`); reference images are not billed, and a failed request is not billed.\n", "operationId": "create-image-openrouter", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-image-request-payload" }, "example": { "model": "z-image-turbo", "prompt": "Studio photograph of a red ceramic teapot beside a blue cup on a wooden table.", "aspect_ratio": "16:9", "resolution": "1K", "provider": { "options": { "stealth": { "steps": 8 } } } } } } }, "responses": { "200": { "description": "OK. With `stream: true`, `text/event-stream` carrying one `image_generation.completed` event and `[DONE]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-image-response-payload" } } } }, "400": { "description": "A field the model does not accept or a malformed input. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "The model does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "A reference image over 20 MB, or the images over 64 MB together", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "$ref": "#/components/responses/rate-limited" }, "503": { "description": "The model is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "description": "The model answered without an image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/images/generations": { "post": { "summary": "Create Image", "tags": [ "Images" ], "description": "Creates one or more images from a prompt, in OpenAI's shape (`images.generate()` in OpenAI's SDKs). The default model is `z-image-turbo`. `GET /v1/images/models` lists the image models currently served with what each accepts.\n\nThe answer is a link (`url`) unless `response_format` is `b64_json`; `POST /v1/images` answers base64 by default. Every error is OpenRouter's envelope.\n\n`quality` (`auto`, `low`, `medium`, `high`, `standard`, `hd`) is accepted and ignored: no model has a quality setting, and `steps` trades time for detail. `moderation` and `style` are not supported and are a 400 naming the field. `stream: true` answers one `image_generation.completed` event and `[DONE]` (`partial_images` above 0 is a 400). `output_format` (`png`, `jpeg`, `webp`) and `output_compression` are passed to the engine. Model-specific settings are `steps` (or `num_inference_steps`), `guidance_scale` and `negative_prompt`, also under `provider.options` (see `POST /v1/images`).\n\nFor reproducible output, send an integer `seed` together with `steps` and `guidance_scale`, and keep every other field the same between requests.\n", "operationId": "create-image", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-image-request-payload" }, "example": { "model": "z-image-turbo", "prompt": "Studio photograph of a red ceramic teapot beside a blue cup on a wooden table.", "n": 1, "size": "1024x1024", "response_format": "b64_json" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-image-response-payload" } } } }, "400": { "description": "A field the model does not accept or a malformed input. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "The model does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "$ref": "#/components/responses/rate-limited" }, "503": { "description": "The model is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/images/edits": { "post": { "summary": "Edit Image", "tags": [ "Images" ], "description": "Edits or recombines images with a prompt, in OpenAI's shape (`images.edit()` in OpenAI's SDKs): multipart `image[]` files and an optional `mask`, or JSON `images: [{image_url}]` and `mask: {image_url}`; OpenRouter's `input_references` works too. The same implementation as `/v1/images/generations`, and the same fields and answer.\n\nOnly a model with reference editing takes this route. `z-image-turbo` has none: the request is a 400 naming `image` (or `images`, `input_references`, `mask`, whichever was sent). Each image is an upload, a base64 data URI or an https URL the gateway fetches itself (public addresses only); the engine only receives bytes. An image's type is read from its bytes and checked against the model's accepted formats.\n\nBilling is the output megapixels only, so an edit with any number of references bills the same as a generation of the same size. `size` `auto` is the model's default size, not the first image's.\n", "operationId": "create-image-edit", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/create-image-edit-multipart-request-payload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/create-image-edit-request-payload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-image-response-payload" } } } }, "400": { "description": "A field the model does not accept, no image, or a malformed input. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "The model does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "An image over 20 MB, or the images over 64 MB together", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "429": { "$ref": "#/components/responses/rate-limited" }, "503": { "description": "The model is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/videos": { "post": { "summary": "Create Video", "tags": [ "Videos" ], "description": "Starts a video render and answers `202` at once with the job; poll its `polling_url`, or pass `callback_url` to be notified. The request follows OpenRouter's video API, so the OpenRouter SDKs work by changing the base URL and key. OpenAI/Sora field names are accepted too: `seconds` for `duration`, `size`, and `input_reference` (an uploaded file in `multipart/form-data`, an https URL string, or `{image_url}`) for the first frame. `GET /v1/videos/models` lists the models with what each accepts.\n\n**Modes (minimax-h3):** text only; `frame_images` with a `first_frame`, a `last_frame` or both; or `input_references` (up to 9 images, 3 videos and 3 audio clips, 12 in all). When both `frame_images` and `input_references` are sent, `frame_images` is used.\n\n**Media:** an https URL or a base64 data URI. Images JPG, PNG, WEBP, HEIC or HEIF up to 30 MB; videos MP4 or MOV up to 50 MB, 2-15 s; audio WAV or MP3 up to 15 MB, 2-15 s.\n\n**Sizes (minimax-h3):** 4 to 15 seconds at 24 fps, with stereo AAC audio. Send `aspect_ratio` or `size`:\n\n| `aspect_ratio` | `size` |\n|---|---|\n| `16:9` (default) | `1344x768` |\n| `9:16` | `768x1344` |\n| `4:3` | `1024x768` |\n| `3:4` | `768x1024` |\n| `1:1` | `768x768` |\n| `21:9` | `1536x672` |\n\n**Output:** duration snaps to the model's frame grid, so a 4 s request is about 4.4 s; read `output.duration`. Videos have a generated soundtrack unless `generate_audio` is `false`.\n\n**Prompts** are used as written. MiniMax's and fal's APIs rewrite prompts by default, so the same prompt can give a different video here.\n\n**Expected wait:** while a job is `pending`, `queue_position` counts the jobs ahead of it for the same model. Once it starts, a minimax-h3 render takes about 3 seconds per second of video for text and frame jobs, and about 5 seconds per second with `input_references`: a 6 s text job is ready in about 20 s. `progress` is estimated from these times.\n\n**Quality (minimax-h3):** `quality` picks a tier, the same in every mode. `turbo` (or `auto`, `low`; the default) uses H3's Turbo LoRA: 4 denoising steps, or 8 with `input_references`. `standard` (or `medium`) runs the full base model at 20 steps and bills 3 times the seconds; `max` (or `high`) runs 40 steps and bills 5 times. For finer control send `num_inference_steps` from 10 to 50 instead (OpenRouter's SDKs: `provider.options.stealth.quality` or `.num_inference_steps`); more steps take longer and cost more. Sending a tier and a different step count is a 400.\n\n**Billing:** per second of requested `duration` at the model's price (`pricing_skus` in `GET /v1/videos/models`; `standard_per_second` and `max_per_second` are the tiers' prices), only when the job completes. `standard` bills 3 times the seconds and `max` 5 times. A raw `num_inference_steps` bills steps / 6 times the seconds, never more than the next tier up (19 steps bill as `standard`), rounded up to a whole second: a 10 s job at 25 steps bills 42 s. `usage.billed_seconds` shows the result. Failed and cancelled jobs are not billed.\n", "operationId": "create-video", "security": [ { "APIKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-video-request-payload" }, "example": { "model": "minimax-h3", "prompt": "A red fox trots through fresh snow at dawn, breath steaming.", "duration": 6, "aspect_ratio": "16:9", "callback_url": "https://example.com/hooks/video" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/create-video-multipart-request-payload" } } } }, "responses": { "202": { "description": "Accepted. The job, `pending`, with its `polling_url` and `queue_position`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-job-payload" } } } }, "400": { "description": "A field the model does not support or a malformed input. The message names the field. Fields are typed, not coerced; `prompt` must be a string, `generate_audio` a boolean (`true` or `false`), `input_reference` a URL string or an object - and a whole number may be sent as text (`\"20\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Unknown video model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "503": { "description": "The model has no valid capability spec at the moment and is not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "413": { "description": "A media input is over its size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "get": { "summary": "List Videos", "tags": [ "Videos" ], "description": "Your video jobs, newest first.", "operationId": "list-videos", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "A job id from the previous page (`last_id`); returns the jobs created before it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-list-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/videos/models": { "get": { "summary": "List Video Models", "tags": [ "Videos" ], "description": "The video models currently served, in OpenRouter's `VideoModel` shape (a `data` list, no pagination; OpenRouter's SDKs parse it) with the durations, sizes, inputs and passthrough parameters each accepts, plus our own fields (`inputs`, `operations`, `supported_fps`, `frame_grid`). Requests are checked against these entries before they are queued. A model without a valid capability spec is not listed.", "operationId": "list-video-models", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-models-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/videos/{id}": { "get": { "summary": "Get Video", "tags": [ "Videos" ], "description": "The job's status, estimated `progress` while it renders, and once `completed` its `unsigned_urls`, `output` and `usage`.", "operationId": "get-video", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/video-id" } ], "responses": { "200": { "description": "OK", "headers": { "openai-poll-after-ms": { "description": "Milliseconds to wait before polling again, from 2000 to 10000, sent while the job is `pending` or `in_progress` and read by OpenAI's SDKs (`videos.poll()`, `create_and_poll()`). Absent once the job has finished.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-job-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "delete": { "summary": "Cancel or Delete Video", "tags": [ "Videos" ], "description": "A `pending` or `in_progress` job is cancelled and not billed; it answers with the job, now `cancelled`. A finished job is deleted with its video and answers `{id, object, deleted}`.\n\nCancelling stops billing at once. A render that has already started stops within about 10 seconds.\n", "operationId": "delete-video", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/video-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/video-job-payload" }, { "$ref": "#/components/schemas/video-deleted-payload" } ] } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "409": { "description": "The job changed state while being cancelled; try again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/videos/{id}/content": { "get": { "summary": "Download Video", "tags": [ "Videos" ], "description": "The MP4. Available once the job is `completed` and until `expires_at` (7 days).", "operationId": "get-video-content", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/video-id" }, { "name": "index", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found, expired, or no output at that index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "409": { "description": "The job has not completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/music": { "post": { "summary": "Create Music", "tags": [ "Music" ], "description": "Starts a song and answers `202` at once with the job; poll its `polling_url`, or pass `callback_url` to be notified (the same signed webhooks as videos, with `music.generation.*` events). A full song takes minutes. To wait for a short one, send `Prefer: wait=` (at most 60): if the job finishes in that time the answer is `200` with the finished job, otherwise `202` as usual. `GET /v1/music/models` lists the models with what each accepts.\n\n**One request for every model.** The fields below are shared by all music models; each model's entry in `GET /v1/music/models` says which it honours. A field the model cannot honour, sent with a value that asks for something, is a `400` naming the field (`metadata.error_type` `unsupported_parameter`), so a request is never billed for something it did not get. A value that asks for nothing (`false`, `[]`, `\"\"`) is accepted. A field this API does not know is ignored and reported in the job's `warnings`.\n\nOther APIs' names are accepted for the shared fields: `tags` (prompt) and `seconds_total` (fal), `music_length_ms`, `force_instrumental`, `model_id` and codec strings such as `mp3_44100_128` in `output_format` (ElevenLabs), `is_instrumental` and `audio_setting` (MiniMax). `aigc_watermark`, `enable_safety_checker` and `sync_mode` are accepted and ignored.\n\n**minimax-music3** (MiniMax-Music3): lyrics are required, and `prompt` is the style caption. The model was trained on captions under three headings, each field on its own line:\n\n```\nGlobal Metadata\nBasic Attributes: bpm is 92. key is E, and scale is minor. Electric Blues / Blues Rock.\n...\nVocal Details\n...\nArrangement\n...\n```\n\nFree prose works too. Lyric section tags on their own lines steer the structure: `[Intro]`, `[Verse]`, `[Pre-Chorus]`, `[Chorus]`, `[Post-Chorus]`, `[Bridge]`, `[Instrumental]`, `[Solo]`, `[Outro]` (other spellings such as `[pre chorus]` or `[Inst]` are rewritten to these). The prompt and lyrics together may come to about 5,000 tokens. `duration` is the longest the song may be, 30 to 360 seconds (default 300); the song may end sooner, and you pay for the seconds it has. `bpm`, `key` and `time_signature` are hints: they are written into the caption's `Basic Attributes` line and reported as `advisory_control` warnings, and the model may not follow them exactly. One song per request; a `seed` gives the same song for the same request. Output is rendered at 32 kHz stereo and delivered as `response_format` (`mp3` by default, 256 kbps).\n\n**Expected wait:** while a job is `pending`, `queue_position` counts the jobs ahead of it for the same model. Once it starts, minimax-music3 renders about 0.7 seconds per second of song: a 3 minute song is ready in about 2 minutes. `progress` is estimated from these times.\n\n**Billing:** per second of audio produced at the model's price (`pricing_skus` in `GET /v1/music/models`), each output rounded up to a whole second and never more than `duration`, only when the job completes. Failed and cancelled jobs are not billed.\n", "operationId": "create-music", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "Prefer", "in": "header", "description": "`wait=`, at most 60: answer with the finished job if it completes in that time.", "schema": { "type": "string", "example": "wait=60" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-music-request-payload" }, "example": { "model": "minimax-music3", "prompt": "Global Metadata\nBasic Attributes: bpm is 118. key is F, and scale is minor. Disco Pop / Nu-Disco.\nVocal Details\nBright female lead, close-miked, light doubles on the chorus.\nArrangement\nFour-on-the-floor kick, slap bass, string stabs, filtered synth swells into the chorus.", "lyrics": "[Verse]\nCity lights are humming low\nEvery window starts to glow\n[Chorus]\nWe keep on running through the night", "duration": 180, "response_format": "mp3", "callback_url": "https://example.com/hooks/music" } } } }, "responses": { "202": { "description": "Accepted. The job, `pending`, with its `polling_url`, `queue_position` and any `warnings`.", "headers": { "openai-poll-after-ms": { "description": "Milliseconds to wait before polling, from 2000 to 10000.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/music-job-payload" } } } }, "200": { "description": "With `Prefer: wait`, the job finished in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/music-job-payload" } } } }, "400": { "description": "A field the model cannot honour, a value out of range or a malformed field. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Unknown music model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "503": { "description": "The model has no valid capability spec at the moment and is not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "get": { "summary": "List Music", "tags": [ "Music" ], "description": "Your music jobs, newest first.", "operationId": "list-music", "security": [ { "APIKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "A job id from the previous page (`last_id`); returns the jobs created before it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/music-list-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "400": { "description": "`limit` or `after` is malformed; the message names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/music/models": { "get": { "summary": "List Music Models", "tags": [ "Music" ], "description": "The music models currently served, each with what it honours, so a client can adapt without code changes. `false` or `[]` means unsupported. Requests are checked against these entries before they are queued. A model without a valid capability spec is not listed.", "operationId": "list-music-models", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/music-models-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/music/{id}": { "get": { "summary": "Get Music", "tags": [ "Music" ], "description": "The job's status, estimated `progress` while it renders, and once `completed` its `outputs`, `unsigned_urls` (index-aligned with `outputs`) and `usage`.", "operationId": "get-music", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/music-id" } ], "responses": { "200": { "description": "OK", "headers": { "openai-poll-after-ms": { "description": "Milliseconds to wait before polling again, from 2000 to 10000, sent while the job is `pending` or `in_progress`. Absent once the job has finished.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/music-job-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } }, "delete": { "summary": "Cancel or Delete Music", "tags": [ "Music" ], "description": "A `pending` or `in_progress` job is cancelled and not billed; it answers with the job, now `cancelled`, and a render that has started stops within about 10 seconds. A finished job is deleted with its audio and answers `{id, object, deleted}`.", "operationId": "delete-music", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/music-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/music-job-payload" }, { "$ref": "#/components/schemas/music-deleted-payload" } ] } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "409": { "description": "The job changed state while being cancelled; try again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/music/{id}/content": { "get": { "summary": "Download Music", "tags": [ "Music" ], "description": "One output of the job, `outputs[index]`, in its `content_type` (`pcm` is raw 16-bit little-endian samples with no header). Available once the job is `completed` and until `expires_at` (7 days).", "operationId": "get-music-content", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/music-id" }, { "name": "index", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found, expired, or no output at that index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "409": { "description": "The job has not completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/music/{id}/stream": { "get": { "summary": "Stream Music", "tags": [ "Music" ], "description": "The song as it renders: the job's `stream_url`, there while it is `pending` or `in_progress` on a model whose `/v1/music/models` entry has `streaming.progressive: true`. The answer is WAV (for minimax-music3 32 kHz, 16-bit, stereo, whatever `response_format` asked for) from its first byte, then follows the render live; the first audio arrives seconds in. Its header's sizes promise the `duration` asked for, the most the model can produce, since the real length is not known until the end; the stored output has its exact length.\n\nA listener who connects late, even just after the job completed, hears it from the start: the stream is kept for 10 minutes after it ends. The response ends when the song does and cannot say why, so read the job when it ends: `completed`, or `failed`/`cancelled` (the audio heard is then not a whole song). If the job is retried after a server failure the stream starts over and a listener partway through is let go; connect again. Send your API key.\n", "operationId": "get-music-stream", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/music-id" }, { "name": "index", "in": "query", "description": "The output, as `outputs[]` will number it.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "The song, as it renders", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "Not found, expired, or no output at that index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "409": { "description": "The model does not stream, or the job finished and its stream is no longer kept (read `content`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/webhooks/secret": { "get": { "summary": "Get Webhook Secret", "tags": [ "Webhooks" ], "description": "The secret your webhooks are signed with, created on first request. It is separate from your API key, so a webhook receiver never holds a key that can spend.\n\nEach delivery is a `POST` of `{type, created_at, data}` with `data` the job as `GET /v1/videos/{id}` or `GET /v1/music/{id}` returns it. Events: `video.generation.completed`, `video.generation.failed`, `video.generation.cancelled`, `video.generation.expired`, and the same four as `music.generation.*` for music jobs. Headers:\n\n- `X-Vultr-Signature: t=,v1=`, the HMAC-SHA256 of `.` with this secret. Reject old timestamps. During a rotation a second `v1=` is signed with the previous secret.\n- `X-Vultr-Idempotency-Key: -`; retried deliveries repeat it.\n\nA `2xx` within 10 seconds is delivered; anything else is retried after 30 s, 2 min, 10 min, 1 h and 6 h. Deliveries can arrive more than once or out of order: use the idempotency key, and the job's `status`, rather than arrival order.\n\n**Verifying a delivery.** Compute the HMAC over the raw request body, before any JSON parsing, with the whole secret including its `whsec_` prefix. Accept the delivery when any `v1=` value matches.\n\n```python\nimport hashlib, hmac, time\n\ndef verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:\n pairs = [part.split(\"=\", 1) for part in header.split(\",\")]\n t = next((v for k, v in pairs if k == \"t\"), None)\n if t is None or abs(time.time() - int(t)) > tolerance:\n return False\n expected = hmac.new(secret.encode(), t.encode() + b\".\" + raw_body, hashlib.sha256).hexdigest()\n return any(k == \"v1\" and hmac.compare_digest(expected, v) for k, v in pairs)\n```\n\n```javascript\nconst crypto = require(\"crypto\");\n\nfunction verify(rawBody, header, secret, tolerance = 300) {\n const pairs = header.split(\",\").map((part) => part.split(\"=\"));\n const t = pairs.find(([k]) => k === \"t\")?.[1];\n if (!t || Math.abs(Date.now() / 1000 - Number(t)) > tolerance) return false;\n const expected = crypto.createHmac(\"sha256\", secret).update(`${t}.`).update(rawBody).digest();\n return pairs.some(([k, v]) => k === \"v1\" && v.length === 64 &&\n crypto.timingSafeEqual(expected, Buffer.from(v, \"hex\")));\n}\n```\n", "operationId": "get-webhook-secret", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook-secret-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/webhooks/secret/rotate": { "post": { "summary": "Rotate Webhook Secret", "tags": [ "Webhooks" ], "description": "Replaces the secret. The previous one keeps signing beside it for 24 hours (`previous_secret_valid_until`).", "operationId": "rotate-webhook-secret", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook-secret-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/models": { "get": { "summary": "List Models", "tags": [ "Models" ], "description": "Retrieve the public inference model catalog. By default this returns OpenRouter ModelDocumentV2 entries (the provider document); OpenRouter's own SDKs, recognised by their User-Agent, and requests with `format=openrouter` get OpenRouter's public model list (`data`, `total_count`, `links`) instead, which they can parse. Send the Anthropic-Version header for an Anthropic-compatible model list with cursor pagination. Anthropic mode includes `vultr/claude-code/` aliases because Claude Code only discovers IDs containing `claude` or `anthropic`; the original IDs remain available. X-Vultr-Model-Type applies only to the default catalog. TypeSafe's SDKs, which send X-TypeSafe-SDK, get TypeSafe's model list instead: the decision models for POST /v1/systemone as `{\"models\": [{name, description, release_date}]}`.", "operationId": "list-models", "security": [], "parameters": [ { "name": "anthropic-version", "in": "header", "required": false, "description": "When present, return Anthropic model entries and pagination fields instead of the default catalog.", "schema": { "type": "string", "example": "2023-06-01" } }, { "name": "X-Vultr-Model-Type", "in": "header", "required": false, "description": "Filter the default catalog to chat-completion models. Ignored in Anthropic mode.", "schema": { "type": "string", "enum": [ "chat" ] } }, { "name": "X-TypeSafe-SDK", "in": "header", "required": false, "description": "Sent by TypeSafe's SDKs (for example `typesafe-sdk/0.7.2`). When present, return TypeSafe's model list of decision models instead of the catalog.", "schema": { "type": "string", "example": "typesafe-sdk/0.7.2" } }, { "name": "format", "in": "query", "required": false, "description": "Set to `openrouter` to get OpenRouter's public model list from a client that does not send an OpenRouter SDK User-Agent, such as a browser (browsers cannot set it). Takes priority over the X-TypeSafe-SDK and Anthropic-Version headers. Other values are ignored.", "schema": { "type": "string", "enum": [ "openrouter" ] } }, { "name": "output_modalities", "in": "query", "required": false, "description": "Comma-separated output modalities to list: `text`, `image`, `embeddings`, `audio`, `video`, `rerank`, `decisions`, `speech`, `transcription`, or `all`. `audio` is the music models, which generate through `/v1/music`. A model matches if any of its outputs is listed. Unset, the default catalog lists every model and OpenRouter's public list lists `text`, as OpenRouter's API does. Not applied in Anthropic or TypeSafe mode.", "schema": { "type": "string", "example": "speech,transcription" } }, { "name": "input_modalities", "in": "query", "required": false, "description": "Comma-separated input modalities: `text`, `image`, `file`, `audio`, `video`. A model matches if it accepts any of them.", "schema": { "type": "string", "example": "image" } }, { "name": "supported_parameters", "in": "query", "required": false, "description": "Comma-separated parameter names, as in the public model list's `supported_parameters`. A model must support all of them.", "schema": { "type": "string", "example": "tools,top_k" } }, { "name": "offset", "in": "query", "required": false, "description": "OpenRouter public list only. Models to skip. Offset and limit both omitted is the whole list.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "after_id", "in": "query", "required": false, "description": "Anthropic mode only. Return the page after this model ID.", "schema": { "type": "string" } }, { "name": "before_id", "in": "query", "required": false, "description": "Anthropic mode only. Return the page before this model ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Anthropic mode: models per page, default 20. OpenRouter public list: models per page, default 500 once offset or limit is set.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/models-response-payload" }, { "$ref": "#/components/schemas/openrouter-public-models-response" }, { "$ref": "#/components/schemas/anthropic-models-response-payload" }, { "$ref": "#/components/schemas/typesafe-models-response-payload" } ] } } } }, "400": { "description": "Unsupported model type filter, unknown output or input modality, invalid offset or limit, or invalid Anthropic pagination cursor. With `anthropic-version` the body is Anthropic's.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/error-payload" }, { "$ref": "#/components/schemas/anthropic-error-payload" } ] } } } }, "502": { "description": "The model catalog is unavailable (OpenRouter public list only; the default catalog answers an empty list)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } } } }, "/models/count": { "get": { "summary": "Count Models", "tags": [ "Models" ], "description": "The number of models the list holds under the same filters, as `{\"data\": {\"count\": n}}`, for OpenRouter's `models.count()`. Public like the list. The default follows the list: `text` for OpenRouter's SDKs and `format=openrouter`, every model otherwise.", "operationId": "count-models", "security": [], "parameters": [ { "name": "output_modalities", "in": "query", "required": false, "description": "Comma-separated output modalities, or `all`; as on `GET /v1/models`.", "schema": { "type": "string", "example": "speech,transcription" } }, { "name": "input_modalities", "in": "query", "required": false, "description": "Comma-separated input modalities, as on `GET /v1/models`.", "schema": { "type": "string" } }, { "name": "supported_parameters", "in": "query", "required": false, "description": "Comma-separated parameter names, as on `GET /v1/models`.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Set to `openrouter` for the SDK default (`text`) without an SDK User-Agent.", "schema": { "type": "string", "enum": [ "openrouter" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/models-count-response" } } } }, "400": { "description": "Unknown output or input modality", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "$ref": "#/components/responses/catalog-unavailable" } } } }, "/models/{id}": { "get": { "summary": "Get Model", "tags": [ "Models" ], "description": "Retrieves one model: the same entry `GET /v1/models` lists for it, returned on its own as OpenAI's retrieve does. With an `anthropic-version` header the answer is Anthropic's model object, for the chat models Anthropic's list shows (including the `vultr/claude-code/` aliases). A model ID with a slash can be sent as path segments (`/v1/models/zai-org/GLM-5`) or percent-encoded (`/v1/models/zai-org%2FGLM-5`). IDs are case-sensitive. An unknown ID, or a model that is not currently served, is a 404 in the error envelope.", "operationId": "get-model", "security": [ { "APIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/model-id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/openrouter-model-document" }, { "$ref": "#/components/schemas/anthropic-model-info" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "description": "No served model has that id. With `anthropic-version` the body is Anthropic's.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/error-payload" }, { "$ref": "#/components/schemas/anthropic-error-payload" } ] } } } }, "502": { "$ref": "#/components/responses/catalog-unavailable" }, "503": { "$ref": "#/components/responses/models-unavailable" } } } }, "/model/{author}/{slug}": { "get": { "summary": "Get Model By Author And Slug", "tags": [ "Models" ], "description": "Retrieves one model in OpenRouter's public model shape, for OpenRouter's `models.get({author, slug})`. Model IDs have no author, so the `slug` is matched against the model ID and any `author` is accepted (`vultr` is the documented one). The whole `author/slug` also matches a model ID that holds a slash, a model's Hugging Face ID (case-insensitively) and a legacy model ID that redirects to the model that replaced it. A `:variant` suffix on the slug is accepted and ignored. A slug that holds a slash can be percent-encoded. Public like `GET /v1/models`, which lists the same entry. An unknown model, one that is not currently served and a private model are a 404 in the error envelope.", "operationId": "get-model-by-author-and-slug", "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The model's organization. Any value is accepted; use `vultr`.", "schema": { "type": "string", "example": "vultr" } }, { "name": "slug", "in": "path", "required": true, "description": "The model ID, optionally with a `:variant` suffix.", "schema": { "type": "string", "example": "glm-5.3" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/openrouter-public-model-response" } } } }, "400": { "description": "Empty variant after the colon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "502": { "$ref": "#/components/responses/catalog-unavailable" } } } }, "/models/all": { "get": { "summary": "List All Models", "tags": [ "Models" ], "deprecated": true, "description": "The chat, speech and image models the API serves, in three lists. Deprecated: `GET /v1/models` lists every model the API serves with everything it accepts and costs, and needs no key; its `output_modalities` parameter (`text`, `speech` or `image`) narrows it to one list.", "operationId": "list-all-models", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/all-models-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "503": { "$ref": "#/components/responses/models-unavailable" } } } }, "/usage": { "get": { "summary": "Get Usage", "tags": [ "Usage" ], "description": "View usage information for the current and previous months.", "operationId": "get-usage", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usage-response-payload" } } } }, "400": { "description": "Bad Request, including a request that failed validation (the message names the rejected field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" } } } }, "/health": { "get": { "summary": "Get Cluster Status", "tags": [ "Health Check" ], "description": "View the current status of the inference cluster.", "operationId": "get-cluster-status", "security": [ { "APIKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cluster-status-response-payload" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cluster-status-response-error-payload" } } } } } } } }, "components": { "schemas": { "anthropic-message-request-payload": { "title": "Anthropic Message Request Payload", "type": "object", "x-tags": [ "messages", "anthropic", "request" ], "description": "Request payload for the Anthropic Messages API format. The request is adapted internally to the underlying chat completions engine.", "x-examples": {}, "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "The model identifier to use for generation." }, "max_tokens": { "type": "integer", "minimum": 0, "description": "Total completion token allowance, including thinking and visible output. The gateway forwards zero if supplied; whether zero is accepted depends on the upstream engine." }, "messages": { "type": "array", "minItems": 1, "description": "Input messages. Models operate on alternating `user` and `assistant` conversational turns. Consecutive `user` or `assistant` turns are combined into a single turn.\n\nIf the final message uses the `assistant` role, the response content continues immediately from that message's content (assistant prefill).\n\nA text-only `system` message may follow a `user` turn, as the final message or before an `assistant` turn. Use the top-level `system` parameter for initial instructions. Turn-scoped `clear_at` and per-message `output_config` are not supported.\n", "items": { "$ref": "#/components/schemas/anthropic-message-param" } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/anthropic-text-block-param" } } ], "description": "System prompt providing context or instructions to the model. May be a string or an array of text blocks." }, "stream": { "type": "boolean", "description": "Whether to stream the response using server-sent events. Streaming events use typed event names: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop." }, "temperature": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Controls randomness in the model responses. Valid range: 0 to 1." }, "top_p": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Enables nucleus sampling with a cumulative probability cutoff." }, "top_k": { "type": "integer", "description": "Limits sampling to the top K options." }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Custom sequences that, when encountered in the generated text, cause the model to stop." }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "An opaque identifier for the end-user making the request." } }, "description": "Additional metadata about the request." }, "output_config": { "type": "object", "description": "Output controls. Effort is translated through the selected model's reasoning configuration. Unsupported configured levels return 400.", "properties": { "effort": { "type": "string", "enum": [ "minimal", "low", "medium", "high", "xhigh", "max", "ultra" ] } } }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "adaptive", "disabled" ], "description": "`enabled` requests thinking with an exact budget on models that support enforced thinking budgets; `adaptive` leaves the thinking allocation to the model; `disabled` turns thinking off." }, "budget_tokens": { "type": "integer", "minimum": 1024, "description": "Required for `enabled`; must be less than `max_tokens` and the effective output limit after context clipping. Models that cannot enforce the budget reject the request." }, "display": { "type": "string", "enum": [ "summarized", "omitted" ], "description": "`omitted` hides thinking text while preserving an API-generated signature for continuation. It is invalid when thinking is disabled." } }, "description": "Thinking configuration. The adapter signs its own thinking blocks for continuation; it does not emit redacted thinking blocks." }, "tools": { "type": "array", "description": "Definitions for tools available to the model.", "items": { "$ref": "#/components/schemas/anthropic-tool-definition" } }, "tool_choice": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool" ], "description": "How the model should use tools. `auto` lets the model decide. `any` forces at least one tool call. `tool` forces a specific tool." }, "name": { "type": "string", "description": "The name of the specific tool to use. Required when type is `tool`." } }, "description": "Instructs how the model should use any provided tools." } } }, "anthropic-message-param": { "title": "Anthropic Message Param", "type": "object", "x-tags": [ "messages", "anthropic", "message" ], "description": "An input message in the Anthropic Messages API format.", "x-examples": {}, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ], "description": "The role of the message author. A `system` message must follow `user`; initial system instructions belong in the top-level `system` field." }, "content": { "oneOf": [ { "type": "string", "description": "Shorthand for a single text block." }, { "type": "array", "items": { "$ref": "#/components/schemas/anthropic-content-block-param" }, "description": "An array of typed content blocks." } ], "description": "System messages support text blocks only." }, "clear_at": { "type": "string", "enum": [ "never" ], "description": "Turn-scoped system messages are not supported." } } }, "anthropic-content-block-param": { "title": "Anthropic Content Block Param", "type": "object", "x-tags": [ "messages", "anthropic", "content block" ], "description": "A typed content block within a message.", "x-examples": {}, "properties": { "type": { "type": "string", "enum": [ "text", "image", "document", "tool_use", "tool_result", "thinking" ], "description": "The type of content block. A `document` is converted to text before the model sees it, as described under `chat-content-part`." }, "text": { "type": "string", "description": "The text content. Present when type is `text`." }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64", "url", "text", "content" ], "description": "The source type. `text` and `content` are for documents whose content is already text; `file` (with `file_id`) is a file uploaded with `POST /files`." }, "media_type": { "type": "string", "description": "The media type of the image or document, for example `image/png` or `application/pdf`. Present when source type is `base64` or `text`." }, "data": { "type": "string", "description": "The base64-encoded image or document, or the document's text for a `text` source." }, "url": { "type": "string", "description": "The URL of the image or document. Present when source type is `url`." }, "file_id": { "type": "string", "description": "A processed file uploaded with `POST /files`. Present when source type is `file`." } }, "description": "The image or document source. Present when type is `image` or `document`." }, "id": { "type": "string", "description": "The unique ID of the tool use. Present when type is `tool_use` or `tool_result`." }, "name": { "type": "string", "description": "The name of the tool that was called. Present when type is `tool_use`." }, "input": { "type": "object", "description": "The input parameters for the tool call, as a JSON object. Present when type is `tool_use`." }, "tool_use_id": { "type": "string", "description": "The ID of the tool use this result corresponds to. Present when type is `tool_result`." }, "content": { "description": "The result content of a tool call. May be a string or an array of text blocks. Present when type is `tool_result`.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/anthropic-text-block-param" } } ] }, "is_error": { "type": "boolean", "description": "Whether the tool call resulted in an error. Present when type is `tool_result`." }, "thinking": { "type": "string", "description": "The thinking text. Present when type is `thinking`." }, "signature": { "type": "string", "description": "The signature value of this thinking block, as returned by the API. Present when type is `thinking`." } } }, "anthropic-text-block-param": { "title": "Anthropic Text Block Param", "type": "object", "x-tags": [ "messages", "anthropic", "text block" ], "description": "A text content block.", "x-examples": {}, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The block type. Always `text`." }, "text": { "type": "string", "minLength": 1, "description": "The text content." }, "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ], "description": "The cache control type. Always `ephemeral`." }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The time-to-live for the cache breakpoint. Defaults to `5m`." } }, "description": "Accepted for Anthropic client compatibility but ignored by the adapter; it does not create a cache breakpoint." } } }, "anthropic-tool-definition": { "title": "Anthropic Tool Definition", "type": "object", "x-tags": [ "messages", "anthropic", "tools" ], "description": "A tool definition in the Anthropic Messages API format.", "x-examples": {}, "required": [ "name", "input_schema" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name of the tool." }, "description": { "type": "string", "description": "A detailed description of what the tool does." }, "input_schema": { "type": "object", "description": "A JSON Schema object describing the expected input format for the tool." }, "type": { "type": "string", "description": "Accepted but ignored by the adapter. Tools are forwarded as ordinary function tools using `name` and `input_schema`; Anthropic built-in tool behavior is not implemented." }, "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ], "description": "The cache control type." } }, "description": "Accepted for Anthropic client compatibility but ignored by the adapter; it does not create a cache breakpoint." } } }, "anthropic-message-response-payload": { "title": "Anthropic Message Response Payload", "type": "object", "x-tags": [ "messages", "anthropic", "response" ], "description": "The response from the Anthropic Messages API.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "A unique identifier for the response message." }, "type": { "type": "string", "enum": [ "message" ], "description": "The object type. Always `message`." }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the response. Always `assistant`." }, "model": { "type": "string", "description": "The model that generated the response." }, "content": { "type": "array", "description": "The generated content blocks from the model.", "items": { "$ref": "#/components/schemas/anthropic-content-block" } }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use" ], "description": "The reason the model stopped generating." }, "stop_sequence": { "type": [ "string", "null" ], "description": "The specific stop sequence that caused generation to stop, if applicable." }, "usage": { "$ref": "#/components/schemas/anthropic-usage" } } }, "anthropic-content-block": { "title": "Anthropic Content Block", "type": "object", "x-tags": [ "messages", "anthropic", "content block", "response" ], "description": "A generated content block in the response.", "x-examples": {}, "properties": { "type": { "type": "string", "enum": [ "text", "thinking", "tool_use" ], "description": "The type of content block." }, "text": { "type": "string", "description": "The generated text. Present when type is `text`." }, "thinking": { "type": "string", "description": "The thinking text. Present when type is `thinking`." }, "signature": { "type": "string", "description": "The signature for the thinking block. Present when type is `thinking`." }, "id": { "type": "string", "description": "The unique ID of the tool use. Present when type is `tool_use`." }, "name": { "type": "string", "description": "The name of the tool called. Present when type is `tool_use`." }, "input": { "type": "object", "description": "The input parameters for the tool call. Present when type is `tool_use`." } } }, "anthropic-usage": { "title": "Anthropic Usage", "type": "object", "x-tags": [ "messages", "anthropic", "usage" ], "description": "Token usage information for the request.", "x-examples": {}, "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens processed." }, "output_tokens": { "type": "integer", "description": "The number of output tokens generated." }, "cache_creation_input_tokens": { "type": [ "integer", "null" ], "description": "The number of tokens used to create a cache entry." }, "cache_read_input_tokens": { "type": [ "integer", "null" ], "description": "The number of tokens read from the cache." } } }, "anthropic-message-streaming-response-payload": { "title": "Anthropic Message Streaming Response Payload", "type": "string", "x-tags": [ "messages", "anthropic", "response", "streaming" ], "description": "A text/event-stream body containing Anthropic Messages events. Each event has an event name and a JSON data line.\n\nEvent flow:\n1. `message_start` - contains a Message object with empty content\n2. `content_block_start` - starts a new content block (text, thinking, or tool_use)\n3. `content_block_delta` - incremental deltas for the content block (text, thinking, input JSON, and a final thinking signature)\n4. `content_block_stop` - ends the current content block\n5. `message_delta` - changes to the top-level message (stop_reason, stop_sequence, usage)\n6. `message_stop` - the message is complete\nA `signature_delta` is sent as a `content_block_delta` before a thinking block closes.\n" }, "anthropic-error-payload": { "title": "Anthropic Error Payload", "type": "object", "description": "Anthropic's error body, which `/v1/messages` (and the model list with `anthropic-version`) answers with so Anthropic's SDKs and Claude Code read it. `error.type` names the failure: `invalid_request_error` (400, 405, 413 as `request_too_large`), `authentication_error` (401), `not_found_error` (404), `rate_limit_error` (429), `api_error` (5xx).", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } }, "chat-completion-request-payload": { "title": "Chat Completion Request Payload", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "request" ], "description": "Chat Completion Request Payload", "x-examples": {}, "required": [ "messages" ], "properties": { "model": { "type": "string", "description": "The [model](#operation/list-models) to use. If omitted, the gateway resolves its default model. A `-normalize` suffix is accepted for compatibility and ignored; every response is normalized. A `:` suffix is parsed separately from the model ID; `:express` derives a thinking budget when the model supports enforced budgets and no explicit budget is supplied." }, "messages": { "type": "array", "minItems": 1, "description": "The message context to use for the chat completion request, separated by system, user, assistant, tool, and developer roles. A final `assistant` message is treated as a prefill and continued (see `continue_final_message`).", "items": { "$ref": "#/components/schemas/chat-completion-req-message" } }, "continue_final_message": { "type": "boolean", "default": false, "description": "Continue the final message instead of starting a new assistant turn. Implied whenever the final message has the `assistant` role, so it only makes the intent explicit. The final message must carry non-empty text and no `tool_calls`; trailing whitespace is trimmed, thinking is disabled for the continuation, and only the newly generated text is returned. Use it to resume a response that ended with `finish_reason` `length`." }, "stream": { "type": "boolean", "description": "Indicates whether the response should be streamed." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Deprecated name for `max_completion_tokens`. If both are sent, `max_completion_tokens` takes precedence. A value below 1 returns 400." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "default": 32768, "description": "Maximum completion tokens, including reasoning and visible output. A value below 1 returns 400; omit the field to get the default. A value that does not fit the model's context window with the prompt is not refused. It is cut to the window less the prompt and a 32 token margin, and `finish_reason` reports `length` if the answer reaches the cut. A prompt that alone fills the window returns 400." }, "reasoning_effort": { "type": "string", "enum": [ "ultra", "max", "xhigh", "high", "medium", "low", "minimal", "none" ], "description": "Shorthand for `reasoning.effort`. When both are supplied, `reasoning.effort` takes precedence. Configured models map this level to their supported reasoning control; unsupported levels return 400." }, "reasoning": { "$ref": "#/components/schemas/reasoning-request-options" }, "n": { "type": "integer", "default": 1, "minimum": 1, "description": "The number of chat completion choices to generate for each input message." }, "seed": { "type": "integer", "description": "If you would like a different response from the same message, changing the seed will change the response. A null value generates a random seed." }, "top_k": { "type": "integer", "minimum": 0, "description": "Sample only from the k most likely tokens at each step. 0 disables it. Passed to the engine; a model's default is the `top_k` in `default_parameters` of the public model list." }, "repetition_penalty": { "type": "number", "format": "float", "minimum": 0, "maximum": 2, "description": "Penalises tokens already in the prompt or the answer. 1.0 is no penalty and above 1.0 discourages repetition. Passed to the engine, which also reads it as a model default." }, "response_format": { "type": "object", "description": "Constrains the answer's format. `json_object` makes the model answer with a JSON object; `json_schema` makes it answer with JSON that matches the schema. `text` is the default.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] }, "json_schema": { "type": "object", "description": "Required when `type` is `json_schema`.", "properties": { "name": { "type": "string" }, "strict": { "type": "boolean" }, "schema": { "type": "object", "description": "A JSON Schema." } } } } }, "temperature": { "type": "number", "format": "float", "default": 1, "minimum": 0, "maximum": 2, "description": "A value between 0.0 and 2.0 that controls the randomness of the model's output. When set closer to 1, such as 0.8, the outcome is more unpredictable and creative. Values nearing 0, like 0.2, produce more predictable and less creative results. A temperature of zero requests greedy decoding; exact reproducibility depends on the model engine." }, "top_p": { "type": "number", "format": "float", "default": 1, "minimum": 0, "maximum": 1, "description": "A value between 0.0 and 1.0 that controls the probability of the model generating a particular token. A higher value will result in more diverse outputs, while a lower value will result in more repetitive outputs." }, "frequency_penalty": { "type": "number", "format": "float", "default": 0, "minimum": -2, "maximum": 2, "description": "A value between -2.0 and 2.0 that controls how much the model penalizes generating repetitive responses." }, "presence_penalty": { "type": "number", "format": "float", "default": 0, "minimum": -2, "maximum": 2, "description": "A value between -2.0 and 2.0 that controls how much the model penalizes generating responses that contain certain words or phrases." }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "maxItems": 4, "items": { "type": "string" } } ], "description": "The strings the model stops generating at, up to 4. A single string is accepted as shorthand for a one-item array." }, "logprobs": { "type": "boolean", "description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. Optional: `logprobs: true` alone returns the sampled token's log probability. Requires `logprobs` to be true." }, "tool_choice": { "description": "Controls which (if any) tool is called by the model. A tool choice other than `none` requires `tools`.", "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ], "description": "`none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.\n" }, { "$ref": "#/components/schemas/function-tool-choice" }, { "type": "object", "title": "Allowed tools", "description": "Constrains the tools available to the model to a pre-defined set. The gateway sends the engine only the allowed tools, with `mode` as the tool choice.", "required": [ "type", "allowed_tools" ], "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ], "description": "Allowed tool configuration type. Always `allowed_tools`." }, "allowed_tools": { "type": "object", "required": [ "mode", "tools" ], "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "`auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools." }, "tools": { "type": "array", "minItems": 1, "description": "The functions the model may call, each named in the request's `tools`.", "items": { "$ref": "#/components/schemas/function-tool-choice" } } } } } } ] }, "tools": { "type": "array", "description": "A list of function tools the model may call.", "items": { "$ref": "#/components/schemas/function-tool" } } } }, "chat-completion-req-message": { "title": "Chat Completion Request Message", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "message" ], "description": "An object containing the role and content for a chat completion request message.", "x-examples": {}, "properties": { "role": { "type": "string", "enum": [ "system", "assistant", "user", "tool", "developer" ], "description": "The role of the author of this message." }, "content": { "description": "The contents of the message: a string, or an array of content parts (text, images, audio, video and documents).\nMedia parts are accepted on `user` messages. See `chat-content-part` for documents: they are converted to text,\nwhich becomes part of the prompt.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/chat-content-part" } } ] } } }, "chat-content-part": { "title": "Chat Content Part", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "message", "documents" ], "description": "One part of a message's content.\n\n**Documents.** A document is converted to text before the model sees it, and that text takes the document's place\nin the conversation. Send a document as a `file` part (OpenAI's and OpenRouter's shape), as an `image_url` part\nwhose URL or data URI is a document, or as an Anthropic `document` block. Accepted types: PDF\n(`application/pdf`), Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`), PowerPoint (`.ppt`, `.pptx`), RTF, HTML,\nCSV, Markdown, JSON, XML and plain text. A data URI with a generic type (`application/octet-stream`) is read by\nits `filename`, then by its content; a link is read by its path, its `Content-Type`, then its content, so signed\nand `/download?id=` links work.\n\n- **Tokens.** The converted text is part of the prompt: it counts toward the model's context window and is\n billed as prompt tokens, like any other text. A document whose text does not fit the model's context window\n is refused with a 400.\n- **Limits.** PDFs up to 300 pages and 100 MB. Scanned and photographed pages are read as well as born-digital\n ones.\n- **Latency and caching.** Conversion adds about a second for a short document and roughly half a second per\n page for a long PDF. The same file sent again within an hour is not converted again. If your client times\n out, retry with the same file: the first conversion goes on, and the retry gets its result.\n- **Errors.** A document the API cannot use (malformed, encrypted, over the page or size limit, an unreadable\n link) is a 400 whose message says why. A 503 with a `Retry-After` header means conversion is busy: retry\n after that many seconds.\n- **`file_id`.** Upload a document once with `POST /files` and reference it by `file_id`: its text was converted\n when it was uploaded, so the request does no conversion. A file still `processing`, in `error`, expired or not\n this account's is a 400 that says which.\n", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "input_audio", "video_url", "file", "document" ], "description": "The type of the part." }, "text": { "type": "string", "description": "The text. Present when type is `text`." }, "image_url": { "type": "object", "description": "An image, or a document, by URL or data URI. Present when type is `image_url`.", "properties": { "url": { "type": "string", "description": "An `https` URL, or a base64 data URI such as `data:image/png;base64,...` or `data:application/pdf;base64,...`." } } }, "input_audio": { "type": "object", "description": "Audio, base64-encoded or by URL. Present when type is `input_audio`.", "properties": { "data": { "type": "string" }, "format": { "type": "string", "example": "wav" } } }, "video_url": { "type": "object", "description": "A video by URL or data URI. Present when type is `video_url`.", "properties": { "url": { "type": "string" } } }, "file": { "type": "object", "description": "A file, usually a document. Present when type is `file`.", "properties": { "filename": { "type": "string", "description": "The file's name. Its extension tells the format when `file_data` does not.", "example": "annual-report.pdf" }, "file_data": { "type": "string", "description": "The file as a base64 data URI (`data:application/pdf;base64,...`), bare base64 (with a `filename`), or an `https` URL." }, "file_id": { "type": "string", "description": "A processed file uploaded with `POST /files`, in place of `file_data`." } } }, "source": { "type": "object", "description": "The document, in Anthropic's shape. Present when type is `document`: `{\"type\": \"base64\", \"media_type\": \"application/pdf\", \"data\": \"...\"}` or `{\"type\": \"url\", \"url\": \"https://...\"}`." } } }, "reasoning-request-options": { "title": "Reasoning Request Options", "type": "object", "description": "Reasoning controls. Configured models map effort through their database profile. Models advertising `reasoning.supports_max_tokens: true` in `/v1/models?format=openrouter` (a `max_tokens` property under the `reasoning` parameter in the default list) enforce the budget; other models accept it without enforcing it.", "properties": { "effort": { "type": "string", "enum": [ "ultra", "max", "xhigh", "high", "medium", "low", "minimal", "none" ] }, "enabled": { "type": "boolean", "description": "When false, sets effort to `none`." }, "summary": { "type": "string", "enum": [ "auto", "concise", "detailed" ], "description": "Accepted but not supported by the current engines." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Thinking-token budget. Must be below the effective completion limit so the model has room to answer. Ignored when thinking is disabled or a final assistant message is being continued." } } }, "function-tool-choice": { "title": "Chat Completion Function Tool Choice", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "tools", "functions" ], "description": "Specifies a tool the model should use. Use to force the model to call a specific function.", "x-examples": {}, "required": [ "type", "function" ], "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "For function calling, the type is always `function`." }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." } } } } }, "function-tool": { "title": "Chat Completion Function Tool", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "tools", "functions" ], "description": "A function tool that can be used to generate a response.", "x-examples": {}, "properties": { "type": { "type": "string", "description": "The type of the tool. Currently, only `function` is supported." }, "function": { "$ref": "#/components/schemas/tool-function" } } }, "tool-function": { "title": "Chat Completion Tool Function", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "tools", "functions" ], "description": "An object representing a function for use with chat completion tool calling.", "x-examples": {}, "properties": { "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64" }, "description": { "type": "string", "description": "A description of what the function does, used by the model to choose when and how to call the function." }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object." }, "strict": { "type": "boolean", "description": "Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`." } } }, "chat-completion-response-payload": { "title": "Chat Completion Response Payload", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "response" ], "description": "OpenRouter's chat completion. The shape is the same whichever engine serves the model: engine-specific fields are removed and reasoning, usage, ids and finish reasons are normalized.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion, prefixed `chatcmpl-`." }, "object": { "type": "string", "description": "Always `chat.completion`." }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) of when the chat completion was created." }, "model": { "type": "string", "description": "The model that was inferred for chat completion." }, "choices": { "type": "array", "description": "The resulting assistant message(s) for the chat completion.", "items": { "$ref": "#/components/schemas/chat-completion-choice" } }, "usage": { "$ref": "#/components/schemas/chat-completion-usage" } } }, "chat-completion-choice": { "title": "Chat Completion Choice", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "choice" ], "description": "Chat Completion Choice", "x-examples": {}, "properties": { "index": { "type": "integer", "description": "The index of the choice in the list of choices." }, "message": { "$ref": "#/components/schemas/chat-completion-message" }, "logprobs": { "anyOf": [ { "$ref": "#/components/schemas/chat-completion-logprobs" }, { "type": "null" } ] }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "error" ], "description": "Why the model stopped, normalized across engines. `tool_calls` whenever the message carries tool calls." }, "native_finish_reason": { "type": [ "string", "null" ], "description": "The engine's own finish reason, unmodified." } } }, "chat-completion-message": { "title": "Chat Completion Message", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "message" ], "description": "An object containing the role and content for a chat completion message.", "x-examples": {}, "properties": { "role": { "type": "string", "enum": [ "system", "assistant", "user", "tool", "developer" ], "description": "The role of the author of this message." }, "content": { "type": "string", "description": "The contents of the message. Always a string, empty when the model only called tools." }, "reasoning": { "type": [ "string", "null" ], "description": "The reasoning (chain-of-thought) the model produced, or null. Every model reports it here; `reasoning_content` is not used." }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.", "items": { "$ref": "#/components/schemas/message-tool-calls" } } } }, "message-tool-calls": { "title": "Chat Completion Message Tool Calls", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "tools", "functions" ], "description": "An object containing the tool calls generated by the model for a chat completion choice.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The ID of the tool call, in the form `call_`. Send it back unchanged as the `tool_call_id` of the tool result." }, "type": { "type": "string", "description": "The type of the tool. Currently, only `function` is supported." }, "function": { "$ref": "#/components/schemas/tool-call-function" } } }, "tool-call-function": { "title": "Chat Completion Tool Call Function", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "tools", "functions" ], "description": "An object containing the the function that the model called for a chat completion choice.", "x-examples": {}, "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format." } } }, "chat-completion-logprobs": { "title": "Chat Completion Logprobs", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "logprobs" ], "description": "An object containing the log probability information for a chat completion choice.", "x-examples": {}, "properties": { "content": { "type": "array", "description": "A list of message content tokens with log probability information.", "items": { "$ref": "#/components/schemas/logprobs-message-content-tokens" } } } }, "logprobs-message-content-tokens": { "title": "Chat Completion Logprobs Message Content Tokens", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "logprobs" ], "description": "An object containing message content tokens for a chat completion choice log probability information.", "x-examples": {}, "properties": { "token": { "type": "string", "description": "The text content of the token." }, "logprob": { "type": "number", "format": "float", "description": "The log probability of the token." }, "bytes": { "type": "array", "description": "A list of integers representing the UTF-8 bytes representation of the token.", "items": { "type": "integer" } }, "top_logprobs": { "type": "array", "description": "List of the most likely tokens and their log probability, at this token position.", "items": { "$ref": "#/components/schemas/logprobs-message-content-token" } } } }, "logprobs-message-content-token": { "title": "Chat Completion Logprobs Message Content Token", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "logprobs" ], "description": "An object containing a message content token for a chat completion choice log probability information.", "x-examples": {}, "properties": { "token": { "type": "string", "description": "The text content of the token." }, "logprob": { "type": "number", "format": "float", "description": "The log probability of the token." }, "bytes": { "type": "array", "description": "A list of integers representing the UTF-8 bytes representation of the token.", "items": { "type": "integer" } } } }, "chat-completion-usage": { "title": "Chat Completion Usage", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "usage" ], "description": "An object containing usage information for this request.", "x-examples": {}, "properties": { "completion_tokens": { "type": "integer", "description": "Number of tokens in the generated completion, including reasoning tokens." }, "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt. Includes vector search embeddings tokens for RAG requests." }, "total_tokens": { "type": "integer", "description": "Total number of tokens used in the request (prompt + completion)." }, "prompt_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer", "description": "Prompt tokens served from the prefix cache. 0 when the engine does not report it." } } }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer", "description": "The part of `completion_tokens` spent on reasoning. 0 when the engine does not report it." } } } } }, "chat-completion-streaming-response-payload": { "title": "Chat Completion Streaming Response Payload", "type": "string", "x-tags": [ "inference", "text generation", "chat completion", "response", "streaming" ], "description": "A text/event-stream body of `chat.completion.chunk` JSON data lines ending with `[DONE]`. Each chunk has `id`, `object`, `created`, `model` and `choices`; each choice, except the final chunk's, has `index`, `delta`, `logprobs`, `finish_reason` and `native_finish_reason`. A delta carries only the fields it adds (`role`, `content`, `reasoning`, `tool_calls`), never nulls. The final chunk carries `usage` and, as OpenRouter's does, one content-free choice, `{\"index\": 0, \"delta\": {}, \"finish_reason\": ..., \"native_finish_reason\": ...}`, repeating the stream's finish values, so a client that reads `choices[0]` on every chunk does not fail. It is always sent, whatever `stream_options.include_usage` says. An error before the stream starts is returned with its HTTP status and the error envelope; an error after it starts arrives as a final chunk with `error` and a choice whose `finish_reason` is `error`, followed by `[DONE]`." }, "error-payload": { "title": "Error Payload", "type": "object", "description": "OpenRouter's error envelope, used by chat completions, responses, rerank and the vector store. `code` is the HTTP status; `metadata.error_type` names the failure in OpenRouter's typed vocabulary, e.g. `context_length_exceeded`, `rate_limit_exceeded`, `invalid_request`.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "type", "metadata" ], "properties": { "code": { "type": "integer", "description": "The HTTP status code." }, "message": { "type": "string" }, "type": { "type": "string", "description": "OpenAI-style error type, kept for OpenAI SDK compatibility." }, "metadata": { "type": "object", "properties": { "error_type": { "type": "string", "description": "OpenRouter's typed error code. Chat also uses `media_processing_failed` for media a model cannot accept." } } } } } } }, "response-create-request-payload": { "title": "Response Create Request Payload", "type": "object", "required": [ "input" ], "description": "OpenAI's Responses request. Fields not listed here are passed to the engine. `store` is accepted and ignored: nothing is stored.", "properties": { "model": { "type": "string", "description": "If omitted, the gateway resolves its default model. A `:` suffix is parsed separately from the model ID; `:express` derives a thinking budget when the model supports enforced budgets and no explicit budget is supplied." }, "input": { "description": "Input text or structured input items. A message item's `content` may hold `input_text`, `input_image` and\n`input_file` parts. An `input_file` (`{\"type\": \"input_file\", \"filename\": \"report.pdf\", \"file_data\":\n\"data:application/pdf;base64,...\"}`, or `file_url` in place of `file_data`) is converted to text before the\nmodel sees it, with the types, limits, token counting, caching and errors described under `chat-content-part`.\n`file_id` (a file uploaded with `POST /files`) uses its stored text.\n", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "object" } } ] }, "instructions": { "type": "string", "description": "A system prompt." }, "max_output_tokens": { "type": "integer", "minimum": 1, "default": 32768, "description": "Maximum output tokens, including reasoning and visible output. Reduced to fit the model's context window with the input." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "tools": { "type": "array", "description": "`function`, `custom` and `namespace` tools. Any other `type` (hosted tools such as `web_search`) is refused with a 400 naming it.", "items": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom", "namespace" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "A `function` tool's arguments, as a JSON schema." }, "strict": { "type": "boolean" }, "format": { "type": "object", "description": "A `custom` tool's input: `{\"type\": \"text\"}` (the default) or `{\"type\": \"grammar\", \"syntax\": \"lark\" or \"regex\", \"definition\": \"...\"}`. The grammar is described to the model; the engine does not enforce it." }, "tools": { "type": "array", "description": "A `namespace` tool's `function` tools. A call to one comes back as a `function_call` with `namespace` set.", "items": { "type": "object" } } } } }, "tool_choice": { "description": "`none`, `auto`, `required`, or a specific `function` or `custom` tool. Anything but `none` needs `tools`.", "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "name": { "type": "string" } } } ] }, "reasoning": { "$ref": "#/components/schemas/reasoning-request-options" }, "store": { "type": "boolean", "description": "Accepted and ignored. Nothing is stored, whatever the value." }, "previous_response_id": { "type": [ "string", "null" ], "description": "Refused with a 400 unless null. Responses are not stored; send the whole conversation in `input`." }, "conversation": { "description": "Refused with a 400. Conversations are not stored." }, "background": { "type": "boolean", "description": "`true` is refused with a 400. A background response would have to be stored to be retrieved." }, "stream": { "type": "boolean" } } }, "response-create-response-payload": { "title": "Response Create Response Payload", "type": "object", "description": "OpenAI's Responses API object, rebuilt from whichever engine answered. Engine-internal fields are removed.", "required": [ "id", "object", "created_at", "completed_at", "status", "error", "model", "output", "usage", "text" ], "properties": { "id": { "type": "string", "description": "`resp_` followed by hex characters. The response is not stored." }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "integer" }, "completed_at": { "type": [ "integer", "null" ], "description": "Unix time the response finished; null while it is in progress." }, "status": { "type": "string", "enum": [ "completed", "incomplete", "failed", "in_progress", "cancelled", "queued" ] }, "error": { "type": [ "object", "null" ], "description": "Why a response failed; null otherwise.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "incomplete_details": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "description": "`max_output_tokens` when the output budget ran out." } } }, "model": { "type": "string" }, "output": { "type": "array", "description": "`message`, `reasoning`, `function_call` and `custom_tool_call` items. A call's `call_id` starts with `call_`; a call to a tool of a `namespace` carries `namespace`.", "items": { "type": "object" } }, "store": { "type": "boolean", "description": "Always false." }, "previous_response_id": { "type": [ "string", "null" ], "description": "Always null." }, "text": { "type": "object", "description": "The text format; `{\"format\": {\"type\": \"text\"}}` by default." }, "tool_choice": { "description": "Echoes the request's, `auto` when none was sent." }, "tools": { "type": "array", "items": { "type": "object" } }, "usage": { "type": [ "object", "null" ], "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer", "description": "Includes reasoning tokens." }, "output_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer" } } }, "total_tokens": { "type": "integer" } } } } }, "embeddings-request-payload": { "title": "Embeddings Request Payload", "type": "object", "description": "OpenRouter's embeddings request. OpenRouter's `provider`, `session_id` and `trace` and OpenAI's `user` are accepted and ignored.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The [embeddings model](#operation/list-models) to use." }, "input": { "description": "A string, a list of strings, a list of token ids, or a list of token id lists. Up to 2048 inputs. Multimodal inputs are rejected.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "maxItems": 2048, "items": { "type": "string", "minLength": 1 } }, { "type": "array", "minItems": 1, "items": { "type": "integer" } }, { "type": "array", "minItems": 1, "maxItems": 2048, "items": { "type": "array", "items": { "type": "integer" } } } ] }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float", "description": "`base64` returns each embedding as base64-encoded little-endian float32 values." }, "dimensions": { "type": "integer", "minimum": 1, "description": "Truncate embeddings to this many dimensions, for models trained to support it (e.g. Qwen3-Embedding)." }, "input_type": { "type": "string", "description": "`search_query` (or `query`) marks the inputs as search queries, so instruction-aware models get their query instruction. Any other value, or none, sends the inputs unchanged." } } }, "embeddings-response-payload": { "title": "Embeddings Response Payload", "type": "object", "required": [ "id", "object", "data", "model", "usage" ], "properties": { "id": { "type": "string", "description": "Identifier for this response, prefixed `emb-`." }, "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "One entry per input, in input order.", "items": { "type": "object", "required": [ "object", "index", "embedding" ], "properties": { "object": { "type": "string", "description": "Always `embedding`." }, "index": { "type": "integer", "description": "Position of the input in the request." }, "embedding": { "description": "A list of floats, or a base64 string when `encoding_format` is `base64`.", "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] } } } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens the model processed, including any query instruction. This is the billed count." }, "total_tokens": { "type": "integer" } } } } }, "openrouter-public-models-response": { "title": "OpenRouter Public Models Response", "type": "object", "required": [ "data", "total_count", "links" ], "description": "OpenRouter's `ModelsListResponse`, served to its SDKs and on `?format=openrouter`.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/openrouter-public-model" } }, "total_count": { "type": "integer", "description": "Models matching the filters, before paging." }, "links": { "type": "object", "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ], "description": "Path and query of the next page, or null on the last.", "example": "/v1/models?offset=500&limit=500" } } } } }, "openrouter-public-model": { "title": "OpenRouter Public Model", "type": "object", "description": "A model in OpenRouter's public `Model` shape, which OpenRouter's SDKs parse. Built from the same entry as the provider document, so context length, price and modalities match it. `pricing.prompt` and `pricing.completion` are USD per token as strings; OpenRouter has no field for a price per second or per megapixel, so image (per megapixel), video and speech (per second generated) put their price in `completion`, transcription (per second of audio read) in `prompt`, and the other is `\"0\"`. Embeddings, rerank and decision models put the price per input token in `prompt`.\n", "required": [ "id", "canonical_slug", "name", "created", "context_length", "architecture", "pricing", "top_provider", "per_request_limits", "supported_parameters", "default_parameters", "supported_voices", "links" ], "properties": { "id": { "type": "string", "example": "glm-5.3" }, "canonical_slug": { "type": "string", "description": "The model id." }, "hugging_face_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "created": { "type": "integer", "description": "Unix timestamp." }, "description": { "type": "string" }, "context_length": { "type": [ "integer", "null" ], "description": "Tokens the model reads. Null for models that have no token context (image, video, speech, transcription)." }, "architecture": { "type": "object", "required": [ "input_modalities", "output_modalities", "modality" ], "properties": { "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "file", "audio", "video" ] } }, "output_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "embeddings", "audio", "video", "rerank", "decisions", "speech", "transcription" ] } }, "modality": { "type": "string", "example": "text+image->text" }, "tokenizer": { "type": "string", "example": "Other" }, "instruct_type": { "type": [ "string", "null" ] } } }, "pricing": { "type": "object", "required": [ "prompt", "completion" ], "properties": { "prompt": { "type": "string", "example": "0.00000055" }, "completion": { "type": "string", "example": "0.00000275" }, "internal_reasoning": { "type": "string" }, "input_cache_read": { "type": "string" } } }, "top_provider": { "type": "object", "required": [ "is_moderated" ], "properties": { "context_length": { "type": [ "integer", "null" ] }, "max_completion_tokens": { "type": [ "integer", "null" ] }, "is_moderated": { "type": "boolean" } } }, "per_request_limits": { "type": [ "object", "null" ] }, "supported_parameters": { "type": "array", "items": { "type": "string" }, "example": [ "temperature", "top_p", "max_tokens", "tools" ] }, "default_parameters": { "type": [ "object", "null" ], "description": "The model row's sampling defaults, limited to temperature, top_p, top_k, frequency_penalty, presence_penalty and repetition_penalty.", "properties": { "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "repetition_penalty": { "type": "number" } } }, "supported_voices": { "type": [ "array", "null" ], "description": "A speech model's voice ids; null for every other model.", "items": { "type": "string" } }, "links": { "type": "object", "required": [ "details" ], "properties": { "details": { "type": "string", "example": "/v1/model/vultr/glm-5.3" } } }, "reasoning": { "type": "object", "description": "Present on reasoning models. Fields the gateway does not know are left out, never null.", "required": [ "mandatory" ], "properties": { "mandatory": { "type": "boolean" }, "supports_max_tokens": { "type": "boolean" }, "supported_efforts": { "type": "array", "items": { "type": "string" } }, "default_effort": { "type": "string" }, "default_enabled": { "type": "boolean" } } } } }, "systemone-request-payload": { "title": "Decision Request Payload", "type": "object", "description": "TypeSafe's `/v1/systemone` request.", "required": [ "model", "state", "questions" ], "properties": { "model": { "type": "string", "description": "The [decision model](#operation/list-models) to use." }, "state": { "description": "What to decide about. A string, or structured data (an object or array), which the model reads as JSON.", "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array", "items": {} } ] }, "questions": { "type": "object", "description": "Up to 64 questions, by id. Each answer comes back under its question's id.", "additionalProperties": { "$ref": "#/components/schemas/systemone-question" } } } }, "systemone-question": { "title": "Decision Question", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "noul", "choice", "score" ] }, "instructions": { "description": "Optional. The question as text, or structured data read as JSON; a question can be carried by its criteria alone.", "oneOf": [ { "type": [ "string", "null" ] }, { "type": "object" }, { "type": "array", "items": {} } ] }, "criteria": { "description": "`noul`: optional `{\"true\": ..., \"false\": ...}` descriptions of yes and no.\n`choice`: required, 1 to 255 options mapped to a description, or null when the option's name says enough.\n`score`: required, 1 to 10 level descriptions, lowest first; a null level is described by its index.\nA single option or level is answered with probability 1 and confidence 1.\nEvery description may be text or structured data read as JSON.\n", "oneOf": [ { "type": "object", "additionalProperties": { "oneOf": [ { "type": [ "string", "null" ] }, { "type": "object" }, { "type": "array", "items": {} } ] } }, { "type": "array", "minItems": 1, "maxItems": 10, "items": { "oneOf": [ { "type": [ "string", "null" ] }, { "type": "object" }, { "type": "array", "items": {} } ] } } ] } } }, "systemone-response-payload": { "title": "Decision Response Payload", "type": "object", "required": [ "model", "answers", "usage" ], "properties": { "model": { "type": "string" }, "answers": { "type": "object", "description": "One answer per question, by question id.", "additionalProperties": { "$ref": "#/components/schemas/systemone-answer" } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Every question's prompt, the billed count." }, "output_tokens": { "type": "integer", "description": "Always 0." } } } } }, "systemone-answer": { "title": "Decision Answer", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "noul", "choice", "score" ] }, "noul": { "type": "number", "description": "`noul` only. The probability of yes, 0 to 1." }, "choice": { "type": "string", "description": "`choice` only. The most likely option." }, "score": { "type": "number", "description": "`score` only. The probability-weighted level, from 0 to the highest level index." }, "legend": { "type": "object", "description": "`score` only. Each level index mapped to its description.", "additionalProperties": { "type": "string" } }, "probabilities": { "type": "object", "description": "`choice` and `score`. Each option, or level index, mapped to its probability; they sum to 1.", "additionalProperties": { "type": "number" } }, "confidence": { "type": "number", "description": "`choice` and `score`. 1 when the distribution is on one answer, 0 when it is uniform." } } }, "rerank-request-payload": { "title": "Rerank Request Payload", "type": "object", "description": "OpenRouter's rerank request. Every model receives only the query and plain-text documents; `top_n` and the document echo are applied by the API so they behave the same on every model. OpenRouter's `provider`, `user`, `session_id` and `trace` and Cohere v2's `max_tokens_per_doc` and `priority` are accepted and ignored.", "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "The [rerank model](#operation/list-models) to use." }, "query": { "type": "string", "minLength": 1, "description": "The search query to rank the documents against." }, "documents": { "type": "array", "minItems": 1, "description": "The documents to rank, as plain strings or objects with a `text` field. Image documents are rejected.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } ] } }, "top_n": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Return only the highest scoring `top_n` results. All results are returned when omitted." }, "return_documents": { "type": "boolean", "default": true, "description": "Extension to OpenRouter's schema. Set `false` to omit `document` from each result." } } }, "rerank-response-payload": { "title": "Rerank Response Payload", "type": "object", "description": "OpenRouter's rerank response, whichever engine serves the model.", "required": [ "id", "model", "results", "usage" ], "properties": { "id": { "type": "string", "description": "Identifier for this rerank response." }, "model": { "type": "string", "description": "The model that ranked the documents." }, "results": { "type": "array", "description": "One entry per returned document, sorted by `relevance_score`, highest first.", "items": { "type": "object", "required": [ "index", "relevance_score" ], "properties": { "index": { "type": "integer", "description": "Position of the document in the request's `documents` list." }, "relevance_score": { "type": "number", "format": "double", "description": "The model's own score, passed through unchanged. Higher is more relevant, but the scale is model specific: `bge-reranker-v2-m3` scores between 0 and 1, while the Vultron Retriever models use an unbounded scale. Compare scores within one model, not across models." }, "document": { "type": "object", "description": "The ranked document as `{text}`. Omitted when `return_documents` is `false`.", "properties": { "text": { "type": "string" } } } } } }, "usage": { "type": "object", "properties": { "total_tokens": { "type": "integer", "description": "Tokens the model processed across every query and document pair. This is the billed input token count." } } } } }, "chat-rag-request-payload": { "title": "Chat Completion RAG Request Payload", "type": "object", "x-tags": [ "inference", "text generation", "chat completion", "request", "RAG", "retrieval augmented generation", "retrieval-augmented generation" ], "description": "Chat Completion RAG Request Payload", "x-examples": {}, "required": [ "collection", "model", "messages" ], "properties": { "collection": { "type": "string", "description": "The [vector store collection](#operation/list-vector-stores) to search for relevant context." }, "model": { "type": "string", "description": "The [model](#operation/list-models) that will be inferred for chat completion. A `-normalize` suffix is accepted for compatibility and ignored; every response is normalized." }, "messages": { "type": "array", "minItems": 1, "description": "The message context to use for the chat completion request, separated by system, user, assistant, tool, and developer roles.", "items": { "$ref": "#/components/schemas/chat-completion-req-message" } }, "max_tokens": { "type": "integer", "description": "Deprecated name for `max_completion_tokens`. If both are sent, `max_completion_tokens` takes precedence." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "default": 32768, "description": "Maximum completion tokens, including reasoning and visible output." }, "reasoning_effort": { "type": "string", "enum": [ "ultra", "max", "xhigh", "high", "medium", "low", "minimal", "none" ], "description": "Shorthand for `reasoning.effort`. Configured models map this level to their supported reasoning control." }, "reasoning": { "$ref": "#/components/schemas/reasoning-request-options" }, "n": { "type": "integer", "default": 1, "description": "The number of chat completion choices to generate for each input message." }, "seed": { "type": "integer", "description": "If you would like a different response from the same message, changing the seed will change the response. A null value generates a random seed." }, "temperature": { "type": "number", "format": "float", "default": 1, "minimum": 0, "maximum": 2, "description": "A value between 0.0 and 2.0 that controls the randomness of the model's output. When set closer to 1, such as 0.8, the outcome is more unpredictable and creative. Values nearing 0, like 0.2, produce more predictable and less creative results. A temperature of zero requests greedy decoding; exact reproducibility depends on the model engine." }, "top_p": { "type": "number", "format": "float", "default": 1, "minimum": 0, "maximum": 1, "description": "A value between 0.0 and 1.0 that controls the probability of the model generating a particular token. A higher value will result in more diverse outputs, while a lower value will result in more repetitive outputs." }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "maxItems": 4, "items": { "type": "string" } } ], "description": "The strings the model stops generating at, up to 4. A single string is accepted as shorthand for a one-item array." }, "frequency_penalty": { "type": "number", "format": "float", "default": 0, "minimum": -2, "maximum": 2, "description": "A value between -2.0 and 2.0 that controls how much the model penalizes generating repetitive responses." }, "presence_penalty": { "type": "number", "format": "float", "default": 0, "minimum": -2, "maximum": 2, "description": "A value between -2.0 and 2.0 that controls how much the model penalizes generating responses that contain certain words or phrases." }, "stream": { "type": "boolean", "description": "Indicates whether the response should be streamed." }, "logprobs": { "type": "boolean", "description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. Optional: `logprobs: true` alone returns the sampled token's log probability. Requires `logprobs` to be true." }, "tool_choice": { "description": "Controls which (if any) tool is called by the model. A tool choice other than `none` requires `tools`.", "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ], "description": "`none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.\n" }, { "$ref": "#/components/schemas/function-tool-choice" }, { "type": "object", "title": "Allowed tools", "description": "Constrains the tools available to the model to a pre-defined set. The gateway sends the engine only the allowed tools, with `mode` as the tool choice.", "required": [ "type", "allowed_tools" ], "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ], "description": "Allowed tool configuration type. Always `allowed_tools`." }, "allowed_tools": { "type": "object", "required": [ "mode", "tools" ], "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "`auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools." }, "tools": { "type": "array", "minItems": 1, "description": "The functions the model may call, each named in the request's `tools`.", "items": { "$ref": "#/components/schemas/function-tool-choice" } } } } } } ] }, "tools": { "type": "array", "description": "A list of function tools the model may call.", "items": { "$ref": "#/components/schemas/function-tool" } } } }, "audio-models-response-payload": { "title": "Audio Models Response Payload", "type": "object", "required": [ "speech", "transcription" ], "properties": { "speech": { "type": "array", "description": "Text-to-speech models, for `POST /v1/audio/speech`.", "items": { "$ref": "#/components/schemas/text-to-speech-model" } }, "transcription": { "type": "array", "description": "Transcription models, for `POST /v1/audio/transcriptions`.", "items": { "$ref": "#/components/schemas/text-to-speech-model" } } } }, "text-to-speech-model": { "title": "Audio Model", "type": "object", "description": "A speech or transcription model, as `GET /v1/audio/models` and `GET /v1/models/all` list it.", "required": [ "id", "created", "price", "price_per_second" ], "properties": { "id": { "type": "string", "description": "The model id to send as `model`.", "example": "qwen3-tts-12hz-1.7b" }, "created": { "type": "integer", "description": "When the model was added, in Unix seconds." }, "price_per_second": { "type": "number", "description": "US dollars per second of audio (produced for speech, read for transcription)." }, "price": { "type": "number", "deprecated": true, "description": "The same value as `price_per_second`, kept for clients that read it." } } }, "text-to-speech-request-payload": { "title": "Text-to-Speech Request Payload", "type": "object", "x-tags": [ "inference", "speech generation", "text-to-speech", "request" ], "description": "Text-to-Speech Request Payload", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The text-to-speech [model](#operation/list-models), e.g. `qwen3-tts-12hz-1.7b`." }, "input": { "type": "string", "description": "The text to speak, up to the model's `max_prompt_length` in characters." }, "voice": { "description": "A built-in speaker, `design` or `clone`, as a string or as OpenAI's `{\"id\": ...}`. Defaults to the model's default speaker, or `clone` when `input_references` is sent.", "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] }, "instructions": { "type": "string", "description": "Style for a built-in speaker, or the description of the voice for `design`. Not accepted with `clone`." }, "input_references": { "type": "array", "description": "OpenRouter's reference parts for `clone`. One `input_audio` clip and, optionally, its transcript as a `text` part.", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_audio", "text" ] }, "input_audio": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "description": "The clip, base64-encoded or a base64 data URI. Up to 15 MB decoded. URLs are not accepted." }, "format": { "type": "string", "enum": [ "wav", "mp3", "flac", "ogg", "m4a", "webm" ] } } }, "text": { "type": "string", "maxLength": 10000, "description": "What the clip says." } } } }, "language": { "type": "string", "description": "The language of the input, as `auto` (the default), an ISO 639-1 code or a name." }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "flac", "wav", "pcm" ], "default": "mp3" }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ], "default": "audio" }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "default": 1 }, "seed": { "type": "integer" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "The engine takes values above 0, so 0 is sent as 0.000001, which keeps only the likeliest token." }, "top_k": { "type": "integer", "minimum": -1 } } }, "transcription-json-request-payload": { "title": "Transcription Request Payload (JSON)", "type": "object", "description": "OpenRouter's transcription request. OpenRouter's `provider` is accepted and ignored.", "required": [ "model", "input_audio" ], "properties": { "model": { "type": "string", "description": "The speech-to-text model to use, e.g. `whisper-large-v3-turbo`." }, "input_audio": { "type": "object", "required": [ "data", "format" ], "properties": { "data": { "type": "string", "description": "The audio, base64-encoded. Raw base64, not a data URI. Up to 25 MB decoded." }, "format": { "type": "string", "enum": [ "wav", "mp3", "flac", "m4a", "ogg", "webm", "aac" ] } } }, "language": { "type": "string", "description": "ISO-639-1 code of the spoken language. Detected when omitted." }, "prompt": { "type": "string", "description": "Text to guide spelling and style, such as names and terms in the audio." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "response_format": { "type": "string", "enum": [ "json", "text" ], "default": "json" }, "stream": { "type": "boolean", "default": false, "description": "Stream the transcript as OpenAI's `transcript.text.*` server-sent events." } } }, "transcription-multipart-request-payload": { "title": "Transcription Request Payload (multipart)", "type": "object", "description": "OpenAI's transcription upload.", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "The speech-to-text model to use, e.g. `whisper-large-v3-turbo`." }, "file": { "type": "string", "format": "binary", "description": "The audio file, up to 25 MB." }, "language": { "type": "string", "description": "ISO-639-1 code of the spoken language. Detected when omitted." }, "prompt": { "type": "string", "description": "Text to guide spelling and style, such as names and terms in the audio." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "response_format": { "type": "string", "enum": [ "json", "text" ], "default": "json" }, "stream": { "type": "boolean", "default": false, "description": "Stream the transcript as OpenAI's `transcript.text.*` server-sent events." } } }, "transcription-response-payload": { "title": "Transcription Response Payload", "type": "object", "required": [ "text", "usage" ], "properties": { "text": { "type": "string", "description": "The transcript." }, "usage": { "type": "object", "properties": { "type": { "type": "string", "description": "Always `duration`." }, "seconds": { "type": "integer", "description": "Seconds of audio, rounded up. This is the billed amount." } } } } }, "audio-voices-response-payload": { "title": "List Audio Voices Response Payload", "type": "object", "x-tags": [ "inference", "audio generation", "speech", "text-to-speech", "voices", "response" ], "description": "List Audio Voices Response Payload", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The value to send as `voice`." }, "name": { "type": "string" }, "mode": { "type": "string", "description": "What the voice selects, e.g. `custom_voice`, `voice_design` or `base` (cloning)." }, "native_language": { "type": "string" }, "description": { "type": "string" } } } } } }, "list-files-response-payload": { "title": "List Files Response Payload", "type": "object", "x-tags": [ "files" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/file-object" } }, "has_more": { "type": "boolean" } } }, "file-object": { "title": "File", "type": "object", "x-tags": [ "files" ], "description": "An uploaded file, in OpenAI's shape.", "properties": { "id": { "type": "string", "example": "file-6f1d2c9a4b7e8f0a1c2d3e4f" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer" }, "created_at": { "type": "integer", "description": "Unix seconds." }, "expires_at": { "type": "integer", "description": "Unix seconds; 30 days after upload. The file and its text are gone after." }, "filename": { "type": "string" }, "purpose": { "type": "string", "description": "As uploaded; `user_data` when none was given. Any purpose can be referenced." }, "status": { "type": "string", "enum": [ "processing", "processed", "error" ], "description": "`processed` once the file can be referenced by `file_id`." }, "status_details": { "type": [ "string", "null" ], "description": "Why the file is in `error`, for example `The PDF has 301 pages; the limit is 300`." } } }, "create-file-request-payload": { "title": "Upload File Request Payload", "type": "object", "x-tags": [ "files" ], "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The document. Its type is read from its name, then its content." }, "purpose": { "type": "string", "maxLength": 32, "default": "user_data", "description": "Stored and reported as given (OpenAI's `user_data`, `assistants` and so on)." } } }, "delete-file-response-payload": { "title": "Delete File Response Payload", "type": "object", "x-tags": [ "files" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "deleted": { "type": "boolean" } } }, "list-vector-stores-response-payload": { "title": "List Vector Stores Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "response" ], "description": "List Vector Stores Response Payload", "x-examples": {}, "properties": { "collections": { "type": "array", "description": "A list of vector store collections.", "items": { "$ref": "#/components/schemas/vector-store-collection" } } } }, "vector-store-collection": { "title": "Vector Store Collection", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection" ], "description": "An object representing a vector store collection containing embeddings records.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique ID of the vector store collection." }, "name": { "type": "string", "description": "The name of the vector store collection." }, "created": { "type": "string", "description": "The UTC creation timestamp of the vector store collection in ISO 8601 format." } } }, "create-vector-store-request-payload": { "title": "Create Vector Store Request Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "request" ], "description": "Create Vector Store Request Payload", "x-examples": {}, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the vector store collection. This is also used to auto-generate a unique ID for the record." } } }, "get-vector-store-response-payload": { "title": "Vector Store Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "response" ], "description": "Vector Store Response Payload", "x-examples": {}, "properties": { "collection": { "$ref": "#/components/schemas/vector-store-collection" } } }, "update-vector-store-request-payload": { "title": "Update Vector Store Request Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "request" ], "description": "Update Vector Store Request Payload", "x-examples": {}, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the vector store collection. Note: the previously generated unique ID will remain the same." } } }, "search-vector-store-request-payload": { "title": "Search Vector Store Request Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "search", "request" ], "description": "Search Vector Store Request Payload", "x-examples": {}, "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The text query to search against the embeddings items in the vector store collection." } } }, "search-vector-store-response-payload": { "title": "Search Vector Store Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "search", "response" ], "description": "Search Vector Store Response Payload", "x-examples": {}, "properties": { "results": { "type": "array", "description": "A list of collection items that best match the embeddings search query, sorted by most relevant first.", "items": { "$ref": "#/components/schemas/vector-store-search-result" } }, "usage": { "$ref": "#/components/schemas/embeddings-usage" } } }, "vector-store-search-result": { "title": "Vector Store Collection", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "search" ], "description": "An object representing a collection item search result.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique ID of the vector store collection item." }, "created": { "type": "string", "description": "The UTC creation timestamp of the collection item in ISO 8601 format." }, "content": { "type": "string", "description": "The readable content text of the vector store collection item." } } }, "embeddings-usage": { "title": "Embeddings Usage", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "usage" ], "description": "An object containing usage information for this embeddings request.", "x-examples": {}, "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the provided input." }, "total_tokens": { "type": "integer", "description": "Total number of tokens used in the request." } } }, "list-vector-store-items-response-payload": { "title": "List Vector Store Items Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "items", "records", "response" ], "description": "List Vector Store Items Response Payload", "x-examples": {}, "properties": { "items": { "type": "array", "description": "A list of vector store collection items.", "items": { "$ref": "#/components/schemas/vector-store-item" } } } }, "vector-store-item": { "title": "Vector Store Collection Item List", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "items", "records" ], "description": "An object representing an embeddings record within a vector store collection item list.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique ID of the vector store collection item." }, "created": { "type": "string", "description": "The UTC creation timestamp of the collection item in ISO 8601 format." }, "description": { "type": "string", "description": "The short description of the content stored as embeddings for this record." } } }, "add-vector-store-item-request-payload": { "title": "Add Vector Store Item Request Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "items", "request" ], "description": "Add Vector Store Item Request Payload", "x-examples": {}, "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The text to be converted into embeddings and stored in the vector store collection." }, "description": { "type": "string", "description": "A description of the contents in this collection item record. If omitted, this value will default to a shortened version of the text stored in the collection." }, "auto_chunk": { "type": "boolean", "description": "Indicates whether the system will automatically chunk the content if it exceeds the embeddings model's maximum sequence length. If set to true, the content will be split into 300 token chunks with 20 tokens of overlap before and after each piece." } } }, "add-vector-store-item-response-payload": { "title": "Add Vector Store Item Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "items", "response" ], "description": "Add Vector Store Item Response Payload", "x-examples": {}, "required": [ "item", "usage" ], "properties": { "item": { "$ref": "#/components/schemas/vector-store-item-full" }, "usage": { "$ref": "#/components/schemas/embeddings-usage" } } }, "vector-store-item-full": { "title": "Vector Store Collection Item", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "items", "records" ], "description": "An object representing an embeddings record within a vector store collection.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique ID of the vector store collection item." }, "created": { "type": "string", "description": "The UTC creation timestamp of the collection item in ISO 8601 format." }, "description": { "type": "string", "description": "The short description of the content stored as embeddings for this record." }, "content": { "type": "string", "description": "The full text of the content stored as embeddings for this record." } } }, "add-vector-store-item-chunked-response-payload": { "title": "Add Vector Store Item Chunked Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "items", "response" ], "description": "Add Vector Store Item Chunked Response Payload", "x-examples": {}, "required": [ "items", "usage" ], "properties": { "items": { "type": "array", "description": "A list of vector store collection items for the chunked content.", "items": { "$ref": "#/components/schemas/vector-store-item-full" } }, "usage": { "$ref": "#/components/schemas/embeddings-usage" } } }, "get-vector-store-item-response-payload": { "title": "Get Vector Store Item Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "item", "response" ], "description": "Get Vector Store Item Response Payload", "x-examples": {}, "properties": { "item": { "$ref": "#/components/schemas/vector-store-item-full" } } }, "update-vector-store-item-request-payload": { "title": "Update Vector Store Item Request Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "items", "request" ], "description": "Update Vector Store Item Request Payload", "x-examples": {}, "required": [ "description" ], "properties": { "description": { "type": "string", "description": "A description of the contents in this collection item record." } } }, "list-vector-store-files-response-payload": { "title": "List Vector Store Files Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "files", "records", "response" ], "description": "List Vector Store Files Response Payload", "x-examples": {}, "properties": { "files": { "type": "array", "description": "A list of vector store collection items.", "items": { "$ref": "#/components/schemas/vector-store-file" } } } }, "vector-store-file": { "title": "Vector Store Collection File", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "files", "records" ], "description": "An object representing a file uploaded to a vector store collection.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique ID of the vector store collection file." }, "filename": { "type": "string", "description": "The name and extension of the file added to the vector store collection." }, "status": { "type": "string", "enum": [ "enqueued", "processing", "complete", "error" ], "description": "The current processing status of the vector store collection file." }, "error": { "type": "string", "description": "The description of what error was reached while processing the file for `error` status only." }, "items": { "type": "integer", "description": "The number of embeddings records representing the file in the vector store collection. Omitted for `error` status." }, "tokens": { "type": "integer", "description": "The number of tokens used while processing the uploaded file. Omitted for `error` status." } } }, "add-vector-store-file-response-payload": { "title": "Add Vector Store File Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collections", "files", "response" ], "description": "Add Vector Store File Response Payload", "x-examples": {}, "properties": { "file": { "$ref": "#/components/schemas/vector-store-file" } } }, "get-vector-store-file-response-payload": { "title": "Get Vector Store File Response Payload", "type": "object", "x-tags": [ "inference", "embeddings", "vectors", "vector store", "collection", "file", "response" ], "description": "Get Vector Store File Response Payload", "x-examples": {}, "properties": { "file": { "$ref": "#/components/schemas/vector-store-file" } } }, "image-models-response": { "title": "Image Models Response", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "created", "endpoints", "architecture", "supported_parameters", "supports_streaming" ], "properties": { "id": { "type": "string", "example": "z-image-turbo" }, "name": { "type": "string", "example": "Z-Image Turbo" }, "description": { "type": "string" }, "created": { "type": "integer", "description": "Unix time in seconds." }, "endpoints": { "type": "string", "description": "Relative URL of the model's endpoint record.", "example": "/v1/images/models/vultr/z-image-turbo/endpoints" }, "architecture": { "type": "object", "properties": { "input_modalities": { "type": "array", "items": { "type": "string" }, "example": [ "text" ] }, "output_modalities": { "type": "array", "items": { "type": "string" }, "example": [ "image" ] } } }, "supported_parameters": { "type": "object", "description": "Every parameter the model accepts by name, including the ones that are also provider options.", "additionalProperties": { "$ref": "#/components/schemas/image-capability-descriptor" } }, "supports_streaming": { "type": "boolean" } } } } } }, "image-capability-descriptor": { "title": "Image Parameter Descriptor", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "enum", "range", "boolean" ], "description": "`enum` lists `values`; `range` has `min` and `max`; `boolean` says the parameter is accepted (free text, or a number without bounds)." }, "values": { "type": "array", "items": { "type": "string" } }, "min": { "type": "number" }, "max": { "type": "number" }, "default": { "description": "The value used when the request omits the parameter." } }, "additionalProperties": true }, "image-model-endpoints-response": { "title": "Image Model Endpoints Response", "type": "object", "required": [ "id", "endpoints" ], "properties": { "id": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "provider_name": { "type": "string", "example": "Vultr" }, "provider_slug": { "type": "string", "example": "vultr" }, "provider_tag": { "type": [ "string", "null" ] }, "supported_parameters": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/image-capability-descriptor" } }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" } }, "passthrough_parameters": { "type": "object", "description": "What each provider option takes.", "additionalProperties": { "$ref": "#/components/schemas/image-capability-descriptor" } }, "pricing": { "type": "array", "items": { "type": "object", "properties": { "billable": { "type": "string", "example": "output_image" }, "cost_usd": { "type": "number", "description": "Dollars per unit." }, "unit": { "type": "string", "example": "megapixel" } } } }, "supports_streaming": { "type": "boolean" } } } } } }, "create-image-request-payload": { "title": "Create Image Request Payload", "type": "object", "x-tags": [ "inference", "image generation", "text-to-image", "request" ], "description": "One request shape for `POST /v1/images`, `/v1/images/generations` and (as JSON) `/v1/images/edits`: OpenRouter's image request, OpenAI's image request and the parameter names each model declares in `GET /v1/images/models` are all accepted on all three routes.\n\nEvery field is read, accepted and ignored by design (`user`, `session_id`, `trace`, and `provider`'s routing fields such as `order` and `sort`), `quality` (`auto`, `low`, `medium`, `high`, `standard`, `hd`; any other value is a 400), or refused with a 400 naming it: `moderation`, `style`, `input_fidelity`, `lora`, `loras`, `partial_images` above 0, and any field the model does not declare. Limits below are z-image-turbo's; each model's own are in `GET /v1/images/models`.\n", "x-examples": {}, "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 4000, "description": "A text description of the desired image(s). The maximum length is the model's (4000 characters for `z-image-turbo`), counted as Unicode characters rather than bytes." }, "model": { "type": "string", "default": "z-image-turbo", "description": "The model to use for image generation. Defaults to `z-image-turbo`. `GET /v1/images/models` lists the image models currently served. An unknown model returns 404." }, "n": { "type": "integer", "default": 1, "minimum": 1, "maximum": 10, "description": "The number of images to generate. The images in one request are generated together, so changing `n` can change every image, including the first, for the same `seed`." }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ], "description": "How the image comes back. `url` is a presigned link that expires after one hour; `b64_json` is the image inline as base64. The default is `b64_json` on `POST /v1/images` (OpenRouter's SDKs require it) and `url` on `/v1/images/generations` and `/v1/images/edits`." }, "size": { "type": "string", "default": "1024x1024", "example": "1280x720", "description": "`WIDTHxHEIGHT` in pixels, or a resolution label (`1K`, `2K`, ...). For `z-image-turbo` any sides that are multiples of 16, an area from 65,536 to 4,194,304 pixels and a longer side at most 4 times the shorter (so `768x768` works and `1000x1000` is a 400). `auto` is the same as leaving it out. An `aspect_ratio` or `resolution` beside an explicit size must agree with it.\n" }, "width": { "type": "integer", "deprecated": true, "description": "Legacy spelling of `size`, kept because this API once documented it as ignored. Needs `height` and means `size` `\"{width}x{height}\"` under the same rules; a 400 if it disagrees with a `size` sent beside it. Use `size`." }, "height": { "type": "integer", "deprecated": true, "description": "See `width`." }, "aspect_ratio": { "type": "string", "example": "16:9", "description": "One of the model's aspect ratios (`GET /v1/images/models`). With `resolution`, or alone at the model's default resolution, it picks the size." }, "resolution": { "type": "string", "example": "1K", "description": "One of the model's resolutions (`512`, `768`, `1K`, `1.5K`, `2K` for `z-image-turbo`; `4K` is a 400)." }, "seed": { "type": "integer", "format": "int64", "minimum": -9223372036854775808, "maximum": 9223372036854775807, "description": "Random seed. Must be an integer; fractional values are rejected rather than rounded. When omitted, each request uses a random seed.\n\nRepeating a request with the same seed and the same value for every other field, including `n` and `size`, returns the same images from the same model version on the same hardware. A model or engine update can change the images a seed produces, and replicas on different GPUs can differ in the last bits.\n" }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": "png" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "The encoder quality for `jpeg` and `webp`, the compression level for `png`. The engine's own default applies when omitted." }, "background": { "type": "string", "enum": [ "auto", "opaque", "transparent" ], "default": "auto", "description": "`auto` and `opaque` give an opaque image. `transparent` only works on a model whose spec supports it (it also needs `output_format` `png` or `webp`); on `z-image-turbo` it is a 400." }, "input_references": { "type": "array", "description": "OpenRouter's reference images, for a model with reference editing (`z-image-turbo` has none, so it is a 400 naming this field). Each is `{\"type\": \"image_url\", \"image_url\": {\"url\": \"\"}}`. The gateway fetches an https URL itself.", "items": { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "steps": { "type": "integer", "minimum": 1, "maximum": 50, "description": "The number of denoising steps (`z-image-turbo`: 1 to 50, default 8). Generation time grows roughly linearly with steps. Also accepted as `num_inference_steps`, and under `provider.options` (see `provider`).\n\nFor `z-image-turbo` the last step of the schedule lands at zero noise and does not change the image, so `N` steps apply `N - 1` denoising updates. The default of 8 applies 7; 9 matches the 8 updates in the upstream Z-Image-Turbo reference.\n" }, "num_inference_steps": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Alias of `steps`." }, "guidance_scale": { "type": "number", "format": "float", "minimum": 0, "maximum": 20, "description": "Classifier-free guidance strength. When omitted, the model's default is used: 0 for `z-image-turbo`, which is also the upstream recommendation for Turbo models.\n\n`0` turns guidance off. Values above 0 turn it on, which enables `negative_prompt` and roughly doubles the model work per step. Higher values are not a quality setting for `z-image-turbo`.\n" }, "negative_prompt": { "type": "string", "description": "Text describing what to steer the image away from. It only takes effect when `guidance_scale` is above 0; at the `z-image-turbo` default of 0 it is ignored. It changes the output, but does not guarantee that the described content is absent." }, "provider": { "type": "object", "description": "OpenRouter's provider preferences. The routing fields (`order`, `only`, `ignore`, `sort`, `allow_fallbacks`, ...) are accepted and ignored. `options` carries the model's own settings (`steps`, `guidance_scale`, `negative_prompt`) for clients that cannot add top-level fields. From OpenRouter's SDKs use `options.stealth`: they keep only the slugs on their closed list and drop any other, `vultr` included, without an error. The first form present wins, the top level before any option; a key the model does not declare is a 400 naming its path.\n", "example": { "options": { "stealth": { "steps": 4 } } } }, "stream": { "type": "boolean", "description": "`true` answers `text/event-stream`: one `image_generation.completed` event (see the response), then `[DONE]`. Always base64. Not with `n` above 1." }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 0, "description": "OpenAI's partial image count. Only 0 is accepted; a stream carries the finished image only." }, "user": { "type": "string", "description": "Accepted and ignored." }, "session_id": { "type": "string", "description": "Accepted and ignored." }, "trace": { "type": "object", "description": "Accepted and ignored." } } }, "create-image-response-payload": { "title": "Create Image Response Payload", "type": "object", "x-tags": [ "inference", "image generation", "text-to-image", "response" ], "description": "The answer of all three image routes. With `stream: true` the answer is `text/event-stream` instead: one event `image_generation.completed` whose data is `{\"type\": \"image_generation.completed\", \"b64_json\", \"media_type\", \"created\", \"created_at\", \"size\", \"output_format\", \"background\", \"usage\"}`, then `data: [DONE]`.\n", "x-examples": {}, "required": [ "created", "data", "usage" ], "properties": { "created": { "type": "integer", "description": "The Unix timestamp (in seconds) of when the image was created." }, "data": { "type": "array", "description": "The list of generated images.", "items": { "$ref": "#/components/schemas/image" } }, "size": { "type": "string", "example": "1024x1024", "description": "The size generated." }, "output_format": { "type": "string", "example": "png" }, "background": { "type": "string", "description": "`transparent` only when the model produced a transparent image, otherwise `opaque`.", "example": "opaque" }, "usage": { "$ref": "#/components/schemas/image-usage" } } }, "image": { "title": "Image", "type": "object", "x-tags": [ "image" ], "description": "One generated image: its bytes inline (`b64_json`) or a link (`url`), never both.", "x-examples": {}, "required": [ "media_type" ], "properties": { "b64_json": { "type": "string", "description": "The base64-encoded image, in `output_format`. Present when `response_format` is `b64_json`, which is the default of `POST /v1/images`." }, "url": { "type": "string", "description": "A presigned link to the image. Present when `response_format` is `url`, which is the default of `/v1/images/generations` and `/v1/images/edits`. Expires after one hour. OpenRouter's SDKs require `b64_json`, so do not use links with them." }, "media_type": { "type": "string", "example": "image/png", "description": "The MIME type of the image (`image/png`, `image/jpeg` or `image/webp`)." }, "revised_prompt": { "type": "string", "description": "Only present when the engine really rewrote the prompt." } } }, "image-usage": { "title": "Image Usage", "type": "object", "description": "Always present. Images are not billed in tokens, so the token counts are 0; they are there because OpenRouter's SDKs require all three whenever `usage` is present.", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "cost", "megapixels" ], "properties": { "prompt_tokens": { "type": "integer", "example": 0 }, "completion_tokens": { "type": "integer", "example": 0 }, "total_tokens": { "type": "integer", "example": 0 }, "input_tokens": { "type": "integer", "example": 0, "description": "OpenAI's name for `prompt_tokens`." }, "output_tokens": { "type": "integer", "example": 0, "description": "OpenAI's name for `completion_tokens`." }, "input_tokens_details": { "type": "object", "properties": { "text_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" } } }, "cost": { "type": "number", "description": "Dollars billed for this request. `megapixels` times the model's price per megapixel; 0 for a model with no price.", "example": 0.02097152 }, "megapixels": { "type": "number", "description": "The billed quantity. Output megapixels (width x height / 1,000,000 per image returned), times the model's step scaling where it has one. Reference images and masks are not billed.", "example": 1.048576 } } }, "create-image-edit-multipart-request-payload": { "title": "Create Image Edit Request Payload (multipart)", "type": "object", "description": "OpenAI's multipart edit request, as `images.edit()` sends it. Every other field of the create request is a form field too (`steps`, `guidance_scale`, ... as plain fields; `provider` and `input_references` as JSON strings).", "required": [ "prompt", "image" ], "properties": { "prompt": { "type": "string" }, "model": { "type": "string" }, "image": { "type": "array", "description": "One or more image files. Send them as `image[]` (what the OpenAI SDKs do); PHP keeps only the last of several parts named plainly `image`.", "items": { "type": "string", "format": "binary" } }, "mask": { "type": "string", "format": "binary", "description": "A PNG mask; it needs at least one image." }, "n": { "type": "integer" }, "size": { "type": "string" }, "response_format": { "type": "string", "enum": [ "url", "b64_json" ] }, "output_format": { "type": "string" }, "output_compression": { "type": "integer" }, "background": { "type": "string" }, "seed": { "type": "integer" }, "stream": { "type": "boolean" } } }, "create-image-edit-request-payload": { "title": "Create Image Edit Request Payload (JSON)", "type": "object", "description": "OpenAI's JSON edit request, for a model with reference editing (`z-image-turbo` has none: a 400 naming `images`). It takes every field of the create request as well. `input_references` (OpenRouter's form) works here too.\n", "allOf": [ { "$ref": "#/components/schemas/create-image-request-payload" }, { "type": "object", "properties": { "images": { "type": "array", "description": "The images to edit, at most the model's maximum (10 for `qwen-image-2.1`), 20 MB each. A `file_id` is not supported.", "items": { "type": "object", "required": [ "image_url" ], "properties": { "image_url": { "type": "string", "description": "An https URL (public addresses only; the gateway fetches it) or a base64 data URI." } } } }, "mask": { "type": "object", "description": "A PNG mask for the edit; it needs at least one image.", "properties": { "image_url": { "type": "string" } } } } } ] }, "create-video-request-payload": { "title": "Create Video Request", "type": "object", "required": [ "model", "prompt" ], "description": "A control another video model takes that this model does not have (`guidance_scale`, `negative_prompt`; minimax-h3 is CFG-distilled and has neither) is a 400 with `metadata.error_type` `unsupported_parameter`, and so is `lora` or `loras`. Any other field the model does not read is accepted and listed in the job's `warnings`; the video is made without it.\n", "properties": { "model": { "type": "string", "example": "minimax-h3" }, "prompt": { "type": "string", "maxLength": 7000, "description": "Must be a string (a list or number is a 400)." }, "duration": { "type": "integer", "description": "Seconds of video. minimax-h3 takes 4-15; default 6. A whole number sent as text (`\"8\"`) is accepted." }, "seconds": { "type": "integer", "description": "OpenAI/Sora's name for `duration`; `duration` wins when both are sent." }, "resolution": { "type": "string", "example": "768p" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1", "21:9" ], "default": "16:9" }, "size": { "type": "string", "description": "Width x height; an alternative to `aspect_ratio`, and must agree with it when both are sent.", "enum": [ "1344x768", "768x1344", "1024x768", "768x1024", "768x768", "1536x672" ] }, "frame_images": { "type": "array", "maxItems": 2, "items": { "type": "object", "required": [ "type", "image_url", "frame_type" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "$ref": "#/components/schemas/video-media-url" }, "frame_type": { "type": "string", "enum": [ "first_frame", "last_frame" ] } } } }, "input_references": { "type": "array", "description": "Reference media for the subject, style or sound. Ignored when `frame_images` is sent.", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_url", "video_url", "audio_url" ] }, "image_url": { "$ref": "#/components/schemas/video-media-url" }, "video_url": { "$ref": "#/components/schemas/video-media-url" }, "audio_url": { "$ref": "#/components/schemas/video-media-url" }, "role": { "type": "string", "enum": [ "reference" ], "default": "reference", "description": "`driving` and `control` are reserved for models that support them." } } } }, "input_reference": { "description": "OpenAI/Sora's first frame, as an https URL (or base64 data URI) string or as `{image_url}`. Ignored when `frame_images` is sent. Any other type is a 400.", "oneOf": [ { "type": "string", "example": "https://example.com/first-frame.png" }, { "type": "object", "properties": { "image_url": { "type": "string" } } } ] }, "generate_audio": { "type": "boolean", "default": true, "description": "Strictly `true` or `false` (in `multipart/form-data` the text `true` or `false`); anything else is a 400." }, "seed": { "type": "integer" }, "num_inference_steps": { "type": "integer", "minimum": 4, "maximum": 50, "description": "minimax-h3: the number of denoising steps. Omit it for the Turbo LoRA (4 steps, or 8 with `input_references`); 10 to 50 runs the full base model, which takes longer and bills steps / 6 times the seconds, capped at the next `quality` tier up (see Billing). Sending the Turbo count itself changes nothing. Prefer `quality`. Also accepted under `provider.options` (see `provider`)." }, "quality": { "type": "string", "enum": [ "turbo", "standard", "max", "auto", "low", "medium", "high" ], "description": "minimax-h3: the quality tier, the same in every mode. `turbo` (`auto`, `low`; the default) is the Turbo LoRA at 1x the price; `standard` (`medium`) is 20 base steps at 3x; `max` (`high`) is 40 base steps at 5x. The job stores the tier's own name. Sending `num_inference_steps` too is a 400 unless it is the tier's count. Also accepted under `provider.options` (see `provider`)." }, "start_time_seconds": { "type": "number", "minimum": 0, "description": "minimax-h3: where to start reading each reference video in `input_references`, in seconds. Also accepted under `provider.options` (see `provider`)." }, "callback_url": { "type": "string", "description": "An https URL notified on completion, failure, cancellation and expiry. See `GET /v1/webhooks/secret`." }, "provider": { "type": "object", "description": "OpenRouter's provider preferences. The routing fields (`order`, `only`, `ignore`, `sort`, `allow_fallbacks`, ...) are accepted and ignored. `options` carries the model's own settings (`quality`, `num_inference_steps`, `start_time_seconds` for minimax-h3; `GET /v1/videos/models` lists each model's `allowed_passthrough_parameters`) for clients that cannot add top-level fields. From OpenRouter's SDKs use `options.stealth`: they keep only the slugs on their closed list and drop any other, `vultr` included, without an error. The first form present wins, the top level before any option; a key the model does not declare is a 400 naming its path.\n", "example": { "options": { "stealth": { "quality": "standard" } } } } } }, "video-media-url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An https URL or a base64 data URI." } } }, "create-video-multipart-request-payload": { "title": "Create Video Request (multipart)", "type": "object", "required": [ "model", "prompt" ], "description": "OpenAI/Sora's form. List fields (`frame_images`, `input_references`) may be sent as JSON strings.", "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "seconds": { "type": "string" }, "size": { "type": "string" }, "input_reference": { "type": "string", "format": "binary", "description": "The first frame." }, "generate_audio": { "type": "string", "enum": [ "true", "false" ] }, "callback_url": { "type": "string" } } }, "video-job-payload": { "title": "Video", "type": "object", "required": [ "id", "object", "model", "status", "progress", "created_at", "polling_url" ], "properties": { "id": { "type": "string", "example": "video_3f2a9c1e7b4d5a6c8e0f1a2b" }, "object": { "type": "string", "enum": [ "video" ] }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "queued", "in_progress", "completed", "failed", "cancelled", "expired" ], "description": "OpenAI's SDKs (requests with `X-Stainless-Lang`) see `queued` for `pending`, and `cancelled` and `expired` as `failed` with that reason as `error.code`; everyone else sees the states below.\n\n- `pending`: queued; see `queue_position`.\n- `in_progress`: rendering; see `progress`.\n- `completed`: the video is ready at `unsigned_urls` until `expires_at`. The only billed status.\n- `failed`: see `error`. Not billed.\n- `cancelled`: cancelled with `DELETE /v1/videos/{id}`. Not billed.\n- `expired`: a completed job past its 7-day retention; the video is deleted.\n" }, "progress": { "type": "integer", "description": "Estimated percent complete while rendering." }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer" }, "expires_at": { "type": "integer", "description": "When the video is deleted." }, "polling_url": { "type": "string" }, "seconds": { "type": "string", "description": "The requested duration." }, "size": { "type": "string" }, "queue_position": { "type": "integer", "description": "Jobs ahead of this one for the same model, while `pending`." }, "unsigned_urls": { "type": "array", "description": "Where to download each output (send your API key).", "items": { "type": "string" } }, "output": { "type": "object", "description": "What was rendered.", "properties": { "duration": { "type": "number" }, "fps": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "has_audio": { "type": "boolean" }, "count": { "type": "integer" } } }, "warnings": { "type": "array", "description": "What the request sent that was not read. Always present; an empty list says nothing was ignored.", "items": { "$ref": "#/components/schemas/video-warning" } }, "usage": { "type": "object", "properties": { "cost": { "type": "number", "description": "USD." }, "output_seconds": { "type": "integer", "description": "Seconds of video requested." }, "billed_seconds": { "type": "integer", "description": "Seconds billed at the model's price; more than `output_seconds` for the `standard` (3x) and `max` (5x) quality tiers and for base `num_inference_steps` (steps / 6, capped at the next tier up)." }, "input_image_count": { "type": "integer" }, "input_video_seconds": { "type": "number" }, "input_audio_seconds": { "type": "number" } } }, "error": { "description": "Why a `failed` job failed. A string beside `error_code`; for OpenAI's SDKs an object with `code` and `message`.", "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "payload_too_large", "timeout", "provider_error", "server_error", "cancelled", "expired" ], "description": "The same values as `error_code`, and `cancelled` or `expired` for a job in that state." }, "message": { "type": "string" } } } ] }, "error_code": { "type": "string", "enum": [ "invalid_request", "payload_too_large", "timeout", "provider_error", "server_error" ], "description": "- `invalid_request`: an input could not be used, for example a media URL that could not be fetched or a file of the wrong type. Fix the request before sending it again.\n- `payload_too_large`: a media input was over its size limit.\n- `timeout`: the render took too long.\n- `provider_error`: the render failed or was interrupted on our side. Sending the same request again is safe.\n- `server_error`: the job could not run, for example because its model or API key was removed.\n" } } }, "video-warning": { "title": "Video Warning", "type": "object", "properties": { "code": { "type": "string", "description": "`unknown_parameter`: not a video request field, so it was not read. Codes are open: ignore one you do not know." }, "field": { "type": "string" }, "message": { "type": "string" } } }, "video-list-payload": { "title": "Video List", "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/video-job-payload" } }, "first_id": { "type": "string" }, "last_id": { "type": "string" }, "has_more": { "type": "boolean" } } }, "video-models-payload": { "title": "Video Models", "description": "OpenRouter's `VideoModel` list, `{data: [VideoModel]}`, plus our own fields.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "canonical_slug", "created", "supported_durations", "supported_resolutions", "supported_aspect_ratios", "supported_sizes", "supported_frame_images", "generate_audio", "seed", "upscale_factor", "creativity", "allowed_passthrough_parameters" ], "properties": { "id": { "type": "string" }, "canonical_slug": { "type": "string", "description": "The model id." }, "name": { "type": "string" }, "description": { "type": "string" }, "hugging_face_id": { "type": [ "string", "null" ] }, "created": { "type": "integer" }, "supported_durations": { "type": "array", "items": { "type": "integer" } }, "supported_resolutions": { "type": "array", "items": { "type": "string" } }, "supported_aspect_ratios": { "type": "array", "items": { "type": "string" } }, "supported_sizes": { "type": "array", "items": { "type": "string" } }, "supported_frame_images": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "first_frame", "last_frame" ] } }, "generate_audio": { "type": "boolean", "description": "Whether the model generates audio with the video." }, "generates_audio": { "type": "boolean", "deprecated": true, "description": "The old name of `generate_audio`, with the same value, kept for a deprecation period. Use `generate_audio`." }, "seed": { "type": "boolean", "description": "Whether a `seed` is honoured." }, "upscale_factor": { "type": [ "object", "null" ], "description": "For upscaling models; always null here." }, "creativity": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "For upscaling models; always null here." }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" } }, "pricing_skus": { "type": "object", "description": "USD per output second as strings as the catalog writes them (`\"0.06\"`). `generate_per_second` and `reference_per_second` are the default (Turbo) price; `_per_second` (`standard_per_second`, `max_per_second`) each quality tier's.", "additionalProperties": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "string", "enum": [ "generate", "edit", "extend" ] } }, "inputs": { "type": "object", "description": "For each role, how many of each media type." }, "supported_fps": { "type": "array", "items": { "type": "integer" } }, "frame_grid": { "type": "string", "description": "How duration is rounded to frames, e.g. `17n+5`." }, "quality_tiers": { "type": [ "array", "null" ], "description": "The values of `quality`, null for a model without tiers.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "steps": { "type": [ "integer", "null" ], "description": "The base steps the tier runs; null for the tier that runs each mode's own Turbo schedule." }, "multiplier": { "type": "number", "description": "Billed seconds per output second." }, "aliases": { "type": "array", "items": { "type": "string" } }, "price_per_second": { "type": [ "string", "null" ] } } } } } } } } }, "video-deleted-payload": { "title": "Video Deleted", "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video.deleted" ] }, "deleted": { "type": "boolean" } } }, "create-music-request-payload": { "title": "Create Music Request", "type": "object", "required": [ "model" ], "description": "The fields every music model shares. Each model's entry in `GET /v1/music/models` says which it honours; one it cannot honour is a 400 naming it. `language`, `instrumental`, `input_references`, `source_audio`, `reference_audio`, `regions`, `negative_prompt`, `include` and `adapters` are reserved for models that will honour them and refused today when they ask for something.", "properties": { "model": { "type": "string", "example": "minimax-music3" }, "prompt": { "type": "string", "description": "The style caption (minimax-music3, at most 6,000 characters). Also accepted as `tags`." }, "lyrics": { "type": "string", "description": "The words, with section tags on their own lines (minimax-music3, at most 12,000 characters; required)." }, "duration": { "type": "integer", "description": "Seconds. For minimax-music3 the longest the song may be, 30 to 360 (default 300). Also accepted as `seconds_total`, or `music_length_ms` in milliseconds." }, "n": { "type": "integer", "minimum": 1, "default": 1, "description": "How many songs to make, each from its own seed, up to the model's `outputs.max_n` (minimax-music3, 1)." }, "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "The same request with the same seed makes the same song. Each output reports the seed it used." }, "response_format": { "type": "string", "enum": [ "mp3", "wav", "flac", "opus", "aac", "pcm" ], "default": "mp3", "description": "`pcm` is raw 16-bit little-endian samples with no header; `opus` is in Ogg at 48 kHz. Also accepted as `output_format`, including codec strings such as `mp3_44100_128`, or MiniMax's `audio_setting.format`." }, "sample_rate": { "type": "integer", "enum": [ 8000, 16000, 22050, 24000, 32000, 44100, 48000 ], "description": "Defaults to the model's own (minimax-music3, 32000)." }, "bitrate": { "type": "integer", "enum": [ 32000, 64000, 96000, 128000, 192000, 256000, 320000 ], "description": "Bits per second for `mp3`, `aac` and `opus` (default 256000); ignored with a warning for the other formats." }, "bpm": { "type": "integer", "description": "Tempo. Advisory on minimax-music3 (30 to 300), written into the caption." }, "key": { "type": "string", "description": "A note with an optional accidental and scale, such as `C major`, `F# minor` or `Eb`. Advisory on minimax-music3." }, "time_signature": { "type": "string", "description": "Beats over a note value, such as `4/4`, `3/4` or `6/8`. Advisory on minimax-music3." }, "task": { "type": "string", "default": "text2music", "description": "What to do, from the model's `tasks`. minimax-music3 serves `text2music`." }, "callback_url": { "type": "string", "description": "An https URL notified on completion, failure, cancellation and expiry. See `GET /v1/webhooks/secret`." }, "provider": { "type": "object", "description": "OpenRouter's provider preferences. The routing fields (`order`, `only`, `ignore`, `sort`, `allow_fallbacks`, ...) are accepted and ignored. `options` carries the model's own settings (each model's `allowed_passthrough_parameters`; minimax-music3 has none) for clients that cannot add top-level fields. From OpenRouter's SDKs use `options.stealth`: they keep only the slugs on their closed list and drop any other, `vultr` included, without an error. The first form present wins, the top level before any option; a key the model does not declare is a 400 naming its path.\n" } } }, "music-job-payload": { "title": "Music Job", "type": "object", "required": [ "id", "object", "model", "task", "status", "progress", "created_at", "polling_url", "warnings" ], "description": "Fields that do not apply to the job's state are left out.", "properties": { "id": { "type": "string", "example": "music_0123456789abcdef01234567" }, "object": { "type": "string", "enum": [ "music" ] }, "model": { "type": "string" }, "task": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled", "expired" ] }, "progress": { "type": "integer", "description": "Estimated percent while rendering." }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer" }, "expires_at": { "type": "integer", "description": "When the audio is deleted (7 days after completion)." }, "polling_url": { "type": "string" }, "stream_url": { "type": "string", "description": "While `pending` or `in_progress` on a model that streams (`streaming.progressive`): the song as WAV as it renders, from its first byte (`GET /v1/music/{id}/stream`; `?index=N` for another output). Send your API key." }, "queue_position": { "type": "integer", "description": "Jobs ahead of this one for the same model, while `pending`." }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/music-output" } }, "unsigned_urls": { "type": "array", "description": "`outputs[N]` is at `unsigned_urls[N]`; send your API key.", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/music-warning" } }, "usage": { "type": "object", "properties": { "cost": { "type": "number", "description": "Dollars, `billed_seconds` times the model's price." }, "duration_seconds": { "type": "number" }, "billed_seconds": { "type": "integer" }, "outputs": { "type": "integer" } } }, "error": { "type": "string", "description": "The failure, when `failed`." }, "error_code": { "type": "string" } } }, "music-output": { "title": "Music Output", "type": "object", "description": "One artifact of the job. `kind` and `role` are open strings; ignore values you do not know.", "properties": { "index": { "type": "integer", "description": "Its place in `outputs` and in `unsigned_urls`; `GET /v1/music/{id}/content?index=N`." }, "kind": { "type": "string", "example": "audio" }, "role": { "type": "string", "example": "mix", "description": "What the audio is; `mix` is the whole song." }, "candidate": { "type": "integer", "description": "Which of the `n` songs it belongs to." }, "content_type": { "type": "string", "example": "audio/mpeg" }, "format": { "type": "string", "example": "mp3" }, "duration_seconds": { "type": "number", "example": 187.4 }, "sample_rate": { "type": "integer", "example": 32000 }, "channels": { "type": "integer", "example": 2 }, "seed": { "type": "integer" }, "metadata": { "type": "object" } } }, "music-warning": { "title": "Music Warning", "type": "object", "properties": { "code": { "type": "string", "description": "`advisory_control` (a hint the model may not follow exactly), `ignored_parameter` (accepted and not used) or `unknown_parameter` (not a music request field)." }, "field": { "type": "string" }, "message": { "type": "string" } } }, "music-list-payload": { "title": "Music List", "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/music-job-payload" } }, "first_id": { "type": "string" }, "last_id": { "type": "string" }, "has_more": { "type": "boolean" } } }, "music-models-payload": { "title": "Music Models", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "canonical_slug": { "type": "string" }, "hugging_face_id": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created": { "type": "integer" }, "output_modalities": { "type": "array", "items": { "type": "string" } }, "interaction": { "type": "string", "description": "`job`: submit and poll." }, "tasks": { "type": "array", "description": "What the model does, each with the input roles it requires (`{role, min, max}`) and the settings it reads.", "items": { "type": "object" } }, "duration": { "type": "object", "description": "`{semantics, min, max, default}` in seconds; `semantics` is `exact` (the song is that long) or `max` (the song may end sooner)." }, "lyrics": { "type": "string", "enum": [ "required", "optional" ] }, "prompt_max_length": { "type": "integer" }, "controls": { "type": "object", "description": "`bpm`, `key`, `time_signature` the model takes, each `{mode}`: `native` (enforced) or `advisory` (a hint written into the caption)." }, "outputs": { "type": "object", "description": "`max_n`, `kinds`, `roles`, `formats`, `default_format`, `sample_rates`, `channels`." }, "seed": { "type": "boolean" }, "adapters": { "type": "boolean" }, "streaming": { "type": "object", "description": "`progressive`: a job on this model has a `stream_url` to hear the song as it renders.", "properties": { "progressive": { "type": "boolean" } } }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" } }, "parameters": { "type": "object" }, "attribution": { "type": [ "string", "null" ], "description": "The name the model's license asks to be shown beside it." }, "pricing_skus": { "type": "object", "description": "`{generate_per_second}` in dollars per second of audio produced; `{}` for an unpriced model." } } } } } }, "music-deleted-payload": { "title": "Music Deleted", "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music.deleted" ] }, "deleted": { "type": "boolean" } } }, "webhook-secret-payload": { "title": "Webhook Secret", "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_secret" ] }, "secret": { "type": "string", "example": "whsec_9a1c..." }, "created_at": { "type": "integer" }, "rotated_at": { "type": [ "integer", "null" ], "description": "When the secret was last rotated, in Unix seconds; null until the first rotation." }, "previous_secret_valid_until": { "type": [ "integer", "null" ], "description": "Until when the previous secret still signs beside this one, in Unix seconds; null outside a rotation." } } }, "models-response-payload": { "title": "List Models Response Payload", "type": "object", "x-tags": [ "inference", "models", "response" ], "description": "List Models Response Payload", "x-examples": {}, "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Live, public database models in OpenRouter ModelDocumentV2 format, sorted by ID. The X-Vultr-Model-Type header can limit this list to chat models.", "items": { "$ref": "#/components/schemas/openrouter-model-document" } } } }, "openrouter-model-document": { "title": "OpenRouter Model Document", "type": "object", "description": "A live model catalog entry. Modalities and pricing vary by model type.", "required": [ "schema_version", "id", "name", "created", "description", "datacenters", "input_modalities", "output_modalities" ], "properties": { "schema_version": { "type": "string", "enum": [ "2.4" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "integer", "description": "Unix timestamp in seconds." }, "description": { "type": "string" }, "datacenters": { "type": "array", "description": "Where the model runs, from the regions llm-router lists for it (`sjc` for Whisper, `sea` for the GLM and MiniMax M3 rows, `atl` for most others). Empty when the router names none.", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "region": { "type": "string" } } } }, "hugging_face_id": { "type": "string" }, "quantization": { "type": "string" }, "input_modalities": { "type": "array", "items": { "$ref": "#/components/schemas/openrouter-model-modality" } }, "output_modalities": { "type": "array", "items": { "$ref": "#/components/schemas/openrouter-model-modality" } }, "reasoning": { "type": "object", "deprecated": true, "description": "Present for reasoning models. Outside OpenRouter's provider schema and kept only for `@vultr/model-catalog` 0.0.2 and earlier; read the `reasoning` and `reasoning_effort` entries of the text output's `supported_parameters` instead. To be removed (RND-258).", "properties": { "mandatory": { "type": "boolean" }, "default_effort": { "type": [ "string", "null" ] }, "default_enabled": { "type": [ "boolean", "null" ] }, "supported_efforts": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "ultra", "max", "xhigh", "high", "medium", "low", "minimal" ] } }, "supports_max_tokens": { "type": "boolean" } } } } }, "openrouter-model-modality": { "title": "OpenRouter Model Modality", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "file", "audio", "video", "speech", "transcription", "embeddings", "rerank", "decisions" ] }, "supported_inputs": { "type": "object", "description": "Modality-specific limits and accepted sources. A chat model's `file` input lists the document formats it reads (`formats`), the `sources` (`url`, `base64`) and `max_content_size_bytes`; the gateway converts a document to text before the model reads it, so every chat model has one." }, "supported_parameters": { "type": "object", "description": "Modality-specific request parameters and limits." }, "streaming": { "type": "boolean" }, "max_length": { "type": "object", "properties": { "value": { "type": "integer" }, "unit": { "type": "string" } } }, "pricing": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "unit": { "type": "string" }, "cost_usd": { "type": "string" } } } } } }, "anthropic-models-response-payload": { "title": "Anthropic List Models Response Payload", "type": "object", "required": [ "data", "first_id", "has_more", "last_id" ], "x-tags": [ "messages", "anthropic", "models", "response" ], "description": "Response payload for listing models in Anthropic format.", "x-examples": {}, "properties": { "data": { "type": "array", "description": "A list of models available for the Messages API.", "items": { "$ref": "#/components/schemas/anthropic-model-info" } }, "first_id": { "type": [ "string", "null" ], "description": "First ID in the data list. Can be used as the `before_id` for the previous page." }, "has_more": { "type": "boolean", "description": "Whether there are more results in the requested page direction." }, "last_id": { "type": [ "string", "null" ], "description": "Last ID in the data list. Can be used as the `after_id` for the next page." } } }, "anthropic-model-info": { "title": "Anthropic Model Info", "type": "object", "required": [ "id", "type", "display_name", "created_at", "max_input_tokens", "max_tokens", "capabilities" ], "x-tags": [ "messages", "anthropic", "models" ], "description": "Model information in Anthropic format.", "x-examples": {}, "properties": { "id": { "type": "string", "description": "Unique model identifier. Each chat model also has a `vultr/claude-code/` alias for Claude Code discovery; both IDs route to the same model." }, "type": { "type": "string", "enum": [ "model" ], "description": "Object type. Always `model`." }, "display_name": { "type": "string", "description": "A human-readable name for the model." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string representing when the model was added to the catalog." }, "max_input_tokens": { "type": [ "integer", "null" ], "description": "Maximum input context window size in tokens." }, "max_tokens": { "type": [ "integer", "null" ], "description": "Maximum value for the max_tokens parameter when using this model." }, "capabilities": { "type": [ "object", "null" ], "description": "Model capability information.", "properties": { "batch": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "citations": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "code_execution": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "image_input": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "pdf_input": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "structured_outputs": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "thinking": { "type": "object", "properties": { "supported": { "type": "boolean" }, "types": { "type": "object", "properties": { "adaptive": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "enabled": { "type": "object", "properties": { "supported": { "type": "boolean" } } } } } } }, "effort": { "type": "object", "properties": { "supported": { "type": "boolean" }, "high": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "low": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "max": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "medium": { "type": "object", "properties": { "supported": { "type": "boolean" } } } } } } } } }, "typesafe-models-response-payload": { "title": "TypeSafe Model List", "description": "TypeSafe's GET /v1/models response, served to TypeSafe's SDKs (X-TypeSafe-SDK): the decision models usable with POST /v1/systemone.", "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "release_date" ], "properties": { "name": { "type": "string", "description": "The model's name, as `model` in a POST /v1/systemone request.", "example": "mica-v0.1-4b" }, "description": { "type": "string" }, "release_date": { "type": "string", "format": "date", "example": "2026-09-27" } } } } } }, "models-count-response": { "title": "Models Count Response", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "example": 12 } } } } }, "openrouter-public-model-response": { "title": "OpenRouter Public Model Response", "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/openrouter-public-model" } } }, "all-models-response-payload": { "title": "List All Models Response Payload", "type": "object", "x-tags": [ "inference", "audio generation", "speech", "text-to-speech", "image generation", "text-to-image", "models", "response" ], "description": "List All Models Response Payload", "x-examples": {}, "properties": { "chat": { "type": "array", "description": "A list of models for use in chat completion.", "items": { "$ref": "#/components/schemas/model" } }, "audio": { "type": "array", "description": "A list of models for use in text-to-speech inference.", "items": { "$ref": "#/components/schemas/text-to-speech-model" } }, "image": { "type": "array", "description": "A list of models currently served for image generation.", "items": { "$ref": "#/components/schemas/text-to-image-model" } } } }, "model": { "title": "Model", "type": "object", "x-tags": [ "inference", "model" ], "description": "Model", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique model identifier that can be used in inference API endpoints." }, "created": { "type": "integer", "description": "The Unix timestamp of when the model was added to the inference API." }, "object": { "type": "string", "description": "The type of object represented in the response, which is always `model`." }, "owned_by": { "type": "string", "description": "The organization that owns the model." }, "features": { "type": "array", "description": "A list of features supported by the model.", "items": { "type": "string" } } } }, "text-to-image-model": { "title": "Text-to-Image Model", "type": "object", "x-tags": [ "inference", "image generation", "text-to-image", "model" ], "description": "Text-to-Image Model", "x-examples": {}, "properties": { "id": { "type": "string", "description": "The unique model identifier that can be used in inference API endpoints." }, "created": { "type": "integer", "description": "The Unix timestamp of when the model was added to the inference API." }, "price": { "type": "number", "format": "float", "description": "The price per megapixel for using the model." } } }, "usage-response-payload": { "title": "Get Usage Response Payload", "type": "object", "x-tags": [ "token", "usage", "response" ], "description": "Get Usage Response Payload", "x-examples": {}, "properties": { "usage": { "type": "object", "properties": { "current_month": { "$ref": "#/components/schemas/usage-object" }, "previous_month": { "$ref": "#/components/schemas/usage-object" } } } } }, "usage-object": { "title": "Inference Usage", "type": "object", "x-tags": [ "inference", "usage", "tokens", "tts", "speech", "text-to-speech" ], "description": "Object containing usage values for the given month.", "x-examples": {}, "properties": { "chat_usage": { "type": "array", "description": "The per-model breakdown of chat completion usage in this monthly period.", "items": { "$ref": "#/components/schemas/chat-usage-object" } }, "tts": { "type": "integer", "description": "The total number of text-to-speech input characters used this period with the standard HD model." }, "tts_sm": { "type": "integer", "description": "The total number of text-to-speech input characters used this period with the basic model." }, "image": { "type": "number", "format": "float", "description": "The total number of megapixels generated during this period with a standard model." }, "image_sm": { "type": "number", "format": "float", "description": "The total number of megapixels generated during this period with a small model." }, "chat": { "type": "integer", "description": "The total number of chat completion tokens used in this monthly period.", "deprecated": true }, "chat_input": { "type": "integer", "description": "The total number of input tokens used in this monthly period.", "deprecated": true } } }, "chat-usage-object": { "title": "Inference Chat Usage", "type": "object", "x-tags": [ "inference", "usage", "tokens", "chat" ], "description": "Object containing per-model chat usage values for the given month.", "x-examples": {}, "properties": { "model": { "type": "string", "description": "The name of the model used during this period." }, "output_tokens": { "type": "integer", "description": "The total number of output tokens used with this model in this monthly period." }, "input_tokens": { "type": "integer", "description": "The total number of input tokens used with this model in this monthly period." } } }, "cluster-status-response-payload": { "title": "Health Check Get Cluster Status Response Payload", "type": "object", "x-tags": [ "health", "health check", "status", "cluster status", "response" ], "description": "Health Check Get Cluster Status Response Payload", "x-examples": {}, "properties": { "status": { "type": "string", "description": "The current status of the inference cluster." } } }, "cluster-status-response-error-payload": { "title": "Health Check Get Cluster Status Error Response Payload", "type": "object", "x-tags": [ "health", "health check", "status", "cluster status", "response", "error" ], "description": "Health Check Get Cluster Status Error Response Payload", "x-examples": {}, "properties": { "status": { "type": "string", "description": "The current status of the inference cluster." }, "message": { "type": "string", "description": "A more detailed error message regarding why the health check failed." } } } }, "responses": { "unauthorized": { "description": "The API key is missing, unknown or not active. Send it as `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" }, "example": { "error": { "code": 401, "message": "Invalid API key", "type": "auth_error", "metadata": { "error_type": "authentication" } } } } } }, "models-unavailable": { "description": "The list of models being served could not be read, so the request's model could not be resolved. Retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "catalog-unavailable": { "description": "The model catalog cannot be read right now. Retry shortly; an empty list is never sent in its place.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } }, "rate-limited": { "description": "Too many requests for this model from your subscription in the last minute, or too many running at once. Wait for `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-payload" } } } } }, "parameters": { "response-id": { "name": "id", "in": "path", "required": true, "description": "A response ID, `resp_` followed by hex characters. Responses are not stored, so no ID resolves.", "schema": { "type": "string" } }, "vector-store-id": { "name": "id", "in": "path", "required": true, "description": "The ID of the vector store collection.", "schema": { "type": "string" } }, "vector-store-item-id": { "name": "itemid", "in": "path", "required": true, "description": "The ID of the vector store collection item.", "schema": { "type": "string" } }, "vector-store-file-id": { "name": "fileid", "in": "path", "required": true, "description": "The ID of the vector store collection file.", "schema": { "type": "string" } }, "video-id": { "name": "id", "in": "path", "required": true, "description": "The video job's ID, `video_` followed by 24 hex characters.", "schema": { "type": "string" } }, "music-id": { "name": "id", "in": "path", "required": true, "description": "The music job's ID, `music_` followed by 24 hex characters.", "schema": { "type": "string" } }, "model-id": { "name": "id", "in": "path", "required": true, "description": "The model id, as `GET /v1/models` lists it. An id with a slash is sent as it is (`zai-org/GLM-5`, which the path takes as more segments) or percent-encoded (`zai-org%2FGLM-5`).", "schema": { "type": "string" } } }, "securitySchemes": { "APIKey": { "type": "http", "scheme": "bearer", "description": "The Vultr Inference API v1 uses API keys for authentication. You can manage your API keys in the [Vultr console](https://console.vultr.com/inference/). Please do not share API keys publicly, or embed them in client-side code.\n\nTo authenticate a request, send your API Key as a bearer token in the request header.\n\n### Authentication Example\n\n curl \"https://api.vultrinference.com/v1/health\" \\\n -H \"Authorization: Bearer ${VULTR_API_KEY}\"\n\nMost API routes require a bearer token. The public `/v1/models` route does not. Use HTTPS for API requests." } } } }