{ "openapi": "3.1.0", "info": { "title": "AI Models Router API", "version": "1.1.0", "summary": "One OpenAI-compatible API for many open-weight AI models, paid from prepaid credits.", "description": "OpenAI Chat Completions-compatible, plus the OpenAI Responses API (Codex) and the Anthropic Messages API (Claude Code).\nPoint any OpenAI SDK at the server URL below and use a model id from GET /models. Anthropic SDKs and Claude Code\nuse https://api.aimodelsrouter.ai (without /v1) as their base URL.\n\n**Billing.** Each request first holds its maximum possible cost from your balance, then settles at the actual cost\n(`usage.cost`, USD). **Failed requests are not charged:** if every route fails, the model rejects the request, or\nyou hit a limit before any output, you pay nothing. If a stream breaks after output started, you pay for the prompt\nand the output that reached you, never more than the hold.\n\n**Errors** carry a stable `type` and, on the chat and account endpoints, `retryable` and `charged`. The Responses and\nMessages endpoints answer in those APIs' own envelopes.\n\nDocs: https://aimodelsrouter.ai/docs · Status: https://aimodelsrouter.ai/status", "termsOfService": "https://aimodelsrouter.ai/legal/terms", "contact": { "name": "AI Models Router support", "email": "support@aimodelsrouter.ai", "url": "https://aimodelsrouter.ai/docs" } }, "externalDocs": { "description": "Documentation", "url": "https://aimodelsrouter.ai/docs" }, "servers": [ { "url": "https://api.aimodelsrouter.ai/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Models", "description": "The public catalog: ids, context sizes, capabilities and prices." }, { "name": "Chat", "description": "OpenAI-compatible chat completions, streamed or not." }, { "name": "Responses", "description": "The OpenAI Responses API (Codex), stateless: nothing is stored." }, { "name": "Messages", "description": "The Anthropic Messages API (Claude Code, Anthropic SDKs)." }, { "name": "Account", "description": "Your key's limits and usage, and per-request metadata." } ], "paths": { "/models": { "get": { "tags": [ "Models" ], "operationId": "listModels", "summary": "List models", "description": "Every publicly available model. No authentication needed.", "security": [], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } } } }, "/models/{model_id}": { "get": { "tags": [ "Models" ], "operationId": "getModel", "summary": "Get a model", "description": "One model. Ids contain a slash (author/model); send it as is or URL-encoded. A retired id that is an alias answers with the model that serves it and the header `X-AMR-Model-Alias`.", "security": [], "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "deepseek/deepseek-v4-flash" } ], "responses": { "200": { "description": "The model.", "headers": { "X-AMR-Model-Alias": { "description": "The retired id you sent, when it is an alias.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/chat/completions": { "post": { "tags": [ "Chat" ], "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "The OpenAI Chat Completions request. With `stream: true` the response is server-sent events: `data: {chunk}` lines, `: keepalive` comments while waiting, a final chunk with `usage` (always sent, whatever `stream_options` says), then `data: [DONE]`. An error after the stream started arrives as a chunk with `finish_reason: \"error\"` and an `error` object, followed by the usage chunk; a failure before any output, once the stream has opened, is one `data: {\"error\": …}` event. A non-streamed request still running after 80 s gets status 200 with whitespace keepalives before the body; an error after that point arrives as this API's error body with status 200.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "The completion, or (with `stream: true`) a stream of chunks.", "headers": { "X-Generation-Id": { "description": "The request's id (gen-…), for GET /generation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletion" }, { "$ref": "#/components/schemas/ErrorBody" } ] } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events; each `data:` line is a ChatCompletionChunk (or an error body), then `[DONE]`." }, "x-event-data-schema": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionChunk" }, { "$ref": "#/components/schemas/ErrorBody" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/Timeout" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/responses": { "post": { "tags": [ "Responses" ], "operationId": "createResponse", "summary": "Create a response (OpenAI Responses API)", "description": "A translation layer over chat completions: the same holds, limits, failover, billing and keepalives. Stateless: `previous_response_id`, `conversation`, `item_reference`, `background` and `prompt` get 400 (send the full input; Codex does with `store: false`), and responses say `store: false`. Hosted tools (`web_search`, `file_search`, …) get 400. With `stream: true` every event has an `event:` line and a `data:` JSON with `type` and `sequence_number`; keepalives are `: keepalive` comments. A failure after the stream started is an `error` event, then `response.failed` with the usage charged for what was sent. A non-streamed request still running after 80 s gets status 200 with whitespace keepalives before the body; an error after that point arrives as this API's error body with status 200.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "200": { "description": "The response, or (with `stream: true`) its events.", "headers": { "X-Generation-Id": { "description": "The request's id (gen-…), for GET /generation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Response" }, { "$ref": "#/components/schemas/ResponsesErrorBody" } ] } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events (`event:` + `data:`); see ResponseStreamEvent." }, "x-event-data-schema": { "$ref": "#/components/schemas/ResponseStreamEvent" } } } }, "400": { "$ref": "#/components/responses/ResponsesBadRequest" }, "401": { "$ref": "#/components/responses/ResponsesUnauthorized" }, "402": { "$ref": "#/components/responses/ResponsesPaymentRequired" }, "403": { "$ref": "#/components/responses/ResponsesForbidden" }, "404": { "$ref": "#/components/responses/ResponsesNotFound" }, "408": { "$ref": "#/components/responses/ResponsesTimeout" }, "413": { "$ref": "#/components/responses/ResponsesPayloadTooLarge" }, "429": { "$ref": "#/components/responses/ResponsesTooManyRequests" }, "500": { "$ref": "#/components/responses/ResponsesInternalError" }, "503": { "$ref": "#/components/responses/ResponsesUnavailable" } } } }, "/messages": { "post": { "tags": [ "Messages" ], "operationId": "createMessage", "summary": "Create a message (Anthropic Messages API)", "description": "For Claude Code and Anthropic SDKs: set their base URL to the API host without /v1 and the model to one of our ids (a `claude-…` id gets 404 not_found_error naming the variables to set). A translation layer over chat completions: the same holds, limits, failover and billing. `anthropic-version` and `anthropic-beta` are accepted and ignored; Claude Code's startup check `GET|HEAD /api/hello` (outside /v1) answers 200. Thinking comes back only when `thinking.type` is `enabled` or `adaptive`. Streams send `message_start`, `content_block_start/delta/stop`, `message_delta` (with the real usage and cost) and `message_stop`; keepalives are `ping` events, and a failure after the stream started is an `error` event (no message_stop). A non-streamed request still running after 80 s gets status 200 with whitespace keepalives before the body; an error after that point arrives as this API's error body with status 200.", "security": [ { "anthropicApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AnthropicVersion" }, { "$ref": "#/components/parameters/AnthropicBeta" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "200": { "description": "The message, or (with `stream: true`) its events.", "headers": { "X-Generation-Id": { "description": "The request's id (gen-…), for GET /generation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/MessagesErrorBody" } ] } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events (`event:` + `data:`); see MessageStreamEvent." }, "x-event-data-schema": { "$ref": "#/components/schemas/MessageStreamEvent" } } } }, "400": { "$ref": "#/components/responses/MessagesBadRequest" }, "401": { "$ref": "#/components/responses/MessagesUnauthorized" }, "402": { "$ref": "#/components/responses/MessagesPaymentRequired" }, "403": { "$ref": "#/components/responses/MessagesForbidden" }, "404": { "$ref": "#/components/responses/MessagesNotFound" }, "408": { "$ref": "#/components/responses/MessagesTimeout" }, "413": { "$ref": "#/components/responses/MessagesPayloadTooLarge" }, "429": { "$ref": "#/components/responses/MessagesTooManyRequests" }, "500": { "$ref": "#/components/responses/MessagesInternalError" }, "503": { "$ref": "#/components/responses/MessagesUnavailable" } } } }, "/messages/count_tokens": { "post": { "tags": [ "Messages" ], "operationId": "countMessageTokens", "summary": "Count input tokens (estimate)", "description": "The Messages body without `max_tokens`. An estimate (about 4 UTF-8 bytes per token, 1,000 per image), free; nothing is sent to a model.", "security": [ { "anthropicApiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AnthropicVersion" }, { "$ref": "#/components/parameters/AnthropicBeta" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesCountTokensRequest" } } } }, "responses": { "200": { "description": "The estimate.", "content": { "application/json": { "schema": { "type": "object", "required": [ "input_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Estimated prompt tokens." } } } } } }, "400": { "$ref": "#/components/responses/MessagesBadRequest" }, "401": { "$ref": "#/components/responses/MessagesUnauthorized" }, "404": { "$ref": "#/components/responses/MessagesNotFound" }, "413": { "$ref": "#/components/responses/MessagesPayloadTooLarge" }, "429": { "$ref": "#/components/responses/MessagesTooManyRequests" } } } }, "/key": { "get": { "tags": [ "Account" ], "operationId": "getKey", "summary": "Current key: limits, usage and what it may still spend", "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KeyInfo" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/generation": { "get": { "tags": [ "Account" ], "operationId": "getGeneration", "summary": "Metadata for one of your requests", "description": "Model, status, tokens, cost and timing for a request made by your account. Prompts and completions are never stored.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^gen-" }, "example": "gen-0b1c…" } ], "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Generation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/generations": { "get": { "tags": [ "Account" ], "operationId": "listGenerations", "summary": "Your recent requests, newest first", "description": "Metadata only, never prompts or outputs; pending requests included. Page with `before` = the previous page's `next_before`.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "schema": { "type": "string", "pattern": "^gen-" }, "description": "A gen-… id of yours: return requests older than it." }, { "$ref": "#/components/parameters/Scope" } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/usage": { "get": { "tags": [ "Account" ], "operationId": "getUsage", "summary": "Cost, tokens and requests per UTC day or per model", "description": "Settled requests only, counted on the UTC day they completed (today's cost equals GET /key usage_daily). Days or models without requests are omitted. Sums are taken in integer micro-USD and converted once.", "parameters": [ { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "day", "model" ], "default": "day" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "First UTC date, included (default: 29 days before `to`)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Last UTC date, included (default: today). At most 367 days from `from`." }, { "$ref": "#/components/parameters/Scope" } ], "responses": { "200": { "description": "The report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk-amr-v1-…", "description": "An API key from https://aimodelsrouter.ai/dashboard/keys, sent as `Authorization: Bearer sk-amr-v1-…`." }, "anthropicApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "The same API key, as Anthropic clients send it (Messages endpoints only)." } }, "parameters": { "AnthropicVersion": { "name": "anthropic-version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Accepted and ignored." }, "AnthropicBeta": { "name": "anthropic-beta", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Accepted and ignored." }, "Scope": { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "key", "account" ], "default": "key" }, "description": "`key`: this API key's requests; `account`: every key of the account." } }, "responses": { "BadRequest": { "description": "Invalid request, a price ceiling (max_price) below the model's price, or zdr with no zero-retention route. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "400_invalid_request": { "summary": "Malformed body, missing model or messages, or a parameter the model rejected.", "value": { "error": { "message": "…", "type": "invalid_request", "code": 400, "retryable": false, "charged": false } } }, "400_max_price_exceeded": { "summary": "The model's price is above your max_price (prompt or completion, USD per 1M tokens). Refused before anything is reserved; error.pricing has the model's prices.", "value": { "error": { "message": "…", "type": "max_price_exceeded", "code": 400, "retryable": false, "charged": false } } }, "400_zdr_unavailable": { "summary": "You sent zdr: true and the model has no zero-data-retention route.", "value": { "error": { "message": "…", "type": "zdr_unavailable", "code": 400, "retryable": false, "charged": false } } } } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "401_invalid_api_key": { "summary": "Missing, unknown, disabled, revoked or expired key.", "value": { "error": { "message": "…", "type": "invalid_api_key", "code": 401, "retryable": false, "charged": false } } } } } } }, "PaymentRequired": { "description": "Not enough credit or key spending limit for the request's hold, or a model available only after the account's first credit purchase. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "402_insufficient_credits": { "summary": "Available balance is below the request's hold (for a stream, its first slice). Mid-stream, it arrives as an error event when the balance or key limit can't cover more output; you pay only for what was sent.", "value": { "error": { "message": "…", "type": "insufficient_credits", "code": 402, "retryable": false, "charged": false } } }, "402_key_limit_exceeded": { "summary": "The request's maximum possible cost (prompt plus max_tokens) is more than one of the key's spending limits has left. error.limit says which: total, daily or monthly; daily and monthly add error.resets_at. Mid-stream, it arrives as an error event.", "value": { "error": { "message": "…", "type": "key_limit_exceeded", "code": 402, "retryable": false, "charged": false } } }, "402_purchase_required": { "summary": "The model is available after your first credit purchase (its supplier limits daily use), and this account has not bought credit yet: the sign-up credit alone does not unlock it. Refused before anything is reserved; the message names a model you can use now. GET /models shows requires_purchase: true for these models.", "value": { "error": { "message": "…", "type": "purchase_required", "code": 402, "retryable": false, "charged": false } } } } } } }, "Forbidden": { "description": "The account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "403_account_suspended": { "summary": "The account is suspended.", "value": { "error": { "message": "…", "type": "account_suspended", "code": 403, "retryable": false, "charged": false } } } } } } }, "NotFound": { "description": "Unknown model, path or generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "404_model_not_found": { "summary": "Unknown or not publicly available model.", "value": { "error": { "message": "…", "type": "model_not_found", "code": 404, "retryable": false, "charged": false } } }, "404_not_found": { "summary": "Unknown path (only the endpoints in this reference exist), or a generation id that is not yours.", "value": { "error": { "message": "…", "type": "not_found", "code": 404, "retryable": false, "charged": false } } } } } } }, "Timeout": { "description": "The model did not respond in time. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "408_timeout": { "summary": "The model did not respond in time and nothing was charged.", "value": { "error": { "message": "…", "type": "timeout", "code": 408, "retryable": true, "charged": false } } } } } } }, "PayloadTooLarge": { "description": "The body is larger than 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "413_invalid_request": { "summary": "Request body larger than 32 MiB.", "value": { "error": { "message": "…", "type": "invalid_request", "code": 413, "retryable": false, "charged": false } } } } } } }, "TooManyRequests": { "description": "A rate, concurrency, daily token or model-capacity limit. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "429_rate_limited": { "summary": "Per-key request rate reached (600 per minute by default). Retry-After header is set.", "value": { "error": { "message": "…", "type": "rate_limited", "code": 429, "retryable": true, "charged": false } } }, "429_concurrency_limited": { "summary": "The key already has as many requests running as its limit allows. Retry-After: 1.", "value": { "error": { "message": "…", "type": "concurrency_limited", "code": 429, "retryable": true, "charged": false } } }, "429_key_token_limit_exceeded": { "summary": "The key used its daily token limit. Retry-After and error.resets_at give the reset (00:00 UTC).", "value": { "error": { "message": "…", "type": "key_token_limit_exceeded", "code": 429, "retryable": false, "charged": false } } }, "429_model_capacity": { "summary": "The model is at capacity right now and nothing was charged. Retry-After says when it should be back.", "value": { "error": { "message": "…", "type": "model_capacity", "code": 429, "retryable": true, "charged": false } } } } } } }, "InternalError": { "description": "A failure on our side. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "500_internal_error": { "summary": "Something failed on our side. Nothing was charged.", "value": { "error": { "message": "…", "type": "internal_error", "code": 500, "retryable": true, "charged": false } } } } } } }, "Unavailable": { "description": "Every route for the model failed or is paused. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "503_upstream_error": { "summary": "Every eligible upstream failed. Nothing was charged.", "value": { "error": { "message": "…", "type": "upstream_error", "code": 503, "retryable": true, "charged": false } } }, "503_no_available_endpoint": { "summary": "All endpoints for the model are disabled or paused. Retry-After is set when one is due back.", "value": { "error": { "message": "…", "type": "no_available_endpoint", "code": 503, "retryable": true, "charged": false } } } } } } }, "ResponsesBadRequest": { "description": "Invalid request, a price ceiling (max_price) below the model's price, or zdr with no zero-retention route. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "400_invalid_request": { "summary": "Malformed body, missing model or messages, or a parameter the model rejected.", "value": { "error": { "message": "…", "type": "invalid_request", "param": null, "code": "invalid_request", "retryable": false, "charged": false } } }, "400_max_price_exceeded": { "summary": "The model's price is above your max_price (prompt or completion, USD per 1M tokens). Refused before anything is reserved; error.pricing has the model's prices.", "value": { "error": { "message": "…", "type": "max_price_exceeded", "param": null, "code": "max_price_exceeded", "retryable": false, "charged": false } } }, "400_zdr_unavailable": { "summary": "You sent zdr: true and the model has no zero-data-retention route.", "value": { "error": { "message": "…", "type": "zdr_unavailable", "param": null, "code": "zdr_unavailable", "retryable": false, "charged": false } } } } } } }, "ResponsesUnauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "401_invalid_api_key": { "summary": "Missing, unknown, disabled, revoked or expired key.", "value": { "error": { "message": "…", "type": "invalid_api_key", "param": null, "code": "invalid_api_key", "retryable": false, "charged": false } } } } } } }, "ResponsesPaymentRequired": { "description": "Not enough credit or key spending limit for the request's hold, or a model available only after the account's first credit purchase. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "402_insufficient_credits": { "summary": "Available balance is below the request's hold (for a stream, its first slice). Mid-stream, it arrives as an error event when the balance or key limit can't cover more output; you pay only for what was sent.", "value": { "error": { "message": "…", "type": "insufficient_credits", "param": null, "code": "insufficient_credits", "retryable": false, "charged": false } } }, "402_key_limit_exceeded": { "summary": "The request's maximum possible cost (prompt plus max_tokens) is more than one of the key's spending limits has left. error.limit says which: total, daily or monthly; daily and monthly add error.resets_at. Mid-stream, it arrives as an error event.", "value": { "error": { "message": "…", "type": "key_limit_exceeded", "param": null, "code": "key_limit_exceeded", "retryable": false, "charged": false } } }, "402_purchase_required": { "summary": "The model is available after your first credit purchase (its supplier limits daily use), and this account has not bought credit yet: the sign-up credit alone does not unlock it. Refused before anything is reserved; the message names a model you can use now. GET /models shows requires_purchase: true for these models.", "value": { "error": { "message": "…", "type": "purchase_required", "param": null, "code": "purchase_required", "retryable": false, "charged": false } } } } } } }, "ResponsesForbidden": { "description": "The account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "403_account_suspended": { "summary": "The account is suspended.", "value": { "error": { "message": "…", "type": "account_suspended", "param": null, "code": "account_suspended", "retryable": false, "charged": false } } } } } } }, "ResponsesNotFound": { "description": "Unknown model, path or generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "404_model_not_found": { "summary": "Unknown or not publicly available model.", "value": { "error": { "message": "…", "type": "model_not_found", "param": null, "code": "model_not_found", "retryable": false, "charged": false } } }, "404_not_found": { "summary": "Unknown path (only the endpoints in this reference exist), or a generation id that is not yours.", "value": { "error": { "message": "…", "type": "not_found", "param": null, "code": "not_found", "retryable": false, "charged": false } } } } } } }, "ResponsesTimeout": { "description": "The model did not respond in time. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "408_timeout": { "summary": "The model did not respond in time and nothing was charged.", "value": { "error": { "message": "…", "type": "timeout", "param": null, "code": "timeout", "retryable": true, "charged": false } } } } } } }, "ResponsesPayloadTooLarge": { "description": "The body is larger than 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "413_invalid_request": { "summary": "Request body larger than 32 MiB.", "value": { "error": { "message": "…", "type": "invalid_request", "param": null, "code": "invalid_request", "retryable": false, "charged": false } } } } } } }, "ResponsesTooManyRequests": { "description": "A rate, concurrency, daily token or model-capacity limit. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "429_rate_limited": { "summary": "Per-key request rate reached (600 per minute by default). Retry-After header is set.", "value": { "error": { "message": "…", "type": "rate_limited", "param": null, "code": "rate_limited", "retryable": true, "charged": false } } }, "429_concurrency_limited": { "summary": "The key already has as many requests running as its limit allows. Retry-After: 1.", "value": { "error": { "message": "…", "type": "concurrency_limited", "param": null, "code": "concurrency_limited", "retryable": true, "charged": false } } }, "429_key_token_limit_exceeded": { "summary": "The key used its daily token limit. Retry-After and error.resets_at give the reset (00:00 UTC).", "value": { "error": { "message": "…", "type": "key_token_limit_exceeded", "param": null, "code": "key_token_limit_exceeded", "retryable": false, "charged": false } } }, "429_model_capacity": { "summary": "The model is at capacity right now and nothing was charged. Retry-After says when it should be back.", "value": { "error": { "message": "…", "type": "model_capacity", "param": null, "code": "model_capacity", "retryable": true, "charged": false } } } } } } }, "ResponsesInternalError": { "description": "A failure on our side. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "500_internal_error": { "summary": "Something failed on our side. Nothing was charged.", "value": { "error": { "message": "…", "type": "internal_error", "param": null, "code": "internal_error", "retryable": true, "charged": false } } } } } } }, "ResponsesUnavailable": { "description": "Every route for the model failed or is paused. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesErrorBody" }, "examples": { "503_upstream_error": { "summary": "Every eligible upstream failed. Nothing was charged.", "value": { "error": { "message": "…", "type": "upstream_error", "param": null, "code": "upstream_error", "retryable": true, "charged": false } } }, "503_no_available_endpoint": { "summary": "All endpoints for the model are disabled or paused. Retry-After is set when one is due back.", "value": { "error": { "message": "…", "type": "no_available_endpoint", "param": null, "code": "no_available_endpoint", "retryable": true, "charged": false } } } } } } }, "MessagesBadRequest": { "description": "Invalid request, a price ceiling (max_price) below the model's price, or zdr with no zero-retention route. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "400_invalid_request": { "summary": "Malformed body, missing model or messages, or a parameter the model rejected.", "value": { "type": "error", "error": { "type": "invalid_request_error", "message": "…" } } }, "400_max_price_exceeded": { "summary": "The model's price is above your max_price (prompt or completion, USD per 1M tokens). Refused before anything is reserved; error.pricing has the model's prices.", "value": { "type": "error", "error": { "type": "invalid_request_error", "message": "…" } } }, "400_zdr_unavailable": { "summary": "You sent zdr: true and the model has no zero-data-retention route.", "value": { "type": "error", "error": { "type": "invalid_request_error", "message": "…" } } } } } } }, "MessagesUnauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "401_invalid_api_key": { "summary": "Missing, unknown, disabled, revoked or expired key.", "value": { "type": "error", "error": { "type": "authentication_error", "message": "…" } } } } } } }, "MessagesPaymentRequired": { "description": "Not enough credit or key spending limit for the request's hold, or a model available only after the account's first credit purchase. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "402_insufficient_credits": { "summary": "Available balance is below the request's hold (for a stream, its first slice). Mid-stream, it arrives as an error event when the balance or key limit can't cover more output; you pay only for what was sent.", "value": { "type": "error", "error": { "type": "billing_error", "message": "…" } } }, "402_key_limit_exceeded": { "summary": "The request's maximum possible cost (prompt plus max_tokens) is more than one of the key's spending limits has left. error.limit says which: total, daily or monthly; daily and monthly add error.resets_at. Mid-stream, it arrives as an error event.", "value": { "type": "error", "error": { "type": "billing_error", "message": "…" } } }, "402_purchase_required": { "summary": "The model is available after your first credit purchase (its supplier limits daily use), and this account has not bought credit yet: the sign-up credit alone does not unlock it. Refused before anything is reserved; the message names a model you can use now. GET /models shows requires_purchase: true for these models.", "value": { "type": "error", "error": { "type": "billing_error", "message": "…" } } } } } } }, "MessagesForbidden": { "description": "The account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "403_account_suspended": { "summary": "The account is suspended.", "value": { "type": "error", "error": { "type": "permission_error", "message": "…" } } } } } } }, "MessagesNotFound": { "description": "Unknown model, path or generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "404_model_not_found": { "summary": "Unknown or not publicly available model.", "value": { "type": "error", "error": { "type": "not_found_error", "message": "…" } } }, "404_not_found": { "summary": "Unknown path (only the endpoints in this reference exist), or a generation id that is not yours.", "value": { "type": "error", "error": { "type": "not_found_error", "message": "…" } } } } } } }, "MessagesTimeout": { "description": "The model did not respond in time. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "408_timeout": { "summary": "The model did not respond in time and nothing was charged.", "value": { "type": "error", "error": { "type": "timeout_error", "message": "…" } } } } } } }, "MessagesPayloadTooLarge": { "description": "The body is larger than 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "413_invalid_request": { "summary": "Request body larger than 32 MiB.", "value": { "type": "error", "error": { "type": "request_too_large", "message": "…" } } } } } } }, "MessagesTooManyRequests": { "description": "A rate, concurrency, daily token or model-capacity limit. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "429_rate_limited": { "summary": "Per-key request rate reached (600 per minute by default). Retry-After header is set.", "value": { "type": "error", "error": { "type": "rate_limit_error", "message": "…" } } }, "429_concurrency_limited": { "summary": "The key already has as many requests running as its limit allows. Retry-After: 1.", "value": { "type": "error", "error": { "type": "rate_limit_error", "message": "…" } } }, "429_key_token_limit_exceeded": { "summary": "The key used its daily token limit. Retry-After and error.resets_at give the reset (00:00 UTC).", "value": { "type": "error", "error": { "type": "rate_limit_error", "message": "…" } } }, "429_model_capacity": { "summary": "The model is at capacity right now and nothing was charged. Retry-After says when it should be back.", "value": { "type": "error", "error": { "type": "rate_limit_error", "message": "…" } } } } } } }, "MessagesInternalError": { "description": "A failure on our side. Nothing is charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "500_internal_error": { "summary": "Something failed on our side. Nothing was charged.", "value": { "type": "error", "error": { "type": "api_error", "message": "…" } } } } } } }, "MessagesUnavailable": { "description": "Every route for the model failed or is paused. Nothing is charged.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorBody" }, "examples": { "503_upstream_error": { "summary": "Every eligible upstream failed. Nothing was charged.", "value": { "type": "error", "error": { "type": "overloaded_error", "message": "…" } } }, "503_no_available_endpoint": { "summary": "All endpoints for the model are disabled or paused. Retry-After is set when one is due back.", "value": { "type": "error", "error": { "type": "overloaded_error", "message": "…" } } } } } } } }, "schemas": { "ErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorObject" } } }, "ErrorObject": { "type": "object", "required": [ "message", "type", "code", "retryable", "charged" ], "description": "Branch on `type`, not `message`. Some types add fields (listed); new fields may be added.", "properties": { "message": { "type": "string", "description": "For humans; may change." }, "type": { "type": "string", "enum": [ "invalid_request", "max_price_exceeded", "zdr_unavailable", "invalid_api_key", "insufficient_credits", "key_limit_exceeded", "purchase_required", "account_suspended", "model_not_found", "not_found", "method_not_allowed", "timeout", "rate_limited", "concurrency_limited", "key_token_limit_exceeded", "model_capacity", "internal_error", "upstream_error", "no_available_endpoint" ], "description": "Stable, machine-readable error type." }, "code": { "type": "integer", "description": "The HTTP status (also inside an in-stream error)." }, "retryable": { "type": "boolean", "description": "The same request, unchanged, can succeed later (after Retry-After when set)." }, "charged": { "type": "boolean", "description": "This request was billed: only an in-stream error after output reached you." }, "limit": { "type": "string", "enum": [ "total", "daily", "monthly" ], "description": "key_limit_exceeded: which spending limit." }, "resets_at": { "type": "string", "format": "date-time", "description": "When a daily or monthly limit resets (UTC)." }, "pricing": { "type": "object", "description": "max_price_exceeded: the model's prices, USD per 1M tokens, as decimal strings.", "properties": { "prompt": { "type": "string" }, "completion": { "type": "string" } } } }, "additionalProperties": true }, "ResponsesErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string", "description": "For humans; may change." }, "type": { "type": "string", "description": "Our error type (see ErrorObject.type)." }, "param": { "type": [ "string", "null" ], "description": "The request field at fault, when known." }, "code": { "type": "string", "description": "Our error type again, as a string (Codex reads `code`)." }, "retryable": { "type": "boolean" }, "charged": { "type": "boolean" } }, "additionalProperties": true, "description": "OpenAI's error envelope. Errors from the routing core add retryable, charged and the type's extra fields." } } }, "MessagesErrorBody": { "type": "object", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "const": "error" }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "timeout_error", "request_too_large", "rate_limit_error", "api_error", "overloaded_error" ], "description": "Anthropic's error type for the HTTP status." }, "message": { "type": "string", "description": "For humans; may change. Names our error type's cause, e.g. the model to set." } } } }, "description": "Anthropic's error envelope." }, "ModelList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Model": { "type": "object", "required": [ "id", "object", "created", "owned_by", "name", "description", "context_length", "max_output_tokens", "architecture", "capabilities", "pricing", "supported_parameters", "capability_details", "has_cache_read_price", "quantization", "data_retention", "availability", "verified_at", "requires_purchase" ], "description": "Every value comes from the catalog or a verified run; unknown is null, never a guess. A model-level fact holds on every route that may serve it.", "properties": { "id": { "type": "string", "description": "The model id to send as `model`.", "example": "deepseek/deepseek-v4-flash" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer", "description": "Release date (Unix seconds); 0 when unknown." }, "owned_by": { "type": "string", "description": "The lab that made the model.", "example": "deepseek" }, "name": { "type": "string" }, "description": { "type": "string" }, "context_length": { "type": "integer", "description": "Maximum prompt + output tokens." }, "max_output_tokens": { "type": "integer" }, "architecture": { "$ref": "#/components/schemas/Architecture" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "streaming", "tools", "structured_outputs", "reasoning" ] }, "description": "Only capabilities verified end to end through this API." }, "pricing": { "$ref": "#/components/schemas/ModelPricing" }, "supported_parameters": { "type": "array", "items": { "type": "string" }, "description": "Parameters verified for this model, plus the gateway's own (max_tokens, max_completion_tokens, max_price, zdr). Other OpenAI parameters are forwarded but not verified per model: absent means not verified." }, "capability_details": { "$ref": "#/components/schemas/CapabilityDetails" }, "has_cache_read_price": { "type": "boolean", "description": "The model has a cache-read price (pricing.input_cache_read is set)." }, "quantization": { "type": [ "string", "null" ], "description": "When every route publishes the same value (e.g. fp8); null otherwise." }, "data_retention": { "type": "object", "required": [ "zero_retention_available", "zero_retention_all_routes" ], "properties": { "zero_retention_available": { "type": "boolean", "description": "Some route's supplier promises not to store inputs and outputs: `zdr: true` works." }, "zero_retention_all_routes": { "type": "boolean", "description": "Every route does." } } }, "availability": { "type": "object", "required": [ "status", "retry_after" ], "properties": { "status": { "type": "string", "enum": [ "available", "at_capacity", "unavailable" ], "description": "at_capacity: a supplier's capacity limit took every route out; unavailable: every route is paused for other reasons." }, "retry_after": { "type": [ "integer", "null" ], "description": "Seconds until the first route is due back." } } }, "verified_at": { "type": [ "string", "null" ], "format": "date", "description": "The oldest date a real run verified a serving route; null when one never was." }, "requires_purchase": { "type": "boolean", "description": "Available only after the account's first credit purchase (the supplier caps the model, e.g. tokens per day). Accounts holding only sign-up credit get 402 purchase_required." } }, "additionalProperties": true }, "Architecture": { "type": "object", "required": [ "input_modalities", "output_modalities" ], "properties": { "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "file", "audio", "video" ] } }, "output_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "file", "audio", "video" ] } } } }, "ModelPricing": { "type": "object", "description": "USD per token as decimal strings. Multiply by 1,000,000 for the price per 1M tokens.", "required": [ "prompt", "completion", "input_cache_read" ], "properties": { "prompt": { "type": "string", "pattern": "^[0-9.]+$", "example": "0.000000175" }, "completion": { "type": "string", "pattern": "^[0-9.]+$", "example": "0.00000035" }, "input_cache_read": { "type": [ "string", "null" ], "pattern": "^[0-9.]+$", "description": "Cached prompt tokens; null when the model has no cache-read price (they cost the input price)." } } }, "CapabilityDetails": { "type": "object", "required": [ "tools", "parallel_tool_calls", "tool_choice", "structured_outputs", "reasoning", "reasoning_effort", "image_input" ], "properties": { "tools": { "type": "boolean" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Every route made parallel calls in the probe (true), some did not (false), unknown (null)." }, "tool_choice": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "auto", "none", "required", "function" ] }, "description": "tool_choice modes every route passed (function = a named tool); null when unknown." }, "structured_outputs": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "reasoning_effort": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Effort levels verified on every route; null when unknown." }, "image_input": { "type": "boolean" } } }, "MaxPrice": { "type": "object", "description": "Highest acceptable price in USD per 1M tokens, as numbers or numeric strings. Other kinds are ignored (we bill nothing per request or image). The cache-read price is never above the input price, so `prompt` covers it.", "properties": { "prompt": { "type": [ "number", "string" ], "description": "USD per 1M input tokens." }, "completion": { "type": [ "number", "string" ], "description": "USD per 1M output tokens." } }, "additionalProperties": true }, "ProviderPreferences": { "type": "object", "description": "OpenRouter's provider object. `max_price` and `zdr` are applied (with the top-level ones, the stricter wins); other fields are accepted and ignored. Never sent upstream.", "properties": { "max_price": { "$ref": "#/components/schemas/MaxPrice" }, "zdr": { "type": "boolean" } }, "additionalProperties": true }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "description": "OpenAI Chat Completions parameters. Other OpenAI parameters are passed to the model; if it rejects one, you get 400 invalid_request.", "properties": { "model": { "type": "string", "example": "deepseek/deepseek-v4-flash" }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatMessage" } }, "stream": { "type": "boolean", "default": false }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "description": "Accepted; the usage chunk is always sent." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Cap on generated tokens. Also lowers the hold on your balance." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "description": "Same as max_tokens." }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "n": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Number of choices; the hold covers all of them." }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" }, "description": "For models with the tools capability." }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } ] }, "parallel_tool_calls": { "type": "boolean" }, "response_format": { "type": "object", "description": "`{type: \"json_object\"}` or `{type: \"json_schema\", json_schema: {...}}`, for models with structured_outputs.", "additionalProperties": true }, "seed": { "type": "integer" }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "reasoning_effort": { "type": "string", "description": "Passed to reasoning models that support it." }, "max_price": { "$ref": "#/components/schemas/MaxPrice", "description": "Refuse the request (400 max_price_exceeded, before anything is reserved) when the model's price is above this, in USD per 1M tokens." }, "zdr": { "type": "boolean", "description": "Zero data retention: use only routes whose supplier's terms promise inputs and outputs are not stored. A model with none answers 400 zdr_unavailable; when its zero-retention routes are down you get 503/429, never a route that keeps data." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" }, "user": { "type": "string", "description": "Accepted for compatibility; never stored or forwarded." } }, "additionalProperties": true }, "ChatMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" } }, { "type": "null" } ], "description": "Text, or content parts (text and, for models with image input, image_url)." }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } }, "tool_call_id": { "type": "string" }, "reasoning_content": { "type": "string", "description": "An earlier turn's reasoning, sent back to models that use it." } }, "additionalProperties": true }, "ContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "image_url" ] }, "text": { "type": "string" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "https URL or data: URI." } } } }, "additionalProperties": true }, "Tool": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" } } } } }, "ToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON text." } } } } }, "ChatCompletion": { "type": "object", "required": [ "id", "object", "created", "model", "choices", "usage" ], "properties": { "id": { "type": "string", "description": "Our request id (gen-…)." }, "object": { "type": "string", "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string", "description": "The model that served the request (an alias you sent resolves to its target)." }, "choices": { "type": "array", "items": { "type": "object", "required": [ "index", "message", "finish_reason" ], "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/AssistantMessage" }, "finish_reason": { "type": [ "string", "null" ], "description": "stop, length, tool_calls, content_filter or error." }, "logprobs": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": true }, "AssistantMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": [ "string", "null" ] }, "refusal": { "type": [ "string", "null" ] }, "reasoning_content": { "type": "string", "description": "Reasoning text, from models that return it (also sent as `reasoning`)." }, "reasoning": { "type": "string", "description": "The same reasoning text, OpenRouter's name." }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } } }, "additionalProperties": true }, "ChatCompletionChunk": { "type": "object", "required": [ "id", "object", "created", "model", "choices" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion.chunk" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "required": [ "index", "delta" ], "properties": { "index": { "type": "integer" }, "delta": { "type": "object", "additionalProperties": true, "description": "role, content, reasoning_content / reasoning or tool_calls fragments." }, "finish_reason": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage", "description": "Only on the final chunk." }, "error": { "$ref": "#/components/schemas/ErrorObject", "description": "Only on an in-stream error chunk (finish_reason \"error\")." } }, "additionalProperties": true }, "Usage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "cost" ], "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer", "description": "Includes reasoning tokens." }, "total_tokens": { "type": "integer" }, "prompt_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" } } }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer" } } }, "cost": { "type": "number", "description": "What this request was charged, in USD." } }, "additionalProperties": true }, "ResponsesRequest": { "type": "object", "required": [ "model", "input" ], "description": "OpenAI Responses parameters. `store`, `include`, `metadata` (echoed back), `prompt_cache_key`, `user` and `client_metadata` are accepted and neither stored nor forwarded.", "properties": { "model": { "type": "string", "example": "deepseek/deepseek-v4-flash" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ResponseInputItem" } } ], "description": "The whole conversation: a string, or items (messages, function calls and their outputs, reasoning)." }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponseInputItem" } } ], "description": "Joined with leading system/developer messages into one first system message." }, "stream": { "type": "boolean", "default": false }, "max_output_tokens": { "type": "integer", "minimum": 1, "description": "Becomes max_tokens; also lowers the hold." }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesTool" } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "function", "custom" ] }, "name": { "type": "string" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "allowed_tools" }, "mode": { "type": "string", "enum": [ "auto", "required" ] }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } } } } ] }, "parallel_tool_calls": { "type": "boolean" }, "reasoning": { "type": "object", "properties": { "effort": { "type": [ "string", "null" ], "enum": [ "minimal", "low", "medium", "high", "xhigh", "none", null ], "description": "Sent as reasoning_effort to models with the reasoning capability (minimal → low, xhigh → high; none → not sent)." }, "summary": { "type": [ "string", "null" ], "description": "When set, reasoning comes back as summary parts instead of reasoning_text content." } }, "additionalProperties": true }, "text": { "type": "object", "properties": { "format": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] }, "name": { "type": "string" }, "schema": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" }, "description": { "type": "string" } } } }, "additionalProperties": true }, "store": { "type": "boolean", "description": "Accepted; nothing is ever stored." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Echoed in the response; not stored." }, "max_price": { "$ref": "#/components/schemas/MaxPrice", "description": "Refuse the request (400 max_price_exceeded, before anything is reserved) when the model's price is above this, in USD per 1M tokens." }, "zdr": { "type": "boolean", "description": "Zero data retention: use only routes whose supplier's terms promise inputs and outputs are not stored. A model with none answers 400 zdr_unavailable; when its zero-retention routes are down you get 503/429, never a route that keeps data." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" } }, "additionalProperties": true }, "ResponseInputItem": { "type": "object", "description": "A message (`type` may be omitted when `role` is set), a function_call or custom_tool_call the model made, its *_output, or a reasoning item sent back. Images a tool returns go into a user turn after the tool results.", "properties": { "type": { "type": "string", "enum": [ "message", "function_call", "function_call_output", "custom_tool_call", "custom_tool_call_output", "reasoning" ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponseInputPart" } } ], "description": "Message parts; for a reasoning item, its reasoning_text parts." }, "call_id": { "type": "string" }, "name": { "type": "string" }, "namespace": { "type": "string", "description": "Codex's grouped tools: the namespace the call belongs to." }, "arguments": { "type": "string", "description": "function_call: JSON text." }, "input": { "type": "string", "description": "custom_tool_call: the freeform input." }, "output": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponseInputPart" } } ] }, "summary": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } }, "additionalProperties": true }, "ResponseInputPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text", "output_text", "text", "input_image", "refusal", "reasoning_text" ] }, "text": { "type": "string" }, "image_url": { "type": "string", "description": "input_image: an https URL or data: URL (there is no Files API, so file_id is refused)." }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ] }, "refusal": { "type": "string" } }, "additionalProperties": true }, "ResponsesTool": { "type": "object", "required": [ "type" ], "description": "function; custom (freeform: one string input, its grammar appended to the description); namespace (Codex's grouped function/custom tools, flattened). Hosted tools such as web_search get 400.", "properties": { "type": { "type": "string", "enum": [ "function", "custom", "namespace" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" }, "format": { "type": "object", "additionalProperties": true, "description": "custom: {type: grammar, syntax, definition}." }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "namespace: its tools." } }, "additionalProperties": true }, "Response": { "type": "object", "required": [ "id", "object", "created_at", "status", "error", "incomplete_details", "model", "output", "parallel_tool_calls", "store", "text", "tool_choice", "tools", "usage", "metadata" ], "properties": { "id": { "type": "string", "description": "Our request id (gen-…)." }, "object": { "type": "string", "const": "response" }, "created_at": { "type": "integer" }, "status": { "type": "string", "enum": [ "completed", "incomplete", "in_progress", "failed" ] }, "background": { "type": "boolean", "const": false }, "error": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } ] }, "incomplete_details": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "enum": [ "max_output_tokens", "content_filter" ] } } } ] }, "instructions": { "type": [ "string", "array", "null" ] }, "max_output_tokens": { "type": [ "integer", "null" ] }, "max_tool_calls": { "type": "null" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseOutputItem" } }, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": "null" }, "reasoning": { "type": "object", "properties": { "effort": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] } } }, "service_tier": { "type": "string", "const": "default" }, "store": { "type": "boolean", "const": false }, "temperature": { "type": [ "number", "null" ] }, "text": { "type": "object", "properties": { "format": { "type": "object", "additionalProperties": true } } }, "tool_choice": { "type": [ "string", "object" ] }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "top_p": { "type": [ "number", "null" ] }, "truncation": { "type": "string", "const": "disabled" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseUsage" } ] }, "user": { "type": "null" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ResponseOutputItem": { "oneOf": [ { "$ref": "#/components/schemas/ResponseReasoningItem" }, { "$ref": "#/components/schemas/ResponseOutputMessage" }, { "$ref": "#/components/schemas/ResponseFunctionCall" }, { "$ref": "#/components/schemas/ResponseCustomToolCall" } ] }, "ResponseReasoningItem": { "type": "object", "required": [ "id", "type", "summary" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "reasoning" }, "summary": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryText" } }, "content": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "reasoning_text" }, "text": { "type": "string" } } } }, "encrypted_content": { "type": "null" } }, "description": "The model's full reasoning: as summary parts when the request set reasoning.summary, else as reasoning_text content." }, "SummaryText": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "summary_text" }, "text": { "type": "string" } } }, "OutputText": { "type": "object", "required": [ "type", "text", "annotations" ], "properties": { "type": { "type": "string", "const": "output_text" }, "text": { "type": "string" }, "annotations": { "type": "array" }, "logprobs": { "type": "array" } } }, "ResponseOutputMessage": { "type": "object", "required": [ "id", "type", "status", "role", "content" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "message" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "role": { "type": "string", "const": "assistant" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/OutputText" } } } }, "ResponseFunctionCall": { "type": "object", "required": [ "id", "type", "status", "call_id", "name", "arguments" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function_call" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON text." }, "namespace": { "type": "string" } } }, "ResponseCustomToolCall": { "type": "object", "required": [ "id", "type", "status", "call_id", "name", "input" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "custom_tool_call" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "call_id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "string" }, "namespace": { "type": "string" } } }, "ResponseUsage": { "type": "object", "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens", "cost" ], "properties": { "input_tokens": { "type": "integer" }, "input_tokens_details": { "type": "object", "required": [ "cached_tokens" ], "properties": { "cached_tokens": { "type": "integer" } } }, "output_tokens": { "type": "integer", "description": "Includes reasoning tokens." }, "output_tokens_details": { "type": "object", "required": [ "reasoning_tokens" ], "properties": { "reasoning_tokens": { "type": "integer" } } }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "What this request was charged, in USD." } } }, "ResponseStreamEvent": { "description": "One event of a Responses stream (`data:` JSON); `type` repeats the `event:` name.", "oneOf": [ { "$ref": "#/components/schemas/ResponseLifecycleEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemEvent" }, { "$ref": "#/components/schemas/ResponseContentPartEvent" }, { "$ref": "#/components/schemas/ResponseTextDeltaEvent" }, { "$ref": "#/components/schemas/ResponseTextDoneEvent" }, { "$ref": "#/components/schemas/ResponseSummaryPartEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDeltaEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDoneEvent" }, { "$ref": "#/components/schemas/ResponseCustomToolCallInputDoneEvent" }, { "$ref": "#/components/schemas/ResponseErrorEvent" } ] }, "ResponseLifecycleEvent": { "type": "object", "required": [ "type", "sequence_number", "response" ], "properties": { "type": { "type": "string", "enum": [ "response.created", "response.in_progress", "response.completed", "response.incomplete", "response.failed" ], "description": "created and in_progress first; then exactly one of completed, incomplete or failed (after an error event)." }, "sequence_number": { "type": "integer" }, "response": { "$ref": "#/components/schemas/Response" } } }, "ResponseOutputItemEvent": { "type": "object", "required": [ "type", "sequence_number", "output_index", "item" ], "properties": { "type": { "type": "string", "enum": [ "response.output_item.added", "response.output_item.done" ] }, "sequence_number": { "type": "integer" }, "output_index": { "type": "integer" }, "item": { "$ref": "#/components/schemas/ResponseOutputItem" } } }, "ResponseContentPartEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "properties": { "type": { "type": "string", "enum": [ "response.content_part.added", "response.content_part.done" ] }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "content_index": { "type": "integer" }, "part": { "$ref": "#/components/schemas/OutputText" } } }, "ResponseTextDeltaEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "properties": { "type": { "type": "string", "enum": [ "response.output_text.delta", "response.reasoning_text.delta", "response.reasoning_summary_text.delta" ] }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "content_index": { "type": "integer", "description": "output_text and reasoning_text." }, "summary_index": { "type": "integer", "description": "reasoning_summary_text." }, "delta": { "type": "string" }, "logprobs": { "type": "array" } } }, "ResponseTextDoneEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "text" ], "properties": { "type": { "type": "string", "enum": [ "response.output_text.done", "response.reasoning_text.done", "response.reasoning_summary_text.done" ] }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "content_index": { "type": "integer" }, "summary_index": { "type": "integer" }, "text": { "type": "string" }, "logprobs": { "type": "array" } } }, "ResponseSummaryPartEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_part.added", "response.reasoning_summary_part.done" ] }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "summary_index": { "type": "integer" }, "part": { "$ref": "#/components/schemas/SummaryText" } } }, "ResponseFunctionCallArgumentsDeltaEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "properties": { "type": { "type": "string", "const": "response.function_call_arguments.delta" }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "delta": { "type": "string" } } }, "ResponseFunctionCallArgumentsDoneEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "name", "arguments" ], "properties": { "type": { "type": "string", "const": "response.function_call_arguments.done" }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "name": { "type": "string" }, "arguments": { "type": "string" } } }, "ResponseCustomToolCallInputDoneEvent": { "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "input" ], "properties": { "type": { "type": "string", "const": "response.custom_tool_call_input.done" }, "sequence_number": { "type": "integer" }, "item_id": { "type": "string" }, "output_index": { "type": "integer" }, "input": { "type": "string" } } }, "ResponseErrorEvent": { "type": "object", "required": [ "type", "sequence_number", "code", "message" ], "properties": { "type": { "type": "string", "const": "error" }, "sequence_number": { "type": "integer" }, "code": { "type": "string", "description": "server_error for upstream failures (Codex retries those), otherwise our error type." }, "message": { "type": "string" }, "param": { "type": "null" } } }, "MessagesRequest": { "type": "object", "required": [ "model", "max_tokens", "messages" ], "description": "Anthropic Messages parameters. `metadata`, `cache_control`, `service_tier` and `context_management` are ignored; `mcp_servers`, `container` and Anthropic's server tools get 400.", "properties": { "model": { "type": "string", "description": "One of our model ids, not claude-….", "example": "deepseek/deepseek-v4-flash" }, "max_tokens": { "type": "integer", "minimum": 1 }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/MessagesTurn" } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } ] }, "stream": { "type": "boolean", "default": false }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesTool" } }, "tool_choice": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string", "description": "type tool: the tool to call." }, "disable_parallel_tool_use": { "type": "boolean" } } }, "thinking": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "enabled", "adaptive", "disabled" ] }, "budget_tokens": { "type": "integer", "description": "Mapped to reasoning_effort for reasoning models (< 4096 low, < 16384 medium, else high)." }, "display": { "type": "string", "enum": [ "omitted", "summarized" ], "description": "omitted: thinking text empty; it travels in the signature instead." } }, "additionalProperties": true }, "output_config": { "type": "object", "properties": { "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "format": { "type": "object", "required": [ "type", "schema" ], "properties": { "type": { "type": "string", "const": "json_schema" }, "schema": { "type": "object", "additionalProperties": true } } } }, "additionalProperties": true }, "max_price": { "$ref": "#/components/schemas/MaxPrice", "description": "Refuse the request (400 max_price_exceeded, before anything is reserved) when the model's price is above this, in USD per 1M tokens." }, "zdr": { "type": "boolean", "description": "Zero data retention: use only routes whose supplier's terms promise inputs and outputs are not stored. A model with none answers 400 zdr_unavailable; when its zero-retention routes are down you get 503/429, never a route that keeps data." }, "provider": { "$ref": "#/components/schemas/ProviderPreferences" } }, "additionalProperties": true }, "MessagesCountTokensRequest": { "type": "object", "required": [ "model", "messages" ], "description": "The Messages body; max_tokens is not needed.", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/MessagesTurn" } }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesTool" } } }, "additionalProperties": true }, "MessagesTurn": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ], "description": "system turns (Claude Code 2.1) stay system messages at their position." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/MessagesContentBlock" } } ] } } }, "MessagesContentBlock": { "type": "object", "required": [ "type" ], "description": "text; image (base64 or url source); tool_use and tool_result (text, images, documents, is_error); thinking (sent back as the model's earlier reasoning; redacted_thinking ignored); document (text sources inlined, other files replaced by a note to the model).", "properties": { "type": { "type": "string", "enum": [ "text", "image", "tool_use", "tool_result", "thinking", "redacted_thinking", "document" ] }, "text": { "type": "string" }, "source": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "tool_use_id": { "type": "string" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "is_error": { "type": "boolean" }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "additionalProperties": true }, "MessagesTool": { "type": "object", "required": [ "name" ], "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "Custom tools only; Anthropic's server and defined tools get 400." }, "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" }, "defer_loading": { "type": "boolean", "description": "Left out until a tool_reference in a tool_result loads it." } }, "additionalProperties": true }, "Message": { "type": "object", "required": [ "id", "type", "role", "model", "content", "stop_reason", "stop_sequence", "usage" ], "properties": { "id": { "type": "string", "description": "Our request id (gen-…)." }, "type": { "type": "string", "const": "message" }, "role": { "type": "string", "const": "assistant" }, "model": { "type": "string" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessageContent" } }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "end_turn", "max_tokens", "tool_use", "stop_sequence", "refusal", null ], "description": "null only in message_start." }, "stop_sequence": { "type": [ "string", "null" ] }, "usage": { "$ref": "#/components/schemas/MessagesUsage" } }, "additionalProperties": true }, "MessageContent": { "oneOf": [ { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "additionalProperties": true }, { "type": "object", "required": [ "type", "thinking", "signature" ], "properties": { "type": { "type": "string", "const": "thinking" }, "thinking": { "type": "string", "description": "Empty with display: omitted." }, "signature": { "type": "string", "description": "`amr`, or `amr1.` with display: omitted." } }, "additionalProperties": true }, { "type": "object", "required": [ "type", "id", "name", "input" ], "properties": { "type": { "type": "string", "const": "tool_use" }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } ] }, "MessagesUsage": { "type": "object", "required": [ "input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Prompt tokens not read from cache (message_start: an estimate)." }, "cache_creation_input_tokens": { "type": "integer", "description": "Always 0." }, "cache_read_input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "What this request was charged, in USD (not in message_start)." } } }, "MessageStreamEvent": { "description": "One event of a Messages stream (`data:` JSON); `type` repeats the `event:` name.", "oneOf": [ { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "const": "message_start" }, "message": { "$ref": "#/components/schemas/Message" } } }, { "type": "object", "required": [ "type", "index", "content_block" ], "properties": { "type": { "type": "string", "const": "content_block_start" }, "index": { "type": "integer" }, "content_block": { "$ref": "#/components/schemas/MessageContent" } } }, { "type": "object", "required": [ "type", "index", "delta" ], "properties": { "type": { "type": "string", "const": "content_block_delta" }, "index": { "type": "integer" }, "delta": { "oneOf": [ { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text_delta" }, "text": { "type": "string" } } }, { "type": "object", "required": [ "type", "thinking" ], "properties": { "type": { "type": "string", "const": "thinking_delta" }, "thinking": { "type": "string" } } }, { "type": "object", "required": [ "type", "signature" ], "properties": { "type": { "type": "string", "const": "signature_delta" }, "signature": { "type": "string" } } }, { "type": "object", "required": [ "type", "partial_json" ], "properties": { "type": { "type": "string", "const": "input_json_delta" }, "partial_json": { "type": "string" } } } ] } } }, { "type": "object", "required": [ "type", "index" ], "properties": { "type": { "type": "string", "const": "content_block_stop" }, "index": { "type": "integer" } } }, { "type": "object", "required": [ "type", "delta", "usage" ], "properties": { "type": { "type": "string", "const": "message_delta" }, "delta": { "type": "object", "required": [ "stop_reason", "stop_sequence" ], "properties": { "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "tool_use", "stop_sequence", "refusal" ] }, "stop_sequence": { "type": [ "string", "null" ] } } }, "usage": { "$ref": "#/components/schemas/MessagesUsage" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "message_stop" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "ping" } } }, { "$ref": "#/components/schemas/MessagesErrorBody" } ] }, "KeyInfo": { "type": "object", "description": "USD amounts are numbers; a limit that is not set is null, and so is its *_remaining.", "required": [ "name", "key_prefix", "usage", "rate_limit", "reserved", "spendable", "balance", "available" ], "properties": { "name": { "type": "string" }, "key_prefix": { "type": "string", "example": "sk-amr-v1-3f9a" }, "limit": { "type": [ "number", "null" ], "description": "Lifetime spending limit." }, "usage": { "type": "number", "description": "Spent with this key, all time." }, "limit_remaining": { "type": [ "number", "null" ], "description": "limit − usage." }, "daily_limit": { "type": [ "number", "null" ], "description": "Spending limit per UTC day." }, "usage_daily": { "type": "number", "description": "Spent today (UTC)." }, "daily_remaining": { "type": [ "number", "null" ], "description": "daily_limit − usage_daily." }, "monthly_limit": { "type": [ "number", "null" ], "description": "Spending limit per UTC month." }, "usage_monthly": { "type": "number", "description": "Spent this month (UTC)." }, "monthly_remaining": { "type": [ "number", "null" ], "description": "monthly_limit − usage_monthly." }, "daily_token_limit": { "type": [ "integer", "null" ] }, "tokens_daily": { "type": "integer" }, "max_concurrency": { "type": [ "integer", "null" ] }, "in_flight": { "type": "integer" }, "rate_limit": { "type": "object", "required": [ "requests_per_minute" ], "properties": { "requests_per_minute": { "type": "integer" } } }, "reserved": { "type": "number", "description": "Holds of this key's requests in progress." }, "spendable": { "type": "number", "description": "The largest hold the next request can take: the smallest of available and every limit's headroom." }, "daily_reset_at": { "type": "string", "format": "date-time" }, "monthly_reset_at": { "type": "string", "format": "date-time" }, "balance": { "type": "number", "description": "Account balance." }, "available": { "type": "number", "description": "Balance minus every hold in progress." }, "auto_top_up": { "type": "boolean" } }, "additionalProperties": true }, "Generation": { "type": "object", "required": [ "id", "model", "status", "cost", "created_at" ], "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "cancelled" ] }, "streamed": { "type": "boolean" }, "finish_reason": { "type": [ "string", "null" ] }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "usage_source": { "type": [ "string", "null" ], "enum": [ "upstream", "estimated", "none", null ], "description": "estimated: the model did not report usage." }, "cost": { "type": "number", "description": "Charged, in USD (0 for a failed request with no output)." }, "total_cost": { "type": "number", "description": "The request's cost at list price, before any write-off." }, "latency_ms": { "type": [ "integer", "null" ] }, "ttft_ms": { "type": [ "integer", "null" ], "description": "Time to first token." }, "http_status": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "client_app": { "type": [ "string", "null" ], "description": "GET /generations: the product token of the caller's User-Agent (name and major.minor), or null." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "GenerationList": { "type": "object", "required": [ "data", "has_more", "next_before" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "description": "Pass as `before` for the next page; null on the last." } } }, "UsageFigures": { "type": "object", "required": [ "requests", "succeeded", "prompt_tokens", "completion_tokens", "total_tokens", "cached_tokens", "reasoning_tokens", "cost" ], "properties": { "requests": { "type": "integer" }, "succeeded": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "Charged, in USD." } } }, "UsageRow": { "allOf": [ { "$ref": "#/components/schemas/UsageFigures" }, { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "group_by=day." }, "model": { "type": "string", "description": "group_by=model." } } }, { "oneOf": [ { "required": [ "date" ] }, { "required": [ "model" ] } ] } ] }, "UsageReport": { "type": "object", "required": [ "data", "total", "group_by", "scope", "from", "to" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } }, "total": { "$ref": "#/components/schemas/UsageFigures" }, "group_by": { "type": "string", "enum": [ "day", "model" ] }, "scope": { "type": "string", "enum": [ "key", "account" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } } } }