{ "openapi": "3.1.1", "info": { "title": "Heimdallm API", "version": "1", "description": "One OpenAI-compatible API in front of many independent providers. Shapes follow the OpenAI dialect, so an existing SDK reaches the marketplace by changing its base URL. On every request body, an optional member sent as an explicit `null` reads exactly as one that was left out — which is what an SDK that types optional members as nullable sends for a member nobody set — and it reaches no provider. Prices are exact decimal strings and money is never a float. A figure that was not measured is `null`, never `0`." }, "servers": [ { "url": "https://api-staging.heimdallm.com/api/v1", "description": "The public API." } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "inference", "description": "Requests the marketplace routes to a provider and bills per unit consumed. Every one of them needs a key." }, { "name": "catalogue", "description": "What the marketplace serves and how well it is serving it: models, endpoints, providers, measured metrics. No key required." }, { "name": "account", "description": "What the presented key has spent, and what its account has left." }, { "name": "keys", "description": "The provisioning API: creating, listing, reading, editing and revoking keys with a management key. A management key manages keys only — it is refused on every route that spends or reports spend." }, { "name": "files", "description": "The per-account file store: upload once, address by id afterwards. A file belongs to the account its key draws from, and reads as absent to every other account. A file is a temporary handoff: it expires 48 hours after it is stored, and from then on every route answers 404 for it as for a deleted file. Its bytes are held sealed, under a key that lives outside the database and every copy of it, so a backup of the database holds nothing that opens a file more than 50 hours after it was stored. `/chat/completions`, `/responses` and `/messages` name a stored file by its id: the marketplace reads the bytes into the request and sends the provider a data URL, so the provider is never given the id and keeps nothing." }, { "name": "batches", "description": "Requests submitted together and run in the background. Every request of a batch is an ordinary request to its endpoint, routed, held, settled and billed exactly as the same body posted to that route would be; a batch is a way to submit them and carries no discount. The outcome of each is written to a file in the account’s file store when the batch ends." }, { "name": "deposits", "description": "Funding an account. The card rail describes itself here; the x402 rail settles here." }, { "name": "auth", "description": "Obtaining a key. An application sends a person to the marketplace to approve one and trades the resulting code for it, so the key it ends up holding is one the person can see and revoke." }, { "name": "service", "description": "The plane itself." }, { "name": "provider", "description": "The provider dashboard's own reads, published to the same key a customer authenticates with: what the presented key's provider is serving and how it is measured, its earnings and statements, and a request for a fresh pull of its models document. Served only to a key whose account belongs to a provider." } ], "paths": { "/": { "get": { "operationId": "getRoot", "summary": "Name the API", "description": "A liveness read that names the plane. Nothing about the caller is read.", "tags": [ "service" ], "security": [], "responses": { "200": { "description": "The plane answered.", "content": { "application/json": { "example": { "name": "Heimdallm API", "status": "ok" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/chat/completions": { "post": { "operationId": "createChatCompletion", "parameters": [ { "name": "X-OpenRouter-Title", "in": "header", "schema": { "type": "string" }, "description": "App name recorded on the generation. A non-empty value takes precedence over X-Title." }, { "name": "X-Title", "in": "header", "schema": { "type": "string" }, "description": "App name when X-OpenRouter-Title is absent or empty." }, { "name": "X-Session-Id", "in": "header", "schema": { "type": "string" }, "description": "An opaque conversation id (up to 256 characters) keying session affinity: requests carrying the same id prefer the endpoint that served the conversation, keeping its prompt cache warm. On `/chat/completions` the `session_id` body member outranks `prompt_cache_key`, which outranks this header. On `/responses`, `prompt_cache_key` outranks this header. The resolved id is forwarded to the serving endpoint as `x-session-id`." } ], "summary": "Chat completion", "description": "The main inference route. `stream: true` answers with SSE chunks; the chunk before `data: [DONE]` carries `usage`, and `honoured` beside it, wherever the marketplace finished accounting for the exchange, and a caller that left or a reply the accounting could not close sees no usage chunk at all. An error after the stream has opened arrives as a final chunk with an `error` member rather than as a status, because the status is already sent. Where the endpoint reports structured deliberation, `message.reasoning_details` (or, streamed, `delta.reasoning_details` per chunk) carries it beside the flattened `reasoning` string: `reasoning.text` entries with an optional `signature`, `reasoning.summary` entries, and `reasoning.encrypted` entries a provider hands back opaque. Streamed entries share an `index`; a caller concatenating same-index `reasoning.text` fragments and taking whichever fragment carries a `signature` reconstructs the entry a non-streamed reply would have sent whole. The member is absent, never an empty array, wherever the endpoint reported nothing structured. Media a turn generated rides beside the prose: `message.images` carries each picture as an `image_url` part whose URL is a data URL, and `message.audio` carries `data`, `transcript` and the endpoint's own `id` and `expires_at`, arriving fragment by fragment on `delta.audio` when streamed. An endpoint that answers in content parts rather than in those members is read the same way, so a reply that drew a picture and said nothing keeps a `content` of `\"\"` rather than becoming a billed reply with nothing in it.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "example": { "model": "deepseek/deepseek-v4-flash-0731-abliterated", "messages": [ { "role": "user", "content": "Hello" } ], "usage": { "include": true } } } } }, "responses": { "200": { "description": "An OpenAI `chat.completion`, plus `provider` and `usage.cost` in USD. With `stream: true` the body is `text/event-stream` instead.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionReply" }, "example": { "id": "gen-01J8Z0X2QZ", "object": "chat.completion", "created": 1785611388, "model": "deepseek/deepseek-v4-flash-0731-abliterated", "provider": "ImpCC", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 3, "total_tokens": 12, "cost": 0.0000021 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts. A `file` part that names both `file_id` and `file_data`, or a request that names more than 16 stored files, is refused too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family. A `file_id` the account cannot read answers 404 as well, whether the file is another account's, was deleted or has passed its `expires_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The stored files the request names total more than 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503. A request that names a stored file is also refused 503, to be retried, while the key store that stored files are sealed under cannot be reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/completions": { "post": { "operationId": "createCompletion", "parameters": [ { "name": "X-Session-Id", "in": "header", "schema": { "type": "string" }, "description": "An opaque conversation id (up to 256 characters) keying session affinity: requests carrying the same id prefer the endpoint that served the conversation, keeping its prompt cache warm. On `/chat/completions` the `session_id` body member outranks `prompt_cache_key`, which outranks this header. On `/responses`, `prompt_cache_key` outranks this header. The resolved id is forwarded to the serving endpoint as `x-session-id`." } ], "summary": "Text completion", "description": "The older OpenAI text-completions shape, a prompt in and text out, over the same inference core. With `stream: true`, SSE frames carry `text_completion` objects with `choices[].text` deltas, a final chunk carrying `usage` and `honoured`, and `[DONE]`. Committed failures use the same error chunk as chat.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequest" }, "example": { "model": "deepseek/deepseek-v4-flash-0731-abliterated", "prompt": "The capital of France is", "max_tokens": 8 } } } }, "responses": { "200": { "description": "An OpenAI `text_completion`, plus `provider` and `usage.cost`.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"id\":\"gen-01J8Z0X2QZ\",\"object\":\"text_completion\",\"created\":1785611388,\"model\":\"deepseek/deepseek-v4-flash-0731-abliterated\",\"provider\":\"ImpCC\",\"choices\":[{\"index\":0,\"text\":\" Paris.\",\"finish_reason\":\"stop\"}]}\n\ndata: {\"id\":\"gen-01J8Z0X2QZ\",\"object\":\"text_completion\",\"created\":1785611388,\"model\":\"deepseek/deepseek-v4-flash-0731-abliterated\",\"provider\":\"ImpCC\",\"choices\":[],\"usage\":{\"prompt_tokens\":6,\"completion_tokens\":3,\"total_tokens\":9,\"cost\":0.0000016}}\n\ndata: [DONE]\n\n" }, "application/json": { "schema": { "$ref": "#/components/schemas/CompletionReply" }, "example": { "id": "gen-01J8Z0X2QZ", "object": "text_completion", "created": 1785611388, "model": "deepseek/deepseek-v4-flash-0731-abliterated", "provider": "ImpCC", "choices": [ { "index": 0, "text": " Paris.", "finish_reason": "stop" } ], "usage": { "prompt_tokens": 6, "completion_tokens": 3, "total_tokens": 9, "cost": 0.0000016 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/messages": { "post": { "operationId": "createMessage", "parameters": [ { "name": "X-Session-Id", "in": "header", "schema": { "type": "string" }, "description": "An opaque conversation id (up to 256 characters) keying session affinity: requests carrying the same id prefer the endpoint that served the conversation, keeping its prompt cache warm. On `/chat/completions` the `session_id` body member outranks `prompt_cache_key`, which outranks this header. On `/responses`, `prompt_cache_key` outranks this header. The resolved id is forwarded to the serving endpoint as `x-session-id`." } ], "summary": "Anthropic message", "description": "The Anthropic Messages dialect over the same inference core: an Anthropic `/v1/messages` request in, an Anthropic `message` out — or, with `stream: true`, a `text/event-stream` of `message_start`, `content_block_*`, `message_delta` and `message_stop` events. `model` is a marketplace model id, as on `/chat/completions`; a client points `ANTHROPIC_BASE_URL` at this API and sets `ANTHROPIC_MODEL` to one. The Anthropic wire carries no conversation id of its own, so `X-Session-Id` is the only way a client using this dialect takes part in session affinity. The marketplace runs no web search: a `tools` entry that declares Anthropic's hosted search by a dated `type` (`web_search_20250305` and later versions) is refused, and a reply never carries `server_tool_use` or `web_search_tool_result` blocks, citations or `usage.server_tool_use`. A search a client performs is its own function tool, and each call the model makes to it is one `tool_use` block.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, "example": { "model": "deepseek/deepseek-v4-flash-0731-abliterated", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Hello" } ] } } } }, "responses": { "200": { "description": "An Anthropic `message` object, or a `text/event-stream` of Anthropic events when `stream: true`. A picture the model generated is an `image` content block beside the text, its `source` a `base64` one carrying the bytes and their `media_type` — or a `url` one where the endpoint answered with a URL of its own. Streamed, the block arrives whole: one `content_block_start` carrying the picture, then its `content_block_stop`. The dialect's `usage` is a required member stating both counts and a client parsing it rejects an object with a member missing, so a count the endpoint never reported is sent as zero and named in `usage.heimdall.unreported`, which lists every count whose zero nothing measured; a count absent from that list is the endpoint's own figure, and the extension member is absent from a reply whose counts were both reported and names both where no usage document arrived. `message_start` names both of them, nothing being measured when a stream opens, and the final `message_delta` carries the verdict, with `honoured` beside its usage where the request carried members the endpoint's declarations judged. No block of a reply states a search: there is no `server_tool_use` or `web_search_tool_result` block, no citation on a `text` block and no `usage.server_tool_use` member, because the marketplace ran none, and a client that counts searches from those members counts none.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessageReply" }, "example": { "id": "msg_01ABC", "type": "message", "role": "assistant", "model": "deepseek/deepseek-v4-flash-0731-abliterated", "content": [ { "type": "text", "text": "Hello." } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 9, "output_tokens": 3 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts. A `file` part that names both `file_id` and `file_data`, or a request that names more than 16 stored files, is refused too. A `tools` entry whose `type` is a dated hosted web search such as `web_search_20250305` is refused before inference, with the entry's position in the message. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "402": { "description": "The account has no credit left to cover the request. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family. A `file_id` the account cannot read answers 404 as well, whether the file is another account's, was deleted or has passed its `expires_at`. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "408": { "description": "The upstream did not answer within the deadline. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "413": { "description": "The stored files the request names total more than 32 MiB. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "422": { "description": "The reply carried generated audio, which this dialect has no content block for. Ask for the model on `/chat/completions`, whose `message.audio` carries it. After a stream has opened the same refusal arrives as an `error` event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "500": { "description": "The marketplace failed to serve the request. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503. A request that names a stored file is also refused 503, to be retried, while the key store that stored files are sealed under cannot be reached. A request with `stream: true` refused before its stream opened answers in `AnthropicErrorEnvelope`; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/AnthropicErrorEnvelope" } ] } } } } } } }, "/messages/count_tokens": { "post": { "operationId": "countMessageTokens", "summary": "Count message tokens", "description": "The input-token count for a would-be Messages request, which the Claude Code CLI reads to decide when to compact a conversation. Estimated from the request text.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensRequest" }, "example": { "model": "deepseek/deepseek-v4-flash-0731-abliterated", "messages": [ { "role": "user", "content": "Hello" } ] } } } }, "responses": { "200": { "description": "The estimated input token count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicCountTokensReply" }, "example": { "input_tokens": 9 } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/responses": { "post": { "operationId": "createResponse", "parameters": [ { "name": "X-Session-Id", "in": "header", "schema": { "type": "string" }, "description": "An opaque conversation id (up to 256 characters) keying session affinity: requests carrying the same id prefer the endpoint that served the conversation, keeping its prompt cache warm. On `/chat/completions` the `session_id` body member outranks `prompt_cache_key`, which outranks this header. On `/responses`, `prompt_cache_key` outranks this header. The resolved id is forwarded to the serving endpoint as `x-session-id`." } ], "summary": "OpenAI response", "description": "The OpenAI Responses dialect over the same inference core, for clients that speak `/v1/responses` — OpenAI's Codex CLI among them. A Responses request in, a `response` object out, or a `text/event-stream` of `response.*` events when `stream: true`. `model` is a marketplace model id; send the full conversation in `input` each turn. Non-null `previous_response_id` and `background: true` are refused before inference with HTTP 400 (`error.code: 400`, `error.metadata.error_type: invalid_request`); the message names the unsupported member. Omitted/null `previous_response_id` and omitted/false/null `background` select stateless foreground execution. `parallel_tool_calls` is forwarded as the chat member of the same name, an advisory control; response objects report `parallel_tool_calls: true` as a placeholder. `store`, `include` and `metadata` are accepted without effect; responses are not retained server-side. `previous_response_id` reaching inference is always null, so it names no conversation to fall back on; `prompt_cache_key` or `X-Session-Id` supplies affinity without stored-response chaining.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" }, "example": { "model": "deepseek/deepseek-v4-flash-0731-abliterated", "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Hello" } ] } ] } } } }, "responses": { "200": { "description": "An OpenAI `response` object, or a `text/event-stream` of `response.*` events when `stream: true`. Media the model generated rides in the assistant message as further content parts: an `output_image` part whose `image_url` is the picture (a data URL wherever the endpoint handed back bytes), and an `output_audio` part carrying `data`, `transcript` and the endpoint's own `id` and `expires_at`. Streamed, a picture is added and done in one pair of `response.content_part.*` events because it arrives whole, while speech accumulates through `response.output_audio.delta` and `response.output_audio.transcript.delta` and is finished by their `.done` events. The dialect's `usage` states all three counts and a client parsing it rejects an object with a member missing, so a count the endpoint never reported is sent as zero and named in `usage.heimdall.unreported`, which lists every member whose zero nothing measured — `total_tokens` among them wherever one of its terms is missing, a total short a term being unknown rather than smaller. A member absent from that list is the endpoint's own figure; the extension member is absent from a reply whose counts were all reported and names all three where no usage document arrived. `response.completed` carries the same object under the same rule, with `honoured` beside its usage where the request carried members the endpoint's declarations judged. The stream commits on its first event or after one keep-alive period, whichever comes first, so a rejection that arrives before either — an unknown model, no eligible endpoint, an engine refusing a member — is an HTTP error status with an `error` body carrying the public envelope's `metadata`. A failure after the stream has committed sends an `event: error` frame — `{\"type\":\"error\",\"code\":null,\"message\":\"…\",\"param\":null}`, `code` and `param` flat beside `type` rather than nested under an `error` member, matching the Responses API's own streamed error event — and then ends on `response.failed`, whose `response.status` is `failed` and whose `response.error` carries a `code` (`invalid_prompt` for a rejected request, `rate_limit_exceeded`, `context_length_exceeded`, or `server_error` for a failure worth retrying) and the same `message`, which ends with the engine's own diagnostic where one came back.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesReply" }, "example": { "id": "resp_01ABC", "object": "response", "status": "completed", "model": "deepseek/deepseek-v4-flash-0731-abliterated", "output": [ { "id": "resp_01ABC-msg-0", "type": "message", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "Hello.", "annotations": [] } ] } ], "usage": { "input_tokens": 9, "output_tokens": 3, "total_tokens": 12 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts. A `file` part that names both `file_id` and `file_data`, or a request that names more than 16 stored files, is refused too. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "402": { "description": "The account has no credit left to cover the request. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family. A `file_id` the account cannot read answers 404 as well, whether the file is another account's, was deleted or has passed its `expires_at`. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "408": { "description": "The upstream did not answer within the deadline. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "413": { "description": "The stored files the request names total more than 32 MiB. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "500": { "description": "The marketplace failed to serve the request. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503. A request that names a stored file is also refused 503, to be retried, while the key store that stored files are sealed under cannot be reached. A request with `stream: true` refused before its stream opened answers in `ResponsesErrorEnvelope`, whose `code` is null; every other refusal answers in `ErrorEnvelope`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/ResponsesErrorEnvelope" } ] } } } } } } }, "/embeddings": { "post": { "operationId": "createEmbedding", "summary": "Embeddings", "description": "Text, pre-tokenized or multimodal input in, vectors out. An embeddings endpoint never streams, so it publishes no time-to-first-token figure. Media parts route only to endpoints declaring their input modality, source and format; a request with no matching seller receives a no-route response.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsRequest" }, "example": { "model": "baai/bge-m3", "input": "The quick brown fox" } } } }, "responses": { "200": { "description": "An OpenAI embeddings list, plus `id`, `provider` and `usage.cost`. `usage.prompt_tokens_details` carries the per-modality share of `prompt_tokens` (`text_tokens`, `image_tokens`, `audio_tokens`, `video_tokens`, `file_tokens`) and is present only when the input mixed modalities and the endpoint reported the split. Unreported token counts are omitted; explicit zeros are retained.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsReply" }, "example": { "object": "list", "id": "gen-01J8Z0X2QZ", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0123, -0.0456 ] } ], "model": "baai/bge-m3", "provider": "ImpCC", "usage": { "prompt_tokens": 5, "total_tokens": 5, "cost": 1e-7 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/embeddings/models": { "get": { "operationId": "listEmbeddingsModels", "summary": "List embeddings models", "description": "Every served model whose output modality includes `embeddings`, in the `GET /models` summary shape — no second catalogue authority, that list filtered.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "offset", "in": "query", "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "The served embeddings models.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } }, "example": { "data": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ] } } } }, "400": { "description": "`offset` or `limit` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/rerank": { "post": { "operationId": "createRerank", "summary": "Rerank", "description": "A query and a set of documents in, one relevance score per document out. Routed only to models declaring the `rerank` output modality: a model with no scoring head has no relevance to report. Results come back ordered by score, highest first, and cut to `top_n` where one was named. Nothing streams. Billed per token where the endpoint publishes a `prompt` price and reports a count, and per request where it publishes a `request` price; an endpoint publishing neither records the units unpriced rather than billing them at zero.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" }, "example": { "model": "baai/bge-reranker-v2-m3", "query": "What is the capital of France?", "documents": [ "Paris is the capital of France.", "Berlin is the capital of Germany." ], "top_n": 1 } } } }, "responses": { "200": { "description": "The ranking, highest score first, plus `provider` and `usage.cost`. `usage.total_tokens` is omitted where the endpoint reported no count. `usage.search_units` counts one query against up to 100 documents as one unit, `ceil(documents / 100)`, reported for reconciliation against the Cohere search-unit shape rather than as a charge of its own.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankReply" }, "example": { "id": "gen_01J8Z4K6V9", "model": "baai/bge-reranker-v2-m3", "provider": "ImpCC", "results": [ { "index": 0, "relevance_score": 0.987 } ], "usage": { "search_units": 1, "total_tokens": 26, "cost": 4e-7 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/systemone": { "post": { "operationId": "createSystemone", "summary": "Answer typed decisions", "description": "Answer choice, score and noul questions about a supplied state in one inference call. Each question is evaluated against the state. A request that cannot fit an endpoint window is refused rather than truncated.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionsRequest" }, "example": { "model": "convaiinnovations/laya", "state": "Refund the duplicate charge.", "questions": { "dept": { "type": "choice", "instructions": "Which team?", "criteria": { "billing": "Invoices and refunds", "engineering": "Bugs and outages" } } } } } } }, "responses": { "200": { "description": "Typed answers with probabilities and measured input tokens.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionsReply" }, "example": { "id": "gen_01J8Z4K6V9", "model": "convaiinnovations/laya", "provider": "ImpCC", "answers": { "dept": { "type": "choice", "choice": "billing", "probabilities": { "billing": 0.94, "engineering": 0.06 }, "confidence": 0.81 } }, "usage": { "input_tokens": 123, "output_tokens": 0, "cost": 0.0000052 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/benchmark/images": { "post": { "operationId": "collectBenchmarkImage", "summary": "Retain an admitted benchmark image artifact", "description": "Restricted to the benchmark worker identity and its durable task claim. Requires one buffered image (n=1, stream=false). Ordinary API keys cannot use this operation; use /images for image generation. The response acknowledges private artifact retention and contains no media bytes.", "tags": [ "inference" ], "parameters": [ { "name": "X-Heimdall-Probe-Endpoint", "description": "Endpoint bound to the admitted benchmark task. `X-Heimdallm-Probe-Endpoint` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Heimdall-Benchmark-Task", "description": "Single-use durable benchmark task identifier. `X-Heimdallm-Benchmark-Task` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" } } } }, "responses": { "200": { "description": "The paid artifact is retained for scoring.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "artifact" ], "properties": { "id": { "type": "string" }, "artifact": { "type": "string", "enum": [ "retained" ] } } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Benchmark dispatch is unavailable to this caller." }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The task is not eligible for dispatch." }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/benchmark/meshes": { "post": { "operationId": "collectBenchmarkMesh", "summary": "Retain an admitted benchmark mesh artifact", "description": "Restricted to the benchmark worker identity and its durable task claim. Retains one original GLB under the five-minute dispatch deadline. Ordinary API keys cannot use this operation; use /meshes for mesh generation.", "tags": [ "inference" ], "parameters": [ { "name": "X-Heimdall-Probe-Endpoint", "description": "Endpoint bound to the admitted benchmark task. `X-Heimdallm-Probe-Endpoint` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Heimdall-Benchmark-Task", "description": "Single-use durable benchmark task identifier. `X-Heimdallm-Benchmark-Task` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkMeshRequest" } } } }, "responses": { "200": { "description": "The paid artifact is retained for scoring.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "artifact" ], "properties": { "id": { "type": "string" }, "artifact": { "type": "string", "enum": [ "retained" ] } } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Benchmark dispatch is unavailable to this caller." }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The task is not eligible for dispatch." }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/benchmark/videos": { "post": { "operationId": "collectBenchmarkVideo", "summary": "Retain an admitted benchmark video artifact", "description": "Restricted to the benchmark worker identity and its durable task claim. Retains one original silent MP4 under the five-minute dispatch deadline. Ordinary API keys cannot use this operation; use /videos for video generation.", "tags": [ "inference" ], "parameters": [ { "name": "X-Heimdall-Probe-Endpoint", "description": "Endpoint bound to the admitted benchmark task. `X-Heimdallm-Probe-Endpoint` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Heimdall-Benchmark-Task", "description": "Single-use durable benchmark task identifier. `X-Heimdallm-Benchmark-Task` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkVideoRequest" } } } }, "responses": { "200": { "description": "The paid artifact is retained for scoring.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "artifact" ], "properties": { "id": { "type": "string" }, "artifact": { "type": "string", "enum": [ "retained" ] } } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Benchmark dispatch is unavailable to this caller." }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The task is not eligible for dispatch." }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/benchmark/speech": { "post": { "operationId": "collectBenchmarkSpeech", "summary": "Retain an admitted benchmark speech artifact", "description": "Restricted to the benchmark worker identity and its durable task claim. Requires one reference recording and WAVE output. Ordinary API keys cannot use this operation; use /audio/speech for speech synthesis. The response acknowledges private artifact retention and contains no media bytes.", "tags": [ "inference" ], "parameters": [ { "name": "X-Heimdall-Probe-Endpoint", "description": "Endpoint bound to the admitted benchmark task. `X-Heimdallm-Probe-Endpoint` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Heimdall-Benchmark-Task", "description": "Single-use durable benchmark task identifier. `X-Heimdallm-Benchmark-Task` is read as the same header.", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "responses": { "200": { "description": "The paid artifact is retained for scoring.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "artifact" ], "properties": { "id": { "type": "string" }, "artifact": { "type": "string", "enum": [ "retained" ] } } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Benchmark dispatch is unavailable to this caller." }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The task is not eligible for dispatch." }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/images": { "post": { "operationId": "createImageGeneration", "summary": "Image generation, reference contract", "description": "The reference Image API: a prompt in, pictures out, streamed where the caller asks for it. Geometry is named as explicit pixels (`size`), a resolution tier (`resolution`) or an aspect ratio (`aspect_ratio`), and resolves against each endpoint's declared `image_envelope` to the one `WIDTHxHEIGHT` that endpoint is asked for, held against and billed on. A tier no endpoint of the model draws is refused naming the bound it crossed; pixels named beside a tier or a ratio are two answers to one question and are refused with 400. A value outside the domain an endpoint publishes for a member is refused before dispatch rather than by an upstream 400. `input_references` are bounded inline images: the marketplace fetches nothing on a caller's behalf, so an `https:` URL is refused where the caller can still act on it. With `stream: true` the body is a `text/event-stream` carrying one JSON object per `data:` line, and only an endpoint declaring `stream` relays previews — the rest answer buffered, which reaches the caller as the completed image alone. Billing is all or nothing: the charge is computed once from the images that completed and rides out on the reply or on the last `image_generation.completed` event. A render that failed, or whose caller left, settles nothing, and the previews already delivered are the caller's to keep.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" }, "example": { "model": "comfy/flux-1-schnell", "prompt": "A lighthouse in fog", "resolution": "1K", "aspect_ratio": "16:9" } } } }, "responses": { "200": { "description": "The rendered images and what they cost, or the stream that drew them.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"type\":\"image_generation.partial_image\",\"partial_image_index\":0,\"b64_json\":\"iVBORw0KGgo…\"}\n\ndata: {\"type\":\"image_generation.completed\",\"b64_json\":\"iVBORw0KGgo…\",\"media_type\":\"image/png\",\"created\":1785611388,\"usage\":{\"prompt_tokens\":12,\"cost\":0.0021}}\n\ndata: [DONE]\n\n" }, "application/json": { "schema": { "$ref": "#/components/schemas/ImageReply" }, "example": { "created": 1785611388, "data": [ { "b64_json": "iVBORw0KGgo…", "media_type": "image/png" } ], "usage": { "prompt_tokens": 12, "cost": 0.0021 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/images/models": { "get": { "operationId": "listImageModels", "summary": "List image models", "description": "Every served model with an image output, in the terms the image contract uses: the `GET /models` summary narrowed to image models, with `supported_parameters` restated as a typed descriptor per accepted member and a relative `endpoints` URL for the listing that answers per endpoint. `supported_parameters` and `supports_streaming` are the union across the model's live endpoints, which makes them a discovery aid rather than a promise any one endpoint keeps.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "offset", "in": "query", "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "The served image models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageModelsListResponse" }, "example": { "data": [ { "id": "acme/paint-v1", "name": "Acme: Paint V1", "description": "A diffusion model for stills.", "created": 1785611388, "architecture": { "input_modalities": [ "text" ], "output_modalities": [ "image" ] }, "supported_parameters": { "n": { "type": "range", "min": 1, "max": 10 }, "seed": { "type": "boolean" }, "size": { "type": "boolean" } }, "supports_streaming": false, "endpoints": "/api/v1/images/models/acme/paint-v1/endpoints" } ] } } } }, "400": { "description": "`offset` or `limit` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/images/models/{author}/{slug}/endpoints": { "get": { "operationId": "getImageModelEndpoints", "summary": "An image model's endpoints", "description": "Every live endpoint serving one image model: the parameters it accepts as typed descriptors, the provider-specific keys it takes under `provider.options[provider_slug]`, whether it streams natively, and one `pricing` line per unit it charges for. A line is published only where the endpoint declared a price for that unit — an undeclared unit is unknown, never free, so a short `pricing` array is a partial declaration rather than a discount. A model served by nothing answers 200 with an empty `endpoints` array; a model with no image output is not on this route at all and answers 404.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } } ], "responses": { "200": { "description": "The model id and its live image endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageModelEndpointsResponse" }, "example": { "id": "acme/paint-v1", "endpoints": [ { "provider_name": "Epsilon Render", "provider_slug": "epsilon", "provider_id": "7d2e9a40-3c5b-4e1f-8a6d-2b9c0f1e4d3a", "provider_tag": "epsilon", "supported_parameters": { "n": { "type": "range", "min": 1, "max": 10 }, "seed": { "type": "boolean" }, "size": { "type": "boolean" } }, "allowed_passthrough_parameters": [], "supports_streaming": false, "pricing": [ { "billable": "output_image", "unit": "megapixel", "cost_usd": 0.002 } ] } ] } } } }, "404": { "description": "No such image model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/videos": { "post": { "operationId": "createVideoJob", "summary": "Submit a video job", "description": "A prompt in, a job back. Rendering a clip takes longer than a request can be held open, so this route answers `202` with `{ id, polling_url, status }` the moment the job is accepted and the work goes on without the connection. `GET /videos/{jobId}` reports how far it got and `GET /videos/{jobId}/content` hands back the bytes. `prompt` is optional because a model that animates a supplied frame is given the picture instead of the words; a model that needs a prompt refuses its absence itself. Geometry has two interchangeable spellings — `resolution` with `aspect_ratio`, or `size` as `WIDTHxHEIGHT` — and which of them a model serves is published by `GET /videos/models` rather than guessed at here. `frame_images` pins a still to one end of the clip, each carrying the `frame_type` that says which end, because an array of one carries no position that could. `input_references` conditions the generation without being a frame of it; an image reference is the shape every engine takes, while audio and video references reach only the endpoints declaring them. A supplied asset is inline base64 and nothing else, the rule the still rail is held to: the marketplace fetches nothing on a caller's behalf, so a URL it would have to reach is refused with 400 before a job exists. `callback_url` must be HTTPS: the notification names a job an API key can read, and a cleartext hop would publish it. Billed per second of delivered video at the endpoint's declared rate, tiered by resolution where it declares a tier; frame area is geometry the request chose and not a quantity anybody is charged for. The clip is deleted 10 minutes after its first delivery, and an undelivered one when the job's window closes, once no response is still reading it, so the marketplace retains nothing past the delivery window.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJobRequest" }, "example": { "model": "comfy/wan-2-2-t2v", "prompt": "A paper boat crossing a puddle", "duration": 8, "resolution": "720p", "aspect_ratio": "16:9" } } } }, "responses": { "202": { "description": "The job was accepted. `status` is where it starts and `polling_url` is where to read it next; neither is a claim that anything has been rendered or charged yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" }, "example": { "id": "vjob_2f1c4a7e9b0d46538a1c7e5f3b204d61", "polling_url": "/api/v1/videos/vjob_2f1c4a7e9b0d46538a1c7e5f3b204d61", "status": "pending" } } } }, "400": { "description": "The body did not parse, a parameter is outside the range the API accepts — a resolution, aspect ratio or frame role outside the contract’s own enum, a `size` that is not `WIDTHxHEIGHT`, an asset that is not an inline base64 data URI, or a `callback_url` that is not HTTPS — or the assets the job names cannot be served as asked. `frame_images` and `input_references` are folded into one list before dispatch, so the two together carry at most 3 items and at most 20 MiB of decoded bytes; a job over either bound is refused naming it. A combination of control roles no endpoint of the model loads in one render is refused naming the sets it does serve, which `reference_inputs.video.control_sets` on `GET /models/{author}/{slug}/endpoints` lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/videos/{jobId}": { "get": { "operationId": "getVideoJob", "summary": "Poll a video job", "description": "How far a job got. `pending` is accepted and not yet started, `in_progress` is rendering, and the other four are terminal: `completed` produced its clips, which stay fetchable until the job's window closes, or for 10 minutes after their first delivery, `failed` carries the reason in `error`, `cancelled` was stopped before it produced one, and `expired` is a job whose delivery window closed with nothing fetched from it; a job fetched from, even in part, stays `completed` after its window closes, with no content left to fetch. A member appears once there is something to say — `generation_id` once the job has been processed and the generation it bills through exists, `unsigned_urls` once there is content to fetch, `clip_durations_seconds` alongside it naming what each clip actually came to, `usage` once it was charged, which is on completion or on a `marketplace` failure whose dispatch was charged and never stored its result — so an absent member is a fact not yet established rather than an empty one. `usage.cost` is null where the units the job consumed carry no declared price: a clip nothing priced is recorded unpriced and flagged, never reported as free. The job row outlives its clip, so a job polled after delivery still answers what it was, and what it cost, with the bytes already gone. `fault` appears only on a `failed` job whose failure this platform caused rather than the endpoint, and its absence is the ordinary case: the reason the job carries is the answer an endpoint gave.", "tags": [ "inference" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job id `POST /videos` returned, of the form `vjob_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^vjob_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The job as it stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" }, "example": { "id": "vjob_2f1c4a7e9b0d46538a1c7e5f3b204d61", "polling_url": "/api/v1/videos/vjob_2f1c4a7e9b0d46538a1c7e5f3b204d61", "status": "completed", "generation_id": "gen-01J8Z0X2QZ", "unsigned_urls": [ "/api/v1/videos/vjob_2f1c4a7e9b0d46538a1c7e5f3b204d61/content?index=0" ], "clip_durations_seconds": [ 4 ], "usage": { "cost": 1.12 } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such job on the key’s own account. Identical whether the id is unknown, malformed, or names a job another account submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/videos/{jobId}/content": { "get": { "operationId": "getVideoJobContent", "summary": "Download a generated clip", "description": "The clip itself, as `video/mp4` bytes. `index` selects which clip of a job that produced several and defaults to the first. A response that starts at the first byte and is written through the last — a whole `200`, or a `206` for `bytes=0-` — is its delivery; a range that starts later is not. Delivery does not remove the clip: it stays readable, whole or by range, for 10 minutes from its first delivery, and a fetch started after that answers 410 — a caller that needs to keep it keeps what this route gave it. Two fetches under way at once both complete. Nothing cuts a response short: the clip is never removed while a response is reading it, so a slow download started inside the window finishes. A download that breaks off leaves the clip in place, and `Range: bytes=N-` fetches the rest. `HEAD` reports the length and delivers nothing. A clip never delivered stays readable until its job's window closes, 24 hours from the render finishing; it is then removed, and a job nobody fetched from becomes `expired` while one fetched from, even in part, stays `completed`. Between them those two rules are why the job store retains nothing past the delivery window, which is what lets a ZDR-approved provider's video endpoint stay ZDR. A job that has not completed has no content to serve and answers 409, which is a different answer from one whose content is gone.", "tags": [ "inference" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job id `POST /videos` returned, of the form `vjob_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^vjob_[0-9a-f]{32}$" } }, { "name": "index", "in": "query", "description": "Which clip of a job that returned several. The first one by default.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "Range", "in": "header", "description": "One byte range, as `bytes=first-last`, `bytes=first-` or `bytes=-count`; the unit is read in any case. A response that starts at the first byte and is written through the last is a delivery, so `bytes=0-` delivers like a whole fetch and a range starting later never does. Any other form, several ranges included, is ignored and the whole asset is served.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The clip, as the container the provider produced it in. The body is the video itself, with no JSON envelope.", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "The requested range of the asset. It is not a delivery and removes nothing.", "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "The bytes served, as `bytes first-last/size`." } }, "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`index` is not a whole number at or above zero.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such job on the key’s own account, or the job produced no clip at that index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The job has not completed, so there is no content to serve yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "The clip is gone: its grace after delivery ended, or it went undelivered until the job expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "416": { "description": "The range starts past the final byte. `Content-Range` states the asset’s length as `bytes */size`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "The bytes served, as `bytes first-last/size`." } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/videos/models": { "get": { "operationId": "listVideoModels", "summary": "List video models", "description": "Every served model with a video output, in the terms the video contract uses. Each `supported_*` member is the union of what the model's live endpoints declare, which makes it a discovery aid rather than a promise any one endpoint keeps, and it is null where none of them declares it — undeclared, not empty, because a model whose endpoints publish no duration list is a model whose durations nobody stated rather than one that serves none. `pricing_skus` publishes the per-second rate under `duration_seconds`, and the same name suffixed by a resolution for each tier priced separately, so a tiered price is one meter at several rates rather than several units. A listing carrying only suffixed names declares no untiered rate, which is a partial declaration and not a free tier. `allowed_passthrough_parameters` names the keys an endpoint accepts under `provider.options`; `parameter_offers` publishes direct request controls declared by sellers.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "offset", "in": "query", "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "The served video models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModelsListResponse" }, "example": { "data": [ { "id": "comfy/wan-2-2-t2v", "canonical_slug": "comfy/wan-2-2-t2v", "name": "Comfy: Wan 2.2 T2V", "created": 1785611388, "description": "A diffusion model for short clips.", "hugging_face_id": null, "supported_resolutions": [ "480p", "720p" ], "supported_aspect_ratios": [ "16:9", "9:16" ], "supported_sizes": null, "supported_durations": [ 4, 8 ], "supported_frame_images": [ "first_frame" ], "supported_reference_roles": { "image": [ "first_frame" ], "video": [ "reference", "depth" ] }, "generate_audio": false, "seed": true, "pricing_skus": { "duration_seconds_480p": "0.068", "duration_seconds_720p": "0.14" }, "allowed_passthrough_parameters": [] } ] } } } }, "400": { "description": "`offset` or `limit` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes": { "post": { "operationId": "createMeshJob", "summary": "Submit a mesh job", "description": "A prompt or a set of views in, a job back. Generating a mesh takes far longer than a request can be held open — sampling a dense surface is minutes of card time, and decimating it to a target is the cheap part — so this route answers `202` with `{ id, polling_url, status }` the moment the job is accepted and the work goes on without the connection. `GET /meshes/{jobId}` reports how far it got and `GET /meshes/{jobId}/content` hands back the GLB. One of `prompt` and `input_references` has to be present: an ask naming neither builds nothing, and an image-only endpoint refuses a prompt beside a supplied view. A view is sent inline as base64; at most four, because more views are a different rig and a different model. `target_faces` is a ceiling rather than a target — a decimator lands at or below it — and what an endpoint generates is its `mesh_envelope`, which `GET /meshes/models` publishes. `generate_texture` bakes an image into the same container; leaving it out leaves the choice to the endpoint. `callback_url` must be HTTPS: the notification names a job an API key can read, and a cleartext hop would publish it. Billed per delivered mesh at the endpoint's declared rate, tiered where it declares a tier; the face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. The asset is deleted 10 minutes after its first delivery, and an undelivered one when the job's window closes, once no response is still reading it, so the marketplace retains nothing past the delivery window.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshJobRequest" }, "example": { "model": "comfy/pixal3d", "prompt": "A ceramic teapot with a bamboo handle", "target_faces": 40000, "generate_texture": true } } } }, "responses": { "202": { "description": "The job was accepted. `status` is where it starts and `polling_url` is where to read it next; neither is a claim that anything has been generated or charged yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshJob" }, "example": { "id": "mjob_8d3b06a1f4c7425e9f2a1d5b7c3e0846", "polling_url": "/api/v1/meshes/mjob_8d3b06a1f4c7425e9f2a1d5b7c3e0846", "status": "pending" } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts — a request naming neither a prompt nor a view, a `target_faces` outside the contract’s own bounds, more than four views, or a `callback_url` that is not HTTPS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes/{jobId}": { "get": { "operationId": "getMeshJob", "summary": "Poll a mesh job", "description": "How far a job got. `pending` is accepted and not yet started, `in_progress` is generating, and the other four are terminal: `completed` produced its assets, which stay fetchable until the job's window closes, or for 10 minutes after their first delivery, `failed` carries the reason in `error`, `cancelled` was stopped before it produced one, and `expired` is a job whose delivery window closed with nothing fetched from it; a job fetched from, even in part, stays `completed` after its window closes, with no content left to fetch. A member appears once there is something to say — `generation_id` once the job has been processed and the generation it bills through exists, `unsigned_urls` once there is content to fetch, `meshes` alongside it naming what each asset actually came to, `usage` once it was charged, which is on completion or on a `marketplace` failure whose dispatch was charged and never stored its result — so an absent member is a fact not yet established rather than an empty one. Every figure under `meshes` is read off the GLB itself rather than taken from what the endpoint reported, so a face count here is a measurement and never a claim. `usage.cost` is null where the units the job consumed carry no declared price: a mesh nothing priced is recorded unpriced and flagged, never reported as free. The job row outlives its asset, so a job polled after delivery still answers what it was, and what it cost, with the bytes already gone. `fault` appears only on a `failed` job whose failure this platform caused rather than the endpoint, and its absence is the ordinary case: the reason the job carries is the answer an endpoint gave.", "tags": [ "inference" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job id `POST /meshes` returned, of the form `mjob_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^mjob_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The job as it stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshJob" }, "example": { "id": "mjob_8d3b06a1f4c7425e9f2a1d5b7c3e0846", "polling_url": "/api/v1/meshes/mjob_8d3b06a1f4c7425e9f2a1d5b7c3e0846", "status": "completed", "generation_id": "gen-01J8Z0X2QZ", "unsigned_urls": [ "/api/v1/meshes/mjob_8d3b06a1f4c7425e9f2a1d5b7c3e0846/content?index=0" ], "meshes": [ { "faces": 38412, "vertices": 19317, "has_texture": true, "bounds": { "min": [ -0.5, 0, -0.5 ], "max": [ 0.5, 0.82, 0.5 ] } } ], "usage": { "cost": 0.4 } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such job on the key’s own account. Identical whether the id is unknown, malformed, or names a job another account submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes/{jobId}/content": { "get": { "operationId": "getMeshJobContent", "summary": "Download a generated mesh", "description": "The mesh itself, as `model/gltf-binary` bytes, with any baked texture inside the same container. `index` selects which asset of a job that produced several and defaults to the first. A response that starts at the first byte and is written through the last — a whole `200`, or a `206` for `bytes=0-` — is its delivery; a range that starts later is not. Delivery does not remove the asset: it stays readable, whole or by range, for 10 minutes from its first delivery, and a fetch started after that answers 410 — a caller that needs to keep it keeps what this route gave it. Two fetches under way at once both complete. Nothing cuts a response short: the asset is never removed while a response is reading it, so a slow download started inside the window finishes. A download that breaks off leaves the asset in place, and `Range: bytes=N-` fetches the rest. `HEAD` reports the length and delivers nothing. An asset never delivered stays readable until its job's window closes, 24 hours from the generation finishing; it is then removed, and a job nobody fetched from becomes `expired` while one fetched from, even in part, stays `completed`. Between them those two rules are why the job store retains nothing past the delivery window, which is what lets a ZDR-approved provider's mesh endpoint stay ZDR. A job that has not completed has no content to serve and answers 409, which is a different answer from one whose content is gone.", "tags": [ "inference" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job id `POST /meshes` returned, of the form `mjob_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^mjob_[0-9a-f]{32}$" } }, { "name": "index", "in": "query", "description": "Which asset of a job that returned several. The first one by default.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "Range", "in": "header", "description": "One byte range, as `bytes=first-last`, `bytes=first-` or `bytes=-count`; the unit is read in any case. A response that starts at the first byte and is written through the last is a delivery, so `bytes=0-` delivers like a whole fetch and a range starting later never does. Any other form, several ranges included, is ignored and the whole asset is served.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The mesh, as a binary glTF container. The body is the asset itself, with no JSON envelope.", "content": { "model/gltf-binary": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "The requested range of the asset. It is not a delivery and removes nothing.", "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "The bytes served, as `bytes first-last/size`." } }, "content": { "model/gltf-binary": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`index` is not a whole number at or above zero.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such job on the key’s own account, or the job produced no mesh at that index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The job has not completed, so there is no content to serve yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "The mesh is gone: its grace after delivery ended, or it went undelivered until the job expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "416": { "description": "The range starts past the final byte. `Content-Range` states the asset’s length as `bytes */size`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "The bytes served, as `bytes first-last/size`." } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes/{jobId}/refinement": { "delete": { "operationId": "cancelMeshRefinement", "tags": [ "inference" ], "summary": "Stop mesh repair and preserve the generated asset", "description": "Requests cancellation of optional marketplace repair. Generation continues if still pending. The original and last validated repair remain downloadable. Poll the job until repair is terminal.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The job id `POST /meshes` returned, of the form `mjob_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^mjob_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Cancellation request recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cancelled" ], "properties": { "cancelled": { "type": "boolean" } } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes/refinement/models": { "get": { "operationId": "listMeshRefinementModels", "tags": [ "inference" ], "summary": "List available mesh repair models and machine pricing", "description": "Lists live image-input models with tool support when repair is enabled, and the exact USD rate for its medium machine.", "responses": { "200": { "description": "Deployment availability, exact machine price, and live vision models with tool support.", "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled", "machine", "data" ], "properties": { "enabled": { "type": "boolean" }, "machine": { "type": "object", "required": [ "size", "vcpus", "memory_gib", "price_per_minute_usd" ], "properties": { "size": { "type": "string", "enum": [ "m" ] }, "vcpus": { "type": "integer" }, "memory_gib": { "type": "integer" }, "price_per_minute_usd": { "type": "string" } } }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/meshes/models": { "get": { "operationId": "listMeshModels", "summary": "List mesh models", "description": "Every served model with a mesh output, in the terms the mesh contract uses. Each declared member is the union of what the model's live endpoints state, which makes it a discovery aid rather than a promise any one endpoint keeps, and it is null where none of them declares it — undeclared, not empty, because a model whose endpoints publish no texture capability is a model nobody stated it for rather than one that bakes none. `mesh_envelope` is the widest envelope across those endpoints — the lowest floor and the highest ceiling any of them serves — because a request is routed to whichever endpoint serves it. `pricing_skus` publishes the per-mesh rate under `mesh_output`, and the same name suffixed for each condition an endpoint prices separately, so a tiered price is one meter at several rates rather than several units. A listing carrying only suffixed names declares no untiered rate, which is a partial declaration and not a free tier. `allowed_passthrough_parameters` names the keys an endpoint accepts under `provider.options`; `parameter_offers` publishes direct request controls declared by sellers.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "offset", "in": "query", "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "The served mesh models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshModelsListResponse" }, "example": { "data": [ { "id": "comfy/pixal3d", "canonical_slug": "comfy/pixal3d", "name": "Comfy: Pixal3D", "created": 1785611388, "description": "A latent-set model for single-object meshes.", "hugging_face_id": null, "mesh_envelope": { "max_faces": 150000, "min_faces": 4000, "texture": true }, "supported_inputs": [ "text", "image" ], "reference_inputs": { "formats": { "image": [ "image/png", "image/jpeg" ] }, "max_items": 4 }, "generate_texture": true, "seed": true, "pricing_skus": { "mesh_output": "0.35" }, "allowed_passthrough_parameters": [] } ] } } } }, "400": { "description": "`offset` or `limit` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/audio/speech": { "post": { "operationId": "createSpeech", "summary": "Speech", "description": "Text in, audio bytes out. The body is the recording itself, in the codec `response_format` named, with no JSON envelope; `X-Generation-Id` and `X-Provider-Name` are sent on it as on every other inference route, and the usage is read back from `GET /generation`. Routed only to endpoints declaring a `speech` output, and only to ones declaring the voice, the codec and the speed asked for. A voice no endpoint of the model declares is resolved before routing rather than refused outright: where the model's endpoints offer one voice between them — an endpoint offers the voice it spells `default`, or its sole voice where it declares exactly one — that voice is routed on and named back in `X-Heimdall-Voice`, and where they offer more than one or none, the request is a 400 listing every voice the model is served with. Substituting further would pick between voices that do not sound alike and bill the caller for the one they did not choose. `GET /speech/models` publishes those voices ahead of the call. Billed per CHARACTER of `input`, counted by the marketplace from the request; an endpoint publishing no character price records the characters unpriced rather than billing them at zero. Seconds of audio produced are published as a figure and billed by nothing. A provider that streams its audio has the body relayed as it arrives.", "tags": [ "inference" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "model", "input", "file" ], "description": "Provider-defined form fields accept plain text or JSON literals for numbers, booleans, arrays and objects. Quote a numeric-looking string as a JSON string.", "properties": { "model": { "type": "string" }, "input": { "type": "string", "maxLength": 15000 }, "file": { "type": "string", "format": "binary", "description": "Voice sample, at most 5 MiB. WAV, MP3, FLAC, OGG, M4A or WebM." }, "transcript": { "type": "string", "maxLength": 15000 }, "voice": { "type": "string" }, "response_format": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "max_new_tokens": { "type": "integer", "minimum": 1, "maximum": 4096 }, "instructions": { "type": "string", "maxLength": 15000 }, "provider": { "type": "string", "description": "JSON-encoded provider preferences." }, "user": { "type": "string" } }, "additionalProperties": true } }, "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" }, "example": { "model": "openbmb/voxcpm2", "input": "The sky above the port was the color of television.", "voice": "alloy", "response_format": "wav" } } } }, "responses": { "200": { "description": "The encoded audio, with the codec's own content type: `audio/mpeg` for `mp3`, `audio/wav` for `wav`, `audio/pcm` for `pcm`, `audio/ogg; codecs=opus` for `opus`, `audio/flac` for `flac`, `audio/aac` for `aac`, `audio/basic` for `mulaw` and `audio/x-alaw-basic` for `alaw`. No `Content-Length`: an endpoint that encodes as it decodes has no length to declare.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } }, "X-Heimdallm-Voice": { "description": "Sent beside `X-Heimdall-Voice` with the same value; either spelling may be read.", "schema": { "type": "string" } }, "X-Heimdall-Voice": { "description": "The voice that spoke, sent only where it is not the one `voice` named. Its absence is not a claim that the asked-for voice spoke: a request naming no voice is served by the endpoint's own default, which the marketplace has no name for.", "schema": { "type": "string" } }, "X-Heimdallm-Unhonoured": { "description": "Sent beside `X-Heimdall-Unhonoured` with the same value; either spelling may be read.", "schema": { "type": "string" } }, "X-Heimdall-Unhonoured": { "description": "Members of the request that did not reach the engine, comma-separated: the verdict every other rail writes into its reply document, on the one rail whose reply is the recording itself. `input`, `voice`, `response_format`, `speed` and `instructions` always reach it; anything else is forwarded only where the serving endpoint declares that name in `supported_parameters`. Absent where nothing was dropped.", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The body did not parse, a parameter is outside the range the API accepts, or `voice` names a voice no endpoint of the model declares and the model's endpoints offer no single substitute — that error lists the voices the model is served with under `metadata.declared_voices`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/speech/models": { "get": { "operationId": "listSpeechModels", "summary": "List speech models", "description": "Every served model whose output modality includes `speech`, in the `GET /models` summary shape — no second catalogue authority, that list filtered. Each entry carries a `speech` object holding the union of what its live endpoints declare: the voices, the codecs and the widest speed range. The union is what the marketplace can be asked for somewhere, not what any one endpoint keeps; `links.details` reaches the endpoints listing, where each endpoint publishes its own `speech_envelope`. This is the route to read before sending `voice`, because a client written against the reference contract knows only that contract's own eleven names.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "offset", "in": "query", "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } } ], "responses": { "200": { "description": "The served speech models.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } }, "example": { "data": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ] } } } }, "400": { "description": "`offset` or `limit` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/audio/transcriptions": { "post": { "operationId": "createTranscription", "summary": "Transcription", "description": "Audio in, text out, on either of two bodies: `multipart/form-data`, with the audio as the `file` part and everything else a form field, capped at 25 MiB; or JSON, with the audio as base64 bytes under `input_audio`, for an upload over that cap. Billed by exactly one unit per call: seconds of audio for a duration-priced endpoint, tokens for one priced by them. Nothing streams.", "tags": [ "inference" ], "requestBody": { "required": true, "description": "Form fields with the audio in a `file` part, or JSON with `input_audio`. Provider-defined multipart fields accept plain text or JSON literals for numbers, booleans, arrays and objects. Quote a numeric-looking string as a JSON string.", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TranscriptionRequest" }, "example": { "model": "openai/whisper-large-v3", "response_format": "verbose_json" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionRequest" }, "example": { "model": "openai/whisper-large-v3", "input_audio": { "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…", "format": "wav" } } } } }, "responses": { "200": { "description": "`response_format: verbose_json` adds `task`, `duration`, `language`, `segments` and `words` (segments and words carry `speaker` where the endpoint returns diarization). `usage.seconds` is whole seconds, rounded up from what the endpoint measured, which is the unit a duration price is charged in; `duration` is that measurement itself and stays fractional. Unreported `usage` figures are omitted; an explicitly measured zero is retained.", "headers": { "X-Generation-Id": { "description": "The id this call is recorded under, set before anything can fail.", "schema": { "type": "string" } }, "X-Provider-Name": { "description": "The provider that served the request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionReply" }, "example": { "text": "The quick brown fox jumps over the lazy dog.", "model": "openai/whisper-large-v3", "provider": "ImpCC", "usage": { "seconds": 4, "cost": 0.000008 } } } } }, "400": { "description": "The body did not parse, or a parameter is outside the range the API accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The account has no credit left to cover the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family_variants` lists the served ids in that family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "408": { "description": "The upstream did not answer within the deadline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The audio file is larger than the 25 MiB the multipart body accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The endpoint that was routed to failed, and no other endpoint could serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "No live endpoint can serve the request: none is declared for the model, or every one of them was excluded by something the request asked for. A 503 that carries `Retry-After` and `X-Should-Retry: true` is the marketplace restarting, and repeating the request is correct. The same restart reaches a stream that has already begun as an in-band error carrying 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/catalogue": { "get": { "operationId": "getCatalogue", "summary": "Read the complete catalogue", "description": "Models, families and providers from one consistent database view, bounded to 2 MiB. An ETag identifies the complete JSON representation. If-None-Match avoids transferring an unchanged body. A cached response expires five seconds after publication, in addition to its bounded refresh duration; unavailable refreshes return 503.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "description": "Content validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The complete public catalogue. Array entries have the corresponding list route shapes.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Content validator." } }, "content": { "application/json": { "example": { "models": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ], "families": [], "providers": [] } } } }, "304": { "description": "The current representation matches If-None-Match; no response body." }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The catalogue is unavailable or exceeds the response size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models": { "get": { "operationId": "listModels", "summary": "List models", "description": "Every model with at least one live endpoint, newest first then by id, narrowed by every filter present. `pricing` is a representative live endpoint's, selected by declared prompt-token price, then completion-token price, then endpoint id, with unknown token prices last; it does not identify the cheapest image or video tariff. The order is stable under the default sort, so stepping `offset` walks the whole filtered list and a page shorter than `limit` is the last one. A filter naming a figure this catalogue does not compute (`category`, `arch`, `distillable`, and the six index bounds) is accepted rather than rejected, but a filter the marketplace cannot evaluate cannot be satisfied: the request answers `\"data\": []` with `unsupported_filters` naming which of these it sent, whatever every other filter present would otherwise have matched — `?context=8192&category=roleplay` answers empty, not the models `context` alone would have kept. `unsupported_filters` is absent when every filter sent is one this catalogue computes.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "family", "in": "query", "description": "Restrict the list to one family id.", "schema": { "type": "string", "example": "deepseek/deepseek-v4-flash-0731" } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match against the model id or its display name.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "category", "in": "query", "description": "Unsupported: this catalogue computes no curated usage category. Reported in `unsupported_filters`.", "schema": { "type": "string" } }, { "name": "supported_parameters", "in": "query", "description": "Comma-separated parameter names. A model matches when every named parameter is declared by at least one of its live endpoints, not necessarily the same one.", "schema": { "type": "string", "example": "tools,structured_outputs" } }, { "name": "input_modalities", "in": "query", "description": "Comma-separated modalities the model must accept, all of them (`text`, `image`, `audio`, `video`, `file`).", "schema": { "type": "string", "example": "text,image" } }, { "name": "output_modalities", "in": "query", "description": "Comma-separated modalities the model must produce, all of them (`text`, `image`, `video`, `audio`, `speech`, `transcription`, `embeddings`, `rerank`, `decisions`, `mesh`).", "schema": { "type": "string", "example": "text" } }, { "name": "context", "in": "query", "description": "Minimum context length in tokens, against the model's own declared window.", "schema": { "type": "integer", "minimum": 0, "example": 32768 } }, { "name": "min_price", "in": "query", "description": "Minimum prompt price. At least one live endpoint must price at or above this. A decimal USD-per-million-token string such as \"1.50\", compared exactly against the endpoint's declared per-token price. Never a float. An endpoint publishing no rate per token satisfies neither bound.", "schema": { "type": "string", "example": "0.10" } }, { "name": "max_price", "in": "query", "description": "Maximum prompt price. At least one live endpoint must price at or below this. A decimal USD-per-million-token string such as \"1.50\", compared exactly against the endpoint's declared per-token price. Never a float. An endpoint publishing no rate per token satisfies neither bound.", "schema": { "type": "string", "example": "1.00" } }, { "name": "min_output_price", "in": "query", "description": "Minimum completion price. At least one live endpoint must price at or above this. A decimal USD-per-million-token string such as \"1.50\", compared exactly against the endpoint's declared per-token price. Never a float. An endpoint publishing no rate per token satisfies neither bound.", "schema": { "type": "string", "example": "0.10" } }, { "name": "max_output_price", "in": "query", "description": "Maximum completion price. At least one live endpoint must price at or below this. A decimal USD-per-million-token string such as \"1.50\", compared exactly against the endpoint's declared per-token price. Never a float. An endpoint publishing no rate per token satisfies neither bound.", "schema": { "type": "string", "example": "4.00" } }, { "name": "providers", "in": "query", "description": "Comma-separated provider slugs. At least one live endpoint must belong to one of them.", "schema": { "type": "string", "example": "impcc" } }, { "name": "model_authors", "in": "query", "description": "Comma-separated authors, matched against the model's own declared author.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "zdr", "in": "query", "description": "`true` restricts the list to models with at least one endpoint the ZDR fold keeps (see `GET /endpoints/zdr`). `false` is accepted and filters nothing.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "region", "in": "query", "description": "Comma-separated country codes or datacenter regions. At least one live endpoint must declare a matching datacenter.", "schema": { "type": "string", "example": "US" } }, { "name": "arch", "in": "query", "description": "Unsupported: this catalogue declares no architecture classification beyond modality. Reported in `unsupported_filters`.", "schema": { "type": "string" } }, { "name": "distillable", "in": "query", "description": "Unsupported: this catalogue declares no distillation licence flag. Reported in `unsupported_filters`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Order of the returned list. `newest` (default) and `oldest` order by release date; the rest need a computed figure this catalogue has.", "schema": { "type": "string", "enum": [ "newest", "oldest", "price-low-to-high", "price-high-to-low", "context-high-to-low" ], "default": "newest" } }, { "name": "min_age_days", "in": "query", "description": "Minimum age in days since the model's declared release date.", "schema": { "type": "integer", "minimum": 0, "example": 30 } }, { "name": "max_age_days", "in": "query", "description": "Maximum age in days since the model's declared release date.", "schema": { "type": "integer", "minimum": 0, "example": 365 } }, { "name": "min_tool_success_rate", "in": "query", "description": "Minimum measured `tool_call_success_1d`, 0-100. At least one live endpoint must clear its sample gate and meet the bound; a null figure matches neither bound.", "schema": { "type": "number", "minimum": 0, "maximum": 100, "example": 85 } }, { "name": "max_tool_success_rate", "in": "query", "description": "Maximum measured `tool_call_success_1d`, 0-100. At least one live endpoint must clear its sample gate and meet the bound; a null figure matches neither bound.", "schema": { "type": "number", "minimum": 0, "maximum": 100, "example": 100 } }, { "name": "min_intelligence_index", "in": "query", "description": "Unsupported: this catalogue computes no intelligence index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "max_intelligence_index", "in": "query", "description": "Unsupported: this catalogue computes no intelligence index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "min_coding_index", "in": "query", "description": "Unsupported: this catalogue computes no coding index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "max_coding_index", "in": "query", "description": "Unsupported: this catalogue computes no coding index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "min_agentic_index", "in": "query", "description": "Unsupported: this catalogue computes no agentic index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "max_agentic_index", "in": "query", "description": "Unsupported: this catalogue computes no agentic index. Reported in `unsupported_filters`.", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "description": "Page size. Without it the whole list is returned.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Valid on its own, without `limit`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "The served catalogue, filtered and paginated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "unsupported_filters": { "type": "array", "items": { "type": "string" }, "description": "Present only when the request named a filter this catalogue does not compute; `data` is then always empty." } } }, "example": { "data": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ] } } } }, "400": { "description": "A parameter is missing, repeated, or outside the range or enum this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/count": { "get": { "operationId": "countModels", "summary": "Count served models", "description": "The size of the complete unfiltered model list across all modalities, before pagination.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "The number of served models.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "count" ], "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0 } } } } }, "example": { "data": { "count": 2 } } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/user": { "get": { "operationId": "listModelsForUser", "summary": "List models for the authenticated account", "description": "The complete unfiltered model list `GET /models` serves, narrowed by the presented key's own account preferences. The one stored preference this route currently reads is the workspace's default ZDR routing preference (`provider.zdr`'s stored default): when it is `true`, every model with no live endpoint the ZDR fold keeps is omitted. An account with no such preference, or one set to `false`, sees the same list `GET /models` serves.", "tags": [ "catalogue" ], "responses": { "200": { "description": "The account's own model list.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } }, "example": { "data": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ] } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}/{slug}": { "get": { "operationId": "getModel", "summary": "Get a model", "description": "One served model, with the same public object as an entry in `GET /models`. Only active models with a live endpoint belonging to an approved provider are served.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } } ], "responses": { "200": { "description": "The served model.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ModelSummary" } } }, "example": { "data": { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } } } } }, "404": { "description": "No such served model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/model/{author}/{slug}": { "get": { "operationId": "getModelAlias", "summary": "Get a model", "description": "One served model, with the same public object as an entry in `GET /models`. Only active models with a live endpoint belonging to an approved provider are served.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } } ], "responses": { "200": { "description": "The served model.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ModelSummary" } } }, "example": { "data": { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } } } } }, "404": { "description": "No such served model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}": { "get": { "operationId": "retrieveModel", "summary": "Retrieve a model (SDK-compatible)", "description": "The single percent-encoded path segment the OpenAI Node and Python SDKs request from `models.retrieve(id)` — `models.retrieve(\"acme/base-1\")` requests `/models/acme%2Fbase-1`. Resolved through the same catalogue projection and the same visibility rules as `GET /models/{author}/{slug}`, and answered as the bare object those SDKs parse (`id`, `created`, `object: \"model\"`, `owned_by`) rather than the `{ data: model }` envelope that route keeps. `owned_by` equals `author`; every other field is the same as the matching entry in `GET /models`.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The whole model id, percent-encoded as one path segment (`author%2Fslug`) rather than split across two.", "schema": { "type": "string", "example": "deepseek%2Fdeepseek-v4-flash-0731-abliterated" } } ], "responses": { "200": { "description": "The served model, as a bare object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkModel" }, "example": { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null, "object": "model", "owned_by": "deepseek" } } } }, "404": { "description": "No such served model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}/{slug}/endpoints": { "get": { "operationId": "getModelEndpoints", "summary": "A model and the endpoints serving it", "description": "The model with every live endpoint on it, each carrying its declared limits and its measured metrics. `uptime_last_5m` and `uptime_last_30m` count success/error attempts under the ten-sample gate. `latency_last_30m` aliases the 30-minute time-to-first-token percentiles in seconds. `throughput_last_30m` uses the same observation rules as daily throughput and its own five-stream gate; its descending performance percentiles make p90 the speed 90% of streams meet or exceed. Daily percentiles retain their ascending statistical meaning. Each recent window carries a matching `_samples` count; `uptime_last_1d_samples` accompanies daily uptime. `supports_tool_choice` follows the tools declaration after standing capability verdicts and measured fidelity filtering. `supports_voice_cloning` is whether the endpoint declares `input_references` on its `speech` output modality, and is false on every endpoint whose document declares no reference clip; `perf_last_30m_by_workload` is null because workload-specific performance is not measured. `speech_envelope` is what the endpoint declared it speaks — the voices, the codecs and the speed range — and the only voices a speech request routed to it may name; it is null on every endpoint that synthesizes no speech. A measured figure whose window holds fewer samples than its own gate is `null`, and the gates differ: five for a timing, ten for uptime, twenty for tool-call success, fifty for the runaway rate. A model that exists with nothing serving it answers 200 with `\"endpoints\": []`. `compliance.zdr` is the marketplace's verdict on the provider's zero-data-retention declaration, not the declaration itself: `true` once the claim passed review, `null` while it is under review, `false` when it was denied or declared false, with `compliance.zdr_status` naming the verdict (`pending`, `approved`, `denied`) wherever a claim stands. `refuted_reasoning_efforts` lists the currently declared `reasoning_effort` levels the endpoint's latest per-level check refuted, empty when none is: the declaration in `supported_parameters` stands, and a request naming a listed level routes past the endpoint until a later check passes. `runaway_rate_1d` is the percent of the day's long replies that ended still repeating their own tail with nothing having stopped them, and it is the one percentage here a reader wants low — uptime and tool-call success both read better the higher they are. Its denominator is the replies whose text was read — no embedding, transcription or render is in it — carrying at least 256 completion tokens; a reply that stopped of its own accord and a reply that ended by calling a tool are outside the numerator, and so is one the engine's own repetition detector ended, which stays in the denominator. The reading is taken as the reply passes, over a bounded window of its tail, and no reply text is retained. Each gated figure carries the count behind it, published whether or not the figure is — `throughput_last_1d_samples`, `tool_call_success_1d_samples`, `runaway_rate_1d_samples`, and `render_timing_samples` with `render_timing_sizes` beside it because the render fit needs distinct geometries as well as renders. A positive count beside a `null` figure is a window measured below its gate, `0` is a window that held nothing of that kind, and `null` is an endpoint nothing has been computed for. `family` is the model's family, the same `{ id, name }` the `GET /models` summary carries. `benchmarks_note` is the grading disclosure every score in an endpoint's `benchmarks` is read under.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } } ], "responses": { "200": { "description": "The model shell, its family and its live endpoints.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "name", "endpoints" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "model_id": { "type": "string" }, "model_name": { "type": "string" }, "provider_name": { "type": "string" }, "provider_slug": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid", "description": "The provider's primary key. It holds when the provider's slug is changed." }, "tag": { "type": "string" }, "context_length": { "type": "integer", "minimum": 0, "description": "This endpoint's own declared context window." }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The output ceiling this endpoint declares, or `null` when it declares none." }, "max_prompt_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The prompt cap this endpoint declares on its `text` input in tokens, distinct from `context_length`: a provider may cap the prompt below the window it caps the conversation at. `null` where the input declares no such bound, or states one in a unit other than tokens." }, "quantization": { "type": [ "string", "null" ], "description": "`int2` … `fp32`, or `null` when the endpoint declares none." }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "object", "additionalProperties": false, "properties": { "supported_efforts": { "type": "array", "items": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ] }, "description": "The explicitly declared effort domain, strongest first. Absent when the domain is unknown; never null or an inferred promise of all API values. Capability refutations are published separately as `refuted_reasoning_efforts` on the endpoint." }, "mandatory": { "type": "boolean", "description": "Present as `false` when the endpoint declares `none` or a boolean reasoning switch. Otherwise omitted: the absence of a disable declaration does not prove mandatory thinking." }, "default_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The valid declared effort default for a request that omits effort. The value `none` means reasoning is off by default. Absent when no valid default is declared." }, "default_enabled": { "type": "boolean", "description": "The declared boolean thinking default, or whether an effort default differs from `none` when no independent thinking switch is declared. Absent when defaults are missing or conflicting; a switch without a default does not inherit the effort default." }, "supports_max_tokens": { "type": "boolean", "description": "Present and `true` only for a declared integer or range reasoning token budget. This describes the endpoint declaration; forwarding the control depends on the adapter." } } }, "video_generation": { "type": "object", "additionalProperties": false, "properties": { "generate_audio": { "type": "object", "additionalProperties": false, "properties": { "supported_values": { "type": "array", "items": { "type": "boolean" }, "description": "Explicitly declared soundtrack choices. Absent when the accepted domain is unknown." }, "default": { "type": "boolean", "description": "The declared soundtrack default. Absent when missing or conflicting; there is no universal API default." } } } } }, "reference_inputs": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 16 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." }, "control_sets": { "type": "array", "description": "Which control roles may travel together in one request, as a list of sets. Absent, every combination of the control roles listed under `roles` is served; present, a request whose control roles match no set is refused.", "items": { "type": "array", "items": { "type": "string", "enum": [ "canny", "depth", "normal", "openpose", "segmentation" ] } } } } }, "video": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 3 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "video": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "first_frame": { "type": "integer", "minimum": 1 }, "last_frame": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } }, "audio": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } }, "video": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." }, "control_sets": { "type": "array", "description": "Which control roles may travel together in one request, as a list of sets. Absent, every combination of the control roles listed under `roles` is served; present, a request whose control roles match no set is refused.", "items": { "type": "array", "items": { "type": "string", "enum": [ "canny", "depth", "normal", "openpose", "segmentation" ] } } } } }, "speech": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 1 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "audio": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "audio": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." } } }, "mesh": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 4 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." } } } } }, "pricing_skus": { "type": "array", "description": "Heimdallm extension: native, discounted billable pricing lines, including ordered conditional overrides. Decimal USD strings retain accounting precision. Search prices are omitted while no search count is metered.", "items": { "type": "object", "required": [ "scope", "modality", "type", "unit", "cost_usd" ], "properties": { "scope": { "type": "string", "enum": [ "input", "output", "request" ] }, "modality": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "cost_usd": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "object", "required": [ "when", "cost_usd" ], "properties": { "when": { "$ref": "#/components/schemas/PricingPredicate" }, "cost_usd": { "type": "string" } } } }, "utc_start": { "type": "integer" }, "utc_end": { "type": "integer" }, "utc_days": { "type": "array", "items": { "type": "string" } }, "ttl_seconds": { "type": "integer" }, "implicit": { "type": "boolean" } } } }, "adapters": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "name", "base_models", "kind", "stage", "strength", "available", "pricing", "required_references" ], "properties": { "id": { "type": "string", "description": "Provider catalogue adapter identity." }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the provider-hosted weights. Send this revision with the selection." }, "name": { "type": "string" }, "description": { "type": "string" }, "base_models": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "lora", "control_lora" ] }, "stage": { "type": "string", "enum": [ "base", "refine", "both" ] }, "strength": { "type": "object", "required": [ "min", "max", "default" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "additionalProperties": false }, "available": { "type": "boolean" }, "pricing": { "type": "string", "enum": [ "included", "conditional" ], "description": "Included in the generation tariff, or selects an explicit conditional output rate." }, "exclusive_group": { "type": "string" }, "required_references": { "type": "array", "items": { "type": "object", "required": [ "kind", "role" ], "properties": { "kind": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": false } } } } }, "video": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "name", "base_models", "kind", "stage", "strength", "available", "pricing", "required_references" ], "properties": { "id": { "type": "string", "description": "Provider catalogue adapter identity." }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the provider-hosted weights. Send this revision with the selection." }, "name": { "type": "string" }, "description": { "type": "string" }, "base_models": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "lora", "control_lora" ] }, "stage": { "type": "string", "enum": [ "base", "refine", "both" ] }, "strength": { "type": "object", "required": [ "min", "max", "default" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "additionalProperties": false }, "available": { "type": "boolean" }, "pricing": { "type": "string", "enum": [ "included", "conditional" ], "description": "Included in the generation tariff, or selects an explicit conditional output rate." }, "exclusive_group": { "type": "string" }, "required_references": { "type": "array", "items": { "type": "object", "required": [ "kind", "role" ], "properties": { "kind": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": false } } } } } }, "description": "Provider-owned adapters selected through provider.options[provider_slug].adapters as an array of {id, revision, strength}. Weights are not uploaded to the marketplace. Unsupported revisions, combinations and required references are refused before funded dispatch." }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "discount" ], "description": "This endpoint's own prices as a request is charged them, decimal strings per unit and already net of the larger of the endpoint's discount and any active site promotion. A rate can carry more than 24 decimals where a discount multiplied a declaration's own precision; a charge is that rate times the units consumed, floored once at the ledger's 24 decimals. Every key names the unit it meters. A unit the endpoint declared no price for is absent from this object, never `0`. Native media scalar keys are present only for one unambiguous, unconditional output tariff; conditional and windowed native rates are omitted from the scalar projection. A price per audio input token is never published, because the marketplace holds no price in that unit.", "properties": { "prompt": { "type": "string", "description": "USD per input token." }, "completion": { "type": "string", "description": "USD per output token." }, "input_cache_read": { "type": "string", "description": "USD per prompt token read from cache." }, "input_cache_write": { "type": "string", "description": "USD per prompt token written to cache." }, "internal_reasoning": { "type": "string", "description": "USD per reasoning token, where the endpoint prices reasoning apart from completion." }, "request": { "type": "string", "description": "USD per request, charged flat." }, "image_megapixel": { "type": "string", "description": "USD per 1,000,000 pixels of delivered image output under a linear area tariff." }, "audio_second": { "type": "string", "description": "USD per second of audio, whether consumed on a transcription or generated in a reply." }, "character": { "type": "string", "description": "USD per character synthesized." }, "input_cache_write_1h": { "type": "string", "description": "USD per prompt token written to a cache that holds it for an hour, where the endpoint prices that lifetime apart from its default one. `input_cache_write` is the price of a write carrying no lifetime." }, "image": { "type": "string", "description": "USD per image supplied in the prompt, charged per image rather than per pixel." }, "audio_output": { "type": "string", "description": "USD per audio token generated in a reply." }, "image_output": { "type": "string", "description": "USD per delivered output image." }, "image_output_token": { "type": "string", "description": "USD per output image token. Heimdallm extension." }, "video_second": { "type": "string", "description": "USD per second of delivered video output, including fractional seconds. Heimdallm extension." }, "mesh_output": { "type": "string", "description": "USD per delivered mesh, charged whole. The face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. Heimdallm extension." }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "Conditional prices. All conditions in an entry must match; later matching entries win per price key. Windowed rates follow default-rate overrides, with declaration order preserved within each group. Present only where at least one condition can be represented." }, "discount": { "type": "number", "description": "Heimdallm extension: the effective fraction taken off the list price to reach the prices above, including any active site promotion. A list price is `price / (1 - discount)`. Always present: `0` where nothing is taken off, and negative where the endpoint charges above its list." } } }, "input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Endpoint inputs with current semantic qualification observations applied." }, "declared_input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Inputs listed by the provider, before endpoint qualification." }, "capability_qualification": { "type": "array", "description": "Current semantic observations. Status retains an unexpired decisive result through a later inconclusive check; latest_check reports the most recent attempt. A capability is absent where it is untested, where its evidence does not apply, and where a check refuted something this endpoint’s own document never declared: such a refutation withholds nothing from routing and is published as nothing. Absence is never unsupported. Observations expire or become inapplicable after serving configuration changes.", "items": { "type": "object", "properties": { "capability": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "string" }, "description": "Semantic assertions established by this check." }, "status": { "type": "string", "enum": [ "verified", "refuted", "inconclusive" ] }, "latest_check": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "refuted", "inconclusive" ] }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "checked_at" ], "additionalProperties": false }, "checked_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "capability", "status", "checked_at", "expires_at", "latest_check" ], "additionalProperties": false } }, "parameter_domains": { "type": "object", "description": "Provider-declared request domains for every output modality, keyed by modality and parameter name. Each value is a JSON Schema fragment. `supported_parameters` also includes names a provider declared without a machine-readable domain. Read the serving endpoint's domain when routing requires an exact value range.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "render_parameters": { "type": "object", "description": "Full descriptors, keyed by output modality (`image`, `video`, `mesh`) then by parameter name, for every render parameter this endpoint both declares in `supported_parameters` and states a domain for. A name with no descriptor, or a modality this endpoint does not render, carries no key here — `supported_parameters` alone is the promise for those. Each inner value is the parameter's own JSON Schema fragment, whose shape follows the descriptor kind (`enum`, `range`, `integer`, `boolean`, `object`) rather than one fixed shape this document can name in advance.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "refuted_reasoning_efforts": { "type": "array", "items": { "type": "string" }, "description": "Currently declared levels of `reasoning_effort` whose latest per-level check refuted the value. The declaration in `supported_parameters` stands — a refuted level filters the value, not the name." }, "supports_tool_choice": { "type": "boolean" }, "supports_implicit_caching": { "type": "boolean", "description": "Whether the provider starts caching a prompt unasked, read off a `cached_prompt` or `cache_write` pricing entry stated `implicit`." }, "supports_voice_cloning": { "type": "boolean" }, "image_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "max_megapixels", "min_edge", "max_edge", "edge_multiple" ], "properties": { "max_megapixels": { "type": "number", "exclusiveMinimum": 0, "description": "The most pixels one image may come to." }, "min_edge": { "type": "integer", "minimum": 1, "description": "The narrowest either edge may fall to." }, "max_edge": { "type": "integer", "minimum": 1, "description": "The widest either edge may reach." }, "edge_multiple": { "type": "integer", "minimum": 1, "description": "Both edges land on a multiple of this, a property of the architecture rather than a preference." } } }, { "type": "null" } ], "description": "What this one endpoint draws, as it declared it. `null` on every endpoint that renders no image, and on an image endpoint whose document declares nothing." }, "video_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "frame", "max_seconds", "fps", "frame_step", "audio" ], "properties": { "frame": { "type": "object", "additionalProperties": false, "required": [ "max_megapixels", "min_edge", "max_edge", "edge_multiple" ], "properties": { "max_megapixels": { "type": "number", "exclusiveMinimum": 0, "description": "The most pixels one image may come to." }, "min_edge": { "type": "integer", "minimum": 1, "description": "The narrowest either edge may fall to." }, "max_edge": { "type": "integer", "minimum": 1, "description": "The widest either edge may reach." }, "edge_multiple": { "type": "integer", "minimum": 1, "description": "Both edges land on a multiple of this, a property of the architecture rather than a preference." } }, "description": "The bounds one frame of the clip draws inside." }, "max_seconds": { "type": "number", "exclusiveMinimum": 0, "description": "The longest clip it renders." }, "fps": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "The frame rates it serves." }, "frame_step": { "type": "integer", "minimum": 1, "description": "The frame count a request resolves to must land on a multiple of this." }, "audio": { "type": "boolean", "description": "Whether it can generate a soundtrack alongside the clip." } } }, { "type": "null" } ], "description": "What this one endpoint renders, as it declared it. `null` on every endpoint that renders no video, and on a video endpoint whose document declares nothing." }, "mesh_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "max_faces", "min_faces", "texture" ], "properties": { "max_faces": { "type": "integer", "minimum": 1, "description": "The most faces it decimates to." }, "min_faces": { "type": "integer", "minimum": 1, "description": "The fewest faces it decimates to. A floor as well as a ceiling, because a decimator handed a target below the surface it can close lands above the target in silence." }, "texture": { "type": "boolean", "description": "Whether it can bake a texture into the mesh." } } }, { "type": "null" } ], "description": "What this one endpoint builds, as it declared it. `null` on every endpoint that generates no mesh, and on a mesh endpoint whose document declares nothing — which is an endpoint no mesh request is routed to." }, "decisions_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "question_types": { "type": "array", "items": { "type": "string", "enum": [ "choice", "score", "noul" ] } }, "max_questions": { "type": "integer", "minimum": 1 }, "option_token_budget": { "type": "integer", "minimum": 1 } } }, { "type": "null" } ], "description": "Question types, request size and option budget this endpoint declares. Null means these bounds are undeclared." }, "speech_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "voices", "formats" ], "properties": { "voices": { "type": "array", "items": { "type": "string" }, "description": "The voice identifiers it answers to, as the provider spells them. A voice named `default` is the one it falls back to." }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ] }, "description": "The codecs it encodes into." }, "min_speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "max_speed": { "type": "number", "minimum": 0.25, "maximum": 4 } } }, { "type": "null" } ], "description": "What this one endpoint speaks, as it declared it, and the only voices a request routed to it may name. `null` on every endpoint that synthesizes no speech, and on a speech endpoint whose document declares nothing — which is an endpoint no speech request is routed to." }, "status": { "type": "integer", "enum": [ 0, -1 ], "description": "`0` while the endpoint reads healthy, `-1` otherwise." }, "health": { "type": "string", "enum": [ "unknown", "healthy", "degraded", "down" ] }, "benchmarks": { "type": "array", "description": "Scores earned by this endpoint, gated on a minimum sample count. Empty where none clear it.", "items": { "type": "object", "required": [ "dataset", "score", "sample_count" ], "additionalProperties": false, "properties": { "dataset": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_count": { "type": "integer", "minimum": 0 } } } }, "compliance": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "zdr", "hipaa" ], "description": "The endpoint's ZDR claim folded through its provider's vetting verdict (`approved` reads `zdr: true`, `pending`/unreviewed reads `null`, `denied` reads `false`), beside its HIPAA claim verbatim. `null` where the endpoint declares neither, which is undeclared rather than refused.", "properties": { "zdr": { "type": [ "boolean", "null" ] }, "zdr_status": { "type": "string", "enum": [ "pending", "approved", "denied" ] }, "hipaa": { "type": [ "boolean", "null" ] } } }, "data_policy": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "training", "retention_days" ], "description": "The endpoint's declared data policy. `null` where it declares none.", "properties": { "training": { "type": [ "boolean", "null" ] }, "retention_days": { "type": [ "integer", "null" ], "minimum": 0 } } }, "datacenters": { "type": [ "array", "null" ], "description": "The endpoint's declared serving locations. `null` where it declares none.", "items": { "type": "object", "required": [ "country_code" ], "additionalProperties": false, "properties": { "country_code": { "type": "string" }, "region": { "type": "string" } } } }, "capacity": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "current", "total", "updated_at" ], "description": "The endpoint's most recently reported capacity, or `null` where the provider has reported none recently enough to trust.", "properties": { "current": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" } } }, "uptime_last_5m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_5m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_30m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_7d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "latency_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "latency_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "ttft_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "ttft_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "perf_last_30m_by_workload": { "type": "null" }, "render_timing": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "fixed_seconds", "seconds_per_megapixel" ], "description": "What a render costs before it draws anything and what each megapixel adds, gated the same as any other measured figure. `null` until the gate clears; `render_timing_samples` and `render_timing_sizes` are published beside it whether or not it has, so a reader can tell a window short of the gate from an endpoint no rendering traffic has reached.", "properties": { "fixed_seconds": { "type": "number", "minimum": 0 }, "seconds_per_megapixel": { "type": "number", "minimum": 0 } } }, "render_timing_samples": { "type": [ "integer", "null" ], "minimum": 0, "description": "Renders counted toward `render_timing`, across every size, whether or not the gate cleared." }, "render_timing_sizes": { "type": [ "integer", "null" ], "minimum": 0, "description": "The distinct sizes among those renders, the fit's second gate." }, "tool_call_success_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of the day's demanded tool asks (`tool_choice: \"required\"` or a named function) that produced a tool call. `null` short of the sample gate, which an `\"auto\"` turn never counts against either way." }, "tool_call_success_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "runaway_rate_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of generations that ran away, per day." }, "runaway_rate_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "name", "model_id", "model_name", "provider_name", "provider_slug", "provider_id", "tag", "context_length", "max_completion_tokens", "max_prompt_tokens", "quantization", "supported_parameters", "reference_inputs", "pricing", "input_modalities", "declared_input_modalities", "capability_qualification", "render_parameters", "refuted_reasoning_efforts", "supports_tool_choice", "supports_implicit_caching", "supports_voice_cloning", "image_envelope", "video_envelope", "mesh_envelope", "decisions_envelope", "speech_envelope", "status", "health", "benchmarks", "compliance", "data_policy", "datacenters", "capacity", "uptime_last_5m", "uptime_last_5m_samples", "uptime_last_30m", "uptime_last_30m_samples", "uptime_last_1d", "uptime_last_1d_samples", "uptime_last_7d", "latency_last_30m", "latency_last_30m_samples", "throughput_last_30m", "throughput_last_30m_samples", "throughput_last_1d", "throughput_last_1d_samples", "ttft_last_30m", "ttft_last_1d", "response_last_30m", "response_last_1d", "perf_last_30m_by_workload", "render_timing", "render_timing_samples", "render_timing_sizes", "tool_call_success_1d", "tool_call_success_1d_samples", "runaway_rate_1d", "runaway_rate_1d_samples" ], "additionalProperties": false } } } } } }, "example": { "data": { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "description": "A mixture-of-experts model tuned for speed.", "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "endpoints": [ { "name": "ImpCC | deepseek/deepseek-v4-flash-0731-abliterated", "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "model_name": "DeepSeek V4 Flash 0731", "provider_name": "ImpCC", "provider_slug": "impcc", "provider_id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "tag": "impcc/fp4", "context_length": 131072, "max_completion_tokens": 32768, "max_prompt_tokens": null, "quantization": "fp4", "supported_parameters": [ "temperature", "tools", "reasoning_effort" ], "input_modalities": [ "text" ], "declared_input_modalities": [ "text" ], "capability_qualification": [], "reference_inputs": {}, "render_parameters": {}, "refuted_reasoning_efforts": [], "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "input_cache_read": "0.000000037", "input_cache_write": "0.000000125", "input_cache_write_1h": "0.0000002", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ], "discount": 0.1 }, "status": 0, "health": "healthy", "uptime_last_5m": null, "uptime_last_5m_samples": 3, "uptime_last_30m": 100, "uptime_last_30m_samples": 14, "uptime_last_1d_samples": 90, "latency_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "latency_last_30m_samples": 7, "throughput_last_30m": null, "throughput_last_30m_samples": 3, "perf_last_30m_by_workload": null, "supports_tool_choice": true, "supports_voice_cloning": false, "uptime_last_1d": 99.5, "uptime_last_7d": 99.2, "ttft_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "ttft_last_1d": null, "response_last_30m": { "p50": 2.61, "p75": 3.1, "p90": 4, "p99": 6.2 }, "response_last_1d": null, "throughput_last_1d": { "p50": 85.1, "p75": 92, "p90": 98.4, "p99": 110.2 }, "throughput_last_1d_samples": 214, "render_timing": null, "render_timing_samples": 0, "render_timing_sizes": 0, "image_envelope": null, "video_envelope": null, "mesh_envelope": null, "decisions_envelope": null, "speech_envelope": null, "supports_implicit_caching": false, "compliance": { "zdr": true, "zdr_status": "approved", "hipaa": false }, "data_policy": { "training": false, "retention_days": 0 }, "datacenters": [ { "country_code": "CA" } ], "tool_call_success_1d": 98.2, "tool_call_success_1d_samples": 340, "runaway_rate_1d": 1.4, "runaway_rate_1d_samples": 620, "benchmarks": [], "capacity": { "current": 1, "total": 4, "updated_at": "2026-08-16T11:59:31.000Z" } } ], "benchmarks_note": "Scores are measured on this marketplace through the same routing customer traffic takes." } } } } }, "404": { "description": "No such model. When the id names a family whose base model is not served, `metadata.family` and `metadata.family_variants` name the served ids to redirect to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}/{slug}/benchmarks": { "get": { "operationId": "getModelBenchmarks", "summary": "A model's benchmark scores", "description": "Scores from the benchmark bank, which runs as real paid traffic through the same routing customers use. Only datasets the model is eligible for appear, and only where the run holds enough samples to publish. `note` is the grading disclosure that goes wherever the scores go. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The publishable scores.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": [ { "dataset": "gsm8k", "score": 0.83, "sample_count": 250, "grading": "exact match" } ], "note": "Scores are measured on this marketplace through the same routing customer traffic takes." } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "404": { "description": "No such model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}/{slug}/series": { "get": { "operationId": "getModelSeries", "summary": "A model's hourly health series", "description": "Per live endpoint, sparse ascending hourly buckets: attempt counts, observed time to first token and median output rate, plus the price changes recorded for the endpoint, each carrying one member per unit the change log records. Discrete percentiles, so every figure published was measured. An hour whose traffic never streamed reports `null` timings rather than zero. Each row names its `model_id`, the one row shape the family series shares. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } }, { "name": "days", "in": "query", "description": "Days of history, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 7, "default": 7 } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One series per live endpoint.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "window_days": 7, "endpoints": [ { "endpoint_id": "5f0c…", "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "provider_slug": "impcc", "provider_id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "provider_name": "ImpCC", "quantization": "fp8", "hours": [ { "hour": "2026-08-16T11:00:00.000Z", "ok": 118, "error": 2, "ttft_p50": 0.42, "ttft_p90": 0.9, "throughput_median": 63.1 } ], "prices": [ { "captured_at": "2026-08-10T09:00:00.000Z", "prompt": "0.0000001", "completion": "0.0000004", "cached_prompt": "0.000000037", "request": null, "image": null, "audio": null, "character": null } ] } ] } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "400": { "description": "`days` is outside 1 to 7.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models/{author}/{slug}/activity/series": { "get": { "operationId": "getModelActivitySeries", "summary": "A model's daily usage", "description": "Per UTC day: requests, prompt and completion token sums, image requests with the megapixels they drew, and audio seconds. Every billed request counts, the marketplace's own paid probe traffic included. Counts only, no money. Sparse: a day without traffic has no entry. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the model id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the model id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731-abliterated" } }, { "name": "days", "in": "query", "description": "Days of history, ending today.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The daily counts.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "window_days": 30, "daily": [ { "date": "2026-08-16", "requests": 12, "prompt_tokens": 90210, "completion_tokens": 4821, "images": 0, "megapixels": 0, "audio_seconds": 0 } ] } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "400": { "description": "`days` is outside 1 to 30.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/families": { "get": { "operationId": "listFamilies", "summary": "List families", "description": "A family is one base model and the variants published from it, which is what lets a page offer a quantisation or an abliteration as a choice rather than as a separate model.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "Every family with a served model in it.", "content": { "application/json": { "example": { "data": [ { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731", "author": "deepseek", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "models": [ "deepseek/deepseek-v4-flash-0731-abliterated" ], "endpoint_count": 3, "providers": [ "impcc" ] } ] } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/families/{author}/{slug}": { "get": { "operationId": "getFamily", "summary": "One family", "description": "The family with the full summary of every served model in it, in the shape `GET /models` uses, and every live endpoint across those models, so a family page needs exactly one call. Each endpoint row is the row `GET /models/{author}/{slug}/endpoints` publishes for that endpoint and names its own `model_id`; rows are ordered by model id, then provider slug, then endpoint id. `benchmarks_note` is the grading disclosure every `benchmarks` score on a row is read under. A family none of whose models is served answers 200 with `\"models\": []` and `\"endpoints\": []`.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the family id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the family id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731" } } ], "responses": { "200": { "description": "The family, its served models newest first, and their live endpoints.", "content": { "application/json": { "example": { "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731", "author": "deepseek", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731" }, "models": [ { "id": "deepseek/deepseek-v4-flash-0731-abliterated", "canonical_slug": "deepseek/deepseek-v4-flash-0731-abliterated", "hugging_face_id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731 (abliterated)", "created": 1785611388, "expiration_date": null, "description": "A mixture-of-experts model tuned for speed.", "context_length": 131072, "architecture": { "modality": "text->text", "input_modalities": [ "text" ], "output_modalities": [ "text" ], "tokenizer": "DeepSeek", "instruct_type": null }, "license": "mit", "parameter_count": 305723922366, "weights_dtype": "I8", "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "request": "0", "input_cache_read": "0.000000037", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ] }, "top_provider": { "context_length": 131072, "max_completion_tokens": 32768, "is_moderated": false }, "per_request_limits": null, "supported_parameters": [ "temperature", "top_p", "tools", "reasoning_effort" ], "reasoning": { "supported_efforts": [ "high", "medium", "low", "none" ], "mandatory": false, "default_effort": "medium", "default_enabled": true, "supports_max_tokens": true }, "default_parameters": { "temperature": 1, "top_p": 1 }, "hugging_face": { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "read_at": 1793817600, "availability": "public", "languages": [ "en", "zh" ], "papers": [ "2606.19348" ], "datasets": [ "HuggingFaceM4/the_cauldron" ], "weights_revision": "0e9e39f249a16976918f6564b8830bc894c89659", "weights_updated_at": 1727283657, "downloads": 128473, "likes": 941, "evaluations": [ { "task": "text-generation", "dataset": "HumanEval", "metrics": [ { "name": "pass@1", "value": 71.3 } ] } ] }, "family": { "id": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" }, "author": "deepseek", "tags": [ "abliterated", "moe" ], "endpoint_count": 1, "links": { "details": "/api/v1/models/deepseek/deepseek-v4-flash-0731-abliterated/endpoints" }, "supported_voices": null, "supported_dimensions": null, "supported_languages": null } ], "endpoints": [ { "name": "ImpCC | deepseek/deepseek-v4-flash-0731-abliterated", "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "model_name": "DeepSeek V4 Flash 0731", "provider_name": "ImpCC", "provider_slug": "impcc", "provider_id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "tag": "impcc/fp4", "context_length": 131072, "max_completion_tokens": 32768, "max_prompt_tokens": null, "quantization": "fp4", "supported_parameters": [ "temperature", "tools", "reasoning_effort" ], "input_modalities": [ "text" ], "declared_input_modalities": [ "text" ], "capability_qualification": [], "reference_inputs": {}, "render_parameters": {}, "refuted_reasoning_efforts": [], "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "input_cache_read": "0.000000037", "input_cache_write": "0.000000125", "input_cache_write_1h": "0.0000002", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ], "discount": 0.1 }, "status": 0, "health": "healthy", "uptime_last_5m": null, "uptime_last_5m_samples": 3, "uptime_last_30m": 100, "uptime_last_30m_samples": 14, "uptime_last_1d_samples": 90, "latency_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "latency_last_30m_samples": 7, "throughput_last_30m": null, "throughput_last_30m_samples": 3, "perf_last_30m_by_workload": null, "supports_tool_choice": true, "supports_voice_cloning": false, "uptime_last_1d": 99.5, "uptime_last_7d": 99.2, "ttft_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "ttft_last_1d": null, "response_last_30m": { "p50": 2.61, "p75": 3.1, "p90": 4, "p99": 6.2 }, "response_last_1d": null, "throughput_last_1d": { "p50": 85.1, "p75": 92, "p90": 98.4, "p99": 110.2 }, "throughput_last_1d_samples": 214, "render_timing": null, "render_timing_samples": 0, "render_timing_sizes": 0, "image_envelope": null, "video_envelope": null, "mesh_envelope": null, "decisions_envelope": null, "speech_envelope": null, "supports_implicit_caching": false, "compliance": { "zdr": true, "zdr_status": "approved", "hipaa": false }, "data_policy": { "training": false, "retention_days": 0 }, "datacenters": [ { "country_code": "CA" } ], "tool_call_success_1d": 98.2, "tool_call_success_1d_samples": 340, "runaway_rate_1d": 1.4, "runaway_rate_1d_samples": 620, "benchmarks": [], "capacity": { "current": 1, "total": 4, "updated_at": "2026-08-16T11:59:31.000Z" } } ], "benchmarks_note": "Scores are measured on this marketplace through the same routing customer traffic takes." } } } }, "404": { "description": "No such family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/families/{author}/{slug}/series": { "get": { "operationId": "getFamilySeries", "summary": "A family's hourly health series", "description": "Per live endpoint across every served model in the family, the series `GET /models/{author}/{slug}/series` publishes for that endpoint: sparse ascending hourly buckets and recorded price changes, each row naming its `model_id`. No bucket is merged across endpoints or models. Rows are ordered by provider slug then endpoint id. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the family id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the family id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731" } }, { "name": "days", "in": "query", "description": "Days of history, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 7, "default": 7 } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One series per live endpoint in the family.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": { "family_id": "deepseek/deepseek-v4-flash-0731", "window_days": 7, "endpoints": [ { "endpoint_id": "5f0c…", "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "provider_slug": "impcc", "provider_id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "provider_name": "ImpCC", "quantization": "fp8", "hours": [ { "hour": "2026-08-16T11:00:00.000Z", "ok": 118, "error": 2, "ttft_p50": 0.42, "ttft_p90": 0.9, "throughput_median": 63.1 } ], "prices": [ { "captured_at": "2026-08-10T09:00:00.000Z", "prompt": "0.0000001", "completion": "0.0000004", "cached_prompt": "0.000000037", "request": null, "image": null, "audio": null, "character": null } ] } ] } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "400": { "description": "`days` is outside 1 to 7.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/families/{author}/{slug}/activity/series": { "get": { "operationId": "getFamilyActivitySeries", "summary": "A family's daily usage", "description": "The counts `GET /models/{author}/{slug}/activity/series` publishes, summed per UTC day over every active model in the family, a model with no live endpoint included. Every billed request counts, the marketplace's own paid probe traffic included. Counts only, no money. Sparse: a day without traffic has no entry. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "author", "in": "path", "required": true, "description": "The half of the family id before the slash.", "schema": { "type": "string", "example": "deepseek" } }, { "name": "slug", "in": "path", "required": true, "description": "The half of the family id after the slash.", "schema": { "type": "string", "example": "deepseek-v4-flash-0731" } }, { "name": "days", "in": "query", "description": "Days of history, ending today.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The daily counts across the family.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": { "family_id": "deepseek/deepseek-v4-flash-0731", "window_days": 30, "daily": [ { "date": "2026-08-16", "requests": 12, "prompt_tokens": 90210, "completion_tokens": 4821, "images": 0, "megapixels": 0, "audio_seconds": 0 } ] } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "400": { "description": "`days` is outside 1 to 30.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such family.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers": { "get": { "operationId": "listProviders", "summary": "List providers", "description": "Approved providers, with the policies and locations each of them declares. `id` is the provider's primary key and holds when its `slug` is changed, so a mirror keyed on `id` follows a renamed provider rather than seeing a new one.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "The approved providers.", "content": { "application/json": { "example": { "data": [ { "id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "name": "ImpCC", "slug": "impcc", "privacy_policy_url": "https://impcc.example/privacy", "terms_of_service_url": "https://impcc.example/terms", "status_page_url": null, "headquarters": "CA", "datacenters": [ "CA" ], "website": "https://impcc.example", "model_count": 3 } ] } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{slug}/series": { "get": { "operationId": "getProviderSeries", "summary": "A provider's hourly health series", "description": "One hourly ok/error series aggregated across all of the provider's live endpoints, with the status board's counting rules. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The provider slug.", "schema": { "type": "string", "example": "impcc" } }, { "name": "days", "in": "query", "description": "Days of history, ending now.", "schema": { "type": "integer", "minimum": 1, "maximum": 7, "default": 7 } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The aggregated series.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "data": { "provider_slug": "impcc", "window_days": 7, "hours": [ { "hour": "2026-08-16T11:00:00.000Z", "ok": 118, "error": 2 } ] } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "400": { "description": "`days` is outside 1 to 7.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such approved provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/endpoints/zdr": { "get": { "operationId": "listZdrEndpoints", "summary": "The endpoints ZDR routing keeps", "description": "Every live endpoint the ZDR fold keeps, across the whole catalogue: a claim whose provider an operator approved. The same public endpoint shape `GET /models/{author}/{slug}/endpoints` publishes, ordered by model id then provider slug then endpoint id. A preview of what `zdr: true` routes to, or what `GET /models?zdr=true` matches. No key required.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "The kept endpoints.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "model_id": { "type": "string" }, "model_name": { "type": "string" }, "provider_name": { "type": "string" }, "provider_slug": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid", "description": "The provider's primary key. It holds when the provider's slug is changed." }, "tag": { "type": "string" }, "context_length": { "type": "integer", "minimum": 0, "description": "This endpoint's own declared context window." }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The output ceiling this endpoint declares, or `null` when it declares none." }, "max_prompt_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The prompt cap this endpoint declares on its `text` input in tokens, distinct from `context_length`: a provider may cap the prompt below the window it caps the conversation at. `null` where the input declares no such bound, or states one in a unit other than tokens." }, "quantization": { "type": [ "string", "null" ], "description": "`int2` … `fp32`, or `null` when the endpoint declares none." }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "object", "additionalProperties": false, "properties": { "supported_efforts": { "type": "array", "items": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ] }, "description": "The explicitly declared effort domain, strongest first. Absent when the domain is unknown; never null or an inferred promise of all API values. Capability refutations are published separately as `refuted_reasoning_efforts` on the endpoint." }, "mandatory": { "type": "boolean", "description": "Present as `false` when the endpoint declares `none` or a boolean reasoning switch. Otherwise omitted: the absence of a disable declaration does not prove mandatory thinking." }, "default_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The valid declared effort default for a request that omits effort. The value `none` means reasoning is off by default. Absent when no valid default is declared." }, "default_enabled": { "type": "boolean", "description": "The declared boolean thinking default, or whether an effort default differs from `none` when no independent thinking switch is declared. Absent when defaults are missing or conflicting; a switch without a default does not inherit the effort default." }, "supports_max_tokens": { "type": "boolean", "description": "Present and `true` only for a declared integer or range reasoning token budget. This describes the endpoint declaration; forwarding the control depends on the adapter." } } }, "video_generation": { "type": "object", "additionalProperties": false, "properties": { "generate_audio": { "type": "object", "additionalProperties": false, "properties": { "supported_values": { "type": "array", "items": { "type": "boolean" }, "description": "Explicitly declared soundtrack choices. Absent when the accepted domain is unknown." }, "default": { "type": "boolean", "description": "The declared soundtrack default. Absent when missing or conflicting; there is no universal API default." } } } } }, "reference_inputs": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 16 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." }, "control_sets": { "type": "array", "description": "Which control roles may travel together in one request, as a list of sets. Absent, every combination of the control roles listed under `roles` is served; present, a request whose control roles match no set is refused.", "items": { "type": "array", "items": { "type": "string", "enum": [ "canny", "depth", "normal", "openpose", "segmentation" ] } } } } }, "video": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 3 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "video": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "first_frame": { "type": "integer", "minimum": 1 }, "last_frame": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } }, "audio": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } }, "video": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 }, "canny": { "type": "integer", "minimum": 1 }, "depth": { "type": "integer", "minimum": 1 }, "normal": { "type": "integer", "minimum": 1 }, "openpose": { "type": "integer", "minimum": 1 }, "segmentation": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." }, "control_sets": { "type": "array", "description": "Which control roles may travel together in one request, as a list of sets. Absent, every combination of the control roles listed under `roles` is served; present, a request whose control roles match no set is refused.", "items": { "type": "array", "items": { "type": "string", "enum": [ "canny", "depth", "normal", "openpose", "segmentation" ] } } } } }, "speech": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 1 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "audio": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "audio": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." } } }, "mesh": { "type": "object", "additionalProperties": false, "required": [ "formats", "max_items", "roles" ], "properties": { "max_items": { "type": "integer", "minimum": 1, "maximum": 4 }, "formats": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string" } } } }, "roles": { "type": "object", "additionalProperties": false, "description": "Per input kind, the roles this endpoint takes and the most items of each one request may carry. Only the kinds listed under `formats` appear: a kind this API cannot carry to this rail as inline bytes takes no reference whatever an endpoint declares on it. A kind listed under `formats` whose roles map is absent takes none. An endpoint that lists only `reference` is one a request naming no role reaches unchanged.", "properties": { "image": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "integer", "minimum": 1 } } } } }, "description": { "type": "string", "description": "The provider's own sentence about what this endpoint conditions on, where they wrote one. Guidance a caller reads, not a bound anything enforces." } } } } }, "pricing_skus": { "type": "array", "description": "Heimdallm extension: native, discounted billable pricing lines, including ordered conditional overrides. Decimal USD strings retain accounting precision. Search prices are omitted while no search count is metered.", "items": { "type": "object", "required": [ "scope", "modality", "type", "unit", "cost_usd" ], "properties": { "scope": { "type": "string", "enum": [ "input", "output", "request" ] }, "modality": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "cost_usd": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "object", "required": [ "when", "cost_usd" ], "properties": { "when": { "$ref": "#/components/schemas/PricingPredicate" }, "cost_usd": { "type": "string" } } } }, "utc_start": { "type": "integer" }, "utc_end": { "type": "integer" }, "utc_days": { "type": "array", "items": { "type": "string" } }, "ttl_seconds": { "type": "integer" }, "implicit": { "type": "boolean" } } } }, "adapters": { "type": "object", "additionalProperties": false, "properties": { "image": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "name", "base_models", "kind", "stage", "strength", "available", "pricing", "required_references" ], "properties": { "id": { "type": "string", "description": "Provider catalogue adapter identity." }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the provider-hosted weights. Send this revision with the selection." }, "name": { "type": "string" }, "description": { "type": "string" }, "base_models": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "lora", "control_lora" ] }, "stage": { "type": "string", "enum": [ "base", "refine", "both" ] }, "strength": { "type": "object", "required": [ "min", "max", "default" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "additionalProperties": false }, "available": { "type": "boolean" }, "pricing": { "type": "string", "enum": [ "included", "conditional" ], "description": "Included in the generation tariff, or selects an explicit conditional output rate." }, "exclusive_group": { "type": "string" }, "required_references": { "type": "array", "items": { "type": "object", "required": [ "kind", "role" ], "properties": { "kind": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": false } } } } }, "video": { "type": "array", "maxItems": 64, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "name", "base_models", "kind", "stage", "strength", "available", "pricing", "required_references" ], "properties": { "id": { "type": "string", "description": "Provider catalogue adapter identity." }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the provider-hosted weights. Send this revision with the selection." }, "name": { "type": "string" }, "description": { "type": "string" }, "base_models": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "lora", "control_lora" ] }, "stage": { "type": "string", "enum": [ "base", "refine", "both" ] }, "strength": { "type": "object", "required": [ "min", "max", "default" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "additionalProperties": false }, "available": { "type": "boolean" }, "pricing": { "type": "string", "enum": [ "included", "conditional" ], "description": "Included in the generation tariff, or selects an explicit conditional output rate." }, "exclusive_group": { "type": "string" }, "required_references": { "type": "array", "items": { "type": "object", "required": [ "kind", "role" ], "properties": { "kind": { "type": "string" }, "role": { "type": "string" } }, "additionalProperties": false } } } } } }, "description": "Provider-owned adapters selected through provider.options[provider_slug].adapters as an array of {id, revision, strength}. Weights are not uploaded to the marketplace. Unsupported revisions, combinations and required references are refused before funded dispatch." }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "discount" ], "description": "This endpoint's own prices as a request is charged them, decimal strings per unit and already net of the larger of the endpoint's discount and any active site promotion. A rate can carry more than 24 decimals where a discount multiplied a declaration's own precision; a charge is that rate times the units consumed, floored once at the ledger's 24 decimals. Every key names the unit it meters. A unit the endpoint declared no price for is absent from this object, never `0`. Native media scalar keys are present only for one unambiguous, unconditional output tariff; conditional and windowed native rates are omitted from the scalar projection. A price per audio input token is never published, because the marketplace holds no price in that unit.", "properties": { "prompt": { "type": "string", "description": "USD per input token." }, "completion": { "type": "string", "description": "USD per output token." }, "input_cache_read": { "type": "string", "description": "USD per prompt token read from cache." }, "input_cache_write": { "type": "string", "description": "USD per prompt token written to cache." }, "internal_reasoning": { "type": "string", "description": "USD per reasoning token, where the endpoint prices reasoning apart from completion." }, "request": { "type": "string", "description": "USD per request, charged flat." }, "image_megapixel": { "type": "string", "description": "USD per 1,000,000 pixels of delivered image output under a linear area tariff." }, "audio_second": { "type": "string", "description": "USD per second of audio, whether consumed on a transcription or generated in a reply." }, "character": { "type": "string", "description": "USD per character synthesized." }, "input_cache_write_1h": { "type": "string", "description": "USD per prompt token written to a cache that holds it for an hour, where the endpoint prices that lifetime apart from its default one. `input_cache_write` is the price of a write carrying no lifetime." }, "image": { "type": "string", "description": "USD per image supplied in the prompt, charged per image rather than per pixel." }, "audio_output": { "type": "string", "description": "USD per audio token generated in a reply." }, "image_output": { "type": "string", "description": "USD per delivered output image." }, "image_output_token": { "type": "string", "description": "USD per output image token. Heimdallm extension." }, "video_second": { "type": "string", "description": "USD per second of delivered video output, including fractional seconds. Heimdallm extension." }, "mesh_output": { "type": "string", "description": "USD per delivered mesh, charged whole. The face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. Heimdallm extension." }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "Conditional prices. All conditions in an entry must match; later matching entries win per price key. Windowed rates follow default-rate overrides, with declaration order preserved within each group. Present only where at least one condition can be represented." }, "discount": { "type": "number", "description": "Heimdallm extension: the effective fraction taken off the list price to reach the prices above, including any active site promotion. A list price is `price / (1 - discount)`. Always present: `0` where nothing is taken off, and negative where the endpoint charges above its list." } } }, "input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Endpoint inputs with current semantic qualification observations applied." }, "declared_input_modalities": { "type": "array", "items": { "type": "string" }, "description": "Inputs listed by the provider, before endpoint qualification." }, "capability_qualification": { "type": "array", "description": "Current semantic observations. Status retains an unexpired decisive result through a later inconclusive check; latest_check reports the most recent attempt. A capability is absent where it is untested, where its evidence does not apply, and where a check refuted something this endpoint’s own document never declared: such a refutation withholds nothing from routing and is published as nothing. Absence is never unsupported. Observations expire or become inapplicable after serving configuration changes.", "items": { "type": "object", "properties": { "capability": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "string" }, "description": "Semantic assertions established by this check." }, "status": { "type": "string", "enum": [ "verified", "refuted", "inconclusive" ] }, "latest_check": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "refuted", "inconclusive" ] }, "checked_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "checked_at" ], "additionalProperties": false }, "checked_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "capability", "status", "checked_at", "expires_at", "latest_check" ], "additionalProperties": false } }, "parameter_domains": { "type": "object", "description": "Provider-declared request domains for every output modality, keyed by modality and parameter name. Each value is a JSON Schema fragment. `supported_parameters` also includes names a provider declared without a machine-readable domain. Read the serving endpoint's domain when routing requires an exact value range.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "render_parameters": { "type": "object", "description": "Full descriptors, keyed by output modality (`image`, `video`, `mesh`) then by parameter name, for every render parameter this endpoint both declares in `supported_parameters` and states a domain for. A name with no descriptor, or a modality this endpoint does not render, carries no key here — `supported_parameters` alone is the promise for those. Each inner value is the parameter's own JSON Schema fragment, whose shape follows the descriptor kind (`enum`, `range`, `integer`, `boolean`, `object`) rather than one fixed shape this document can name in advance.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "refuted_reasoning_efforts": { "type": "array", "items": { "type": "string" }, "description": "Currently declared levels of `reasoning_effort` whose latest per-level check refuted the value. The declaration in `supported_parameters` stands — a refuted level filters the value, not the name." }, "supports_tool_choice": { "type": "boolean" }, "supports_implicit_caching": { "type": "boolean", "description": "Whether the provider starts caching a prompt unasked, read off a `cached_prompt` or `cache_write` pricing entry stated `implicit`." }, "supports_voice_cloning": { "type": "boolean" }, "image_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "max_megapixels", "min_edge", "max_edge", "edge_multiple" ], "properties": { "max_megapixels": { "type": "number", "exclusiveMinimum": 0, "description": "The most pixels one image may come to." }, "min_edge": { "type": "integer", "minimum": 1, "description": "The narrowest either edge may fall to." }, "max_edge": { "type": "integer", "minimum": 1, "description": "The widest either edge may reach." }, "edge_multiple": { "type": "integer", "minimum": 1, "description": "Both edges land on a multiple of this, a property of the architecture rather than a preference." } } }, { "type": "null" } ], "description": "What this one endpoint draws, as it declared it. `null` on every endpoint that renders no image, and on an image endpoint whose document declares nothing." }, "video_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "frame", "max_seconds", "fps", "frame_step", "audio" ], "properties": { "frame": { "type": "object", "additionalProperties": false, "required": [ "max_megapixels", "min_edge", "max_edge", "edge_multiple" ], "properties": { "max_megapixels": { "type": "number", "exclusiveMinimum": 0, "description": "The most pixels one image may come to." }, "min_edge": { "type": "integer", "minimum": 1, "description": "The narrowest either edge may fall to." }, "max_edge": { "type": "integer", "minimum": 1, "description": "The widest either edge may reach." }, "edge_multiple": { "type": "integer", "minimum": 1, "description": "Both edges land on a multiple of this, a property of the architecture rather than a preference." } }, "description": "The bounds one frame of the clip draws inside." }, "max_seconds": { "type": "number", "exclusiveMinimum": 0, "description": "The longest clip it renders." }, "fps": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "The frame rates it serves." }, "frame_step": { "type": "integer", "minimum": 1, "description": "The frame count a request resolves to must land on a multiple of this." }, "audio": { "type": "boolean", "description": "Whether it can generate a soundtrack alongside the clip." } } }, { "type": "null" } ], "description": "What this one endpoint renders, as it declared it. `null` on every endpoint that renders no video, and on a video endpoint whose document declares nothing." }, "mesh_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "max_faces", "min_faces", "texture" ], "properties": { "max_faces": { "type": "integer", "minimum": 1, "description": "The most faces it decimates to." }, "min_faces": { "type": "integer", "minimum": 1, "description": "The fewest faces it decimates to. A floor as well as a ceiling, because a decimator handed a target below the surface it can close lands above the target in silence." }, "texture": { "type": "boolean", "description": "Whether it can bake a texture into the mesh." } } }, { "type": "null" } ], "description": "What this one endpoint builds, as it declared it. `null` on every endpoint that generates no mesh, and on a mesh endpoint whose document declares nothing — which is an endpoint no mesh request is routed to." }, "decisions_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "question_types": { "type": "array", "items": { "type": "string", "enum": [ "choice", "score", "noul" ] } }, "max_questions": { "type": "integer", "minimum": 1 }, "option_token_budget": { "type": "integer", "minimum": 1 } } }, { "type": "null" } ], "description": "Question types, request size and option budget this endpoint declares. Null means these bounds are undeclared." }, "speech_envelope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "voices", "formats" ], "properties": { "voices": { "type": "array", "items": { "type": "string" }, "description": "The voice identifiers it answers to, as the provider spells them. A voice named `default` is the one it falls back to." }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ] }, "description": "The codecs it encodes into." }, "min_speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "max_speed": { "type": "number", "minimum": 0.25, "maximum": 4 } } }, { "type": "null" } ], "description": "What this one endpoint speaks, as it declared it, and the only voices a request routed to it may name. `null` on every endpoint that synthesizes no speech, and on a speech endpoint whose document declares nothing — which is an endpoint no speech request is routed to." }, "status": { "type": "integer", "enum": [ 0, -1 ], "description": "`0` while the endpoint reads healthy, `-1` otherwise." }, "health": { "type": "string", "enum": [ "unknown", "healthy", "degraded", "down" ] }, "benchmarks": { "type": "array", "description": "Scores earned by this endpoint, gated on a minimum sample count. Empty where none clear it.", "items": { "type": "object", "required": [ "dataset", "score", "sample_count" ], "additionalProperties": false, "properties": { "dataset": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "sample_count": { "type": "integer", "minimum": 0 } } } }, "compliance": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "zdr", "hipaa" ], "description": "The endpoint's ZDR claim folded through its provider's vetting verdict (`approved` reads `zdr: true`, `pending`/unreviewed reads `null`, `denied` reads `false`), beside its HIPAA claim verbatim. `null` where the endpoint declares neither, which is undeclared rather than refused.", "properties": { "zdr": { "type": [ "boolean", "null" ] }, "zdr_status": { "type": "string", "enum": [ "pending", "approved", "denied" ] }, "hipaa": { "type": [ "boolean", "null" ] } } }, "data_policy": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "training", "retention_days" ], "description": "The endpoint's declared data policy. `null` where it declares none.", "properties": { "training": { "type": [ "boolean", "null" ] }, "retention_days": { "type": [ "integer", "null" ], "minimum": 0 } } }, "datacenters": { "type": [ "array", "null" ], "description": "The endpoint's declared serving locations. `null` where it declares none.", "items": { "type": "object", "required": [ "country_code" ], "additionalProperties": false, "properties": { "country_code": { "type": "string" }, "region": { "type": "string" } } } }, "capacity": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "current", "total", "updated_at" ], "description": "The endpoint's most recently reported capacity, or `null` where the provider has reported none recently enough to trust.", "properties": { "current": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" } } }, "uptime_last_5m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_5m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_30m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_7d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "latency_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "latency_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "ttft_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "ttft_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "perf_last_30m_by_workload": { "type": "null" }, "render_timing": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "fixed_seconds", "seconds_per_megapixel" ], "description": "What a render costs before it draws anything and what each megapixel adds, gated the same as any other measured figure. `null` until the gate clears; `render_timing_samples` and `render_timing_sizes` are published beside it whether or not it has, so a reader can tell a window short of the gate from an endpoint no rendering traffic has reached.", "properties": { "fixed_seconds": { "type": "number", "minimum": 0 }, "seconds_per_megapixel": { "type": "number", "minimum": 0 } } }, "render_timing_samples": { "type": [ "integer", "null" ], "minimum": 0, "description": "Renders counted toward `render_timing`, across every size, whether or not the gate cleared." }, "render_timing_sizes": { "type": [ "integer", "null" ], "minimum": 0, "description": "The distinct sizes among those renders, the fit's second gate." }, "tool_call_success_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of the day's demanded tool asks (`tool_choice: \"required\"` or a named function) that produced a tool call. `null` short of the sample gate, which an `\"auto\"` turn never counts against either way." }, "tool_call_success_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "runaway_rate_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of generations that ran away, per day." }, "runaway_rate_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "name", "model_id", "model_name", "provider_name", "provider_slug", "provider_id", "tag", "context_length", "max_completion_tokens", "max_prompt_tokens", "quantization", "supported_parameters", "reference_inputs", "pricing", "input_modalities", "declared_input_modalities", "capability_qualification", "render_parameters", "refuted_reasoning_efforts", "supports_tool_choice", "supports_implicit_caching", "supports_voice_cloning", "image_envelope", "video_envelope", "mesh_envelope", "decisions_envelope", "speech_envelope", "status", "health", "benchmarks", "compliance", "data_policy", "datacenters", "capacity", "uptime_last_5m", "uptime_last_5m_samples", "uptime_last_30m", "uptime_last_30m_samples", "uptime_last_1d", "uptime_last_1d_samples", "uptime_last_7d", "latency_last_30m", "latency_last_30m_samples", "throughput_last_30m", "throughput_last_30m_samples", "throughput_last_1d", "throughput_last_1d_samples", "ttft_last_30m", "ttft_last_1d", "response_last_30m", "response_last_1d", "perf_last_30m_by_workload", "render_timing", "render_timing_samples", "render_timing_sizes", "tool_call_success_1d", "tool_call_success_1d_samples", "runaway_rate_1d", "runaway_rate_1d_samples" ], "additionalProperties": false } } } }, "example": { "data": [ { "name": "ImpCC | deepseek/deepseek-v4-flash-0731-abliterated", "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "model_name": "DeepSeek V4 Flash 0731", "provider_name": "ImpCC", "provider_slug": "impcc", "provider_id": "0b6f3c1e-8d2a-4f7b-9c1d-5e4a3b2c1d0e", "tag": "impcc/fp4", "context_length": 131072, "max_completion_tokens": 32768, "max_prompt_tokens": null, "quantization": "fp4", "supported_parameters": [ "temperature", "tools", "reasoning_effort" ], "input_modalities": [ "text" ], "declared_input_modalities": [ "text" ], "capability_qualification": [], "reference_inputs": {}, "render_parameters": {}, "refuted_reasoning_efforts": [], "pricing": { "prompt": "0.0000001", "completion": "0.0000004", "input_cache_read": "0.000000037", "input_cache_write": "0.000000125", "input_cache_write_1h": "0.0000002", "overrides": [ { "min_prompt_tokens": 131071, "prompt": "0.0000002" } ], "discount": 0.1 }, "status": 0, "health": "healthy", "uptime_last_5m": null, "uptime_last_5m_samples": 3, "uptime_last_30m": 100, "uptime_last_30m_samples": 14, "uptime_last_1d_samples": 90, "latency_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "latency_last_30m_samples": 7, "throughput_last_30m": null, "throughput_last_30m_samples": 3, "perf_last_30m_by_workload": null, "supports_tool_choice": true, "supports_voice_cloning": false, "uptime_last_1d": 99.5, "uptime_last_7d": 99.2, "ttft_last_30m": { "p50": 0.42, "p75": 0.55, "p90": 0.9, "p99": 1.4 }, "ttft_last_1d": null, "response_last_30m": { "p50": 2.61, "p75": 3.1, "p90": 4, "p99": 6.2 }, "response_last_1d": null, "throughput_last_1d": { "p50": 85.1, "p75": 92, "p90": 98.4, "p99": 110.2 }, "throughput_last_1d_samples": 214, "render_timing": null, "render_timing_samples": 0, "render_timing_sizes": 0, "image_envelope": null, "video_envelope": null, "mesh_envelope": null, "decisions_envelope": null, "speech_envelope": null, "supports_implicit_caching": false, "compliance": { "zdr": true, "zdr_status": "approved", "hipaa": false }, "data_policy": { "training": false, "retention_days": 0 }, "datacenters": [ { "country_code": "CA" } ], "tool_call_success_1d": 98.2, "tool_call_success_1d_samples": 340, "runaway_rate_1d": 1.4, "runaway_rate_1d_samples": 620, "benchmarks": [], "capacity": { "current": 1, "total": 4, "updated_at": "2026-08-16T11:59:31.000Z" } } ] } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/benchmarks": { "get": { "operationId": "listBenchmarks", "summary": "Current serving benchmark results", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "description": "Named official benchmark suites and current serving variants. Results use current protocol-matched evidence within 30 days. Supported sample metrics publish provisional scores after five scored tasks; completed/expected records exact coverage. Only complete runs carry final official aggregates. Provisional averages require identical sample_fingerprint values. Costs are decimal USD strings and missing measurements are null. Computed at most once a minute per gateway, and served for up to an hour past that while it is recomputed; `generated_at` and `Last-Modified` state when. A reader waits at most six seconds for a computation and is otherwise answered 503 with `Retry-After` while it completes.", "responses": { "200": { "description": "Benchmark catalogue, run coverage, provenance and efficiency metrics in a data envelope.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "generated_at", "window_days", "daily_budget_usd", "suites", "variants" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "window_days": { "type": "integer" }, "daily_budget_usd": { "type": "string" }, "suites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "inference": { "type": "string" }, "metric": { "type": "string" }, "direction": { "type": "string", "enum": [ "higher", "lower" ] }, "unit": { "type": "string", "enum": [ "percent", "score" ] }, "source": { "type": "string" }, "description": { "type": "string" }, "unavailable_reason": { "type": "string" } } } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "model_id", "model_name", "provider", "provider_slug", "quantization", "inference", "inference_types", "results" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model_id": { "type": "string" }, "model_name": { "type": "string" }, "provider": { "type": "string" }, "provider_slug": { "type": "string" }, "quantization": { "type": [ "string", "null" ] }, "inference": { "type": "string" }, "inference_types": { "type": "array", "items": { "type": "string" } }, "not_applicable": { "type": "object", "description": "Suites this variant never collects, keyed by suite id, with the reason.", "additionalProperties": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "required": [ "suite_id", "run_id", "protocol", "provenance", "state", "expected", "completed", "score", "metrics", "started_at", "completed_at", "cost_per_task", "actual_cost", "duration_ms", "answer_characters", "completion_tokens", "reasoning_tokens", "missing_reason" ], "properties": { "suite_id": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "protocol": { "type": "string", "description": "Hash of the complete dataset and evaluation protocol." }, "comparison_protocol": { "type": "string", "description": "Comparison identity retaining the full protocol except provider chat output ceilings. The exact request settings remain in provenance." }, "sample_fingerprint": { "type": "string", "description": "Hash of the scored item/repetition set; partial averages require an identical sample." }, "provenance": { "type": "object", "properties": { "dataset_revision": { "type": "string" }, "evaluator_revision": { "type": "string" }, "protocol": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "sources": { "type": "array", "items": { "type": "string" } } } }, "state": { "type": "string", "enum": [ "collecting", "complete", "blocked" ] }, "expected": { "type": "integer" }, "completed": { "type": "integer" }, "repetitions": { "type": "integer", "description": "Required trials per dataset question." }, "prerequisite_expected": { "type": "integer", "description": "Required corpus preparation batches, separate from scored queries." }, "prerequisite_completed": { "type": "integer" }, "score": { "type": [ "number", "null" ] }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_per_task": { "type": [ "string", "null" ], "description": "Decimal USD per scored task, repriced at current rates." }, "actual_cost": { "type": [ "string", "null" ], "description": "Measured historical spend across all attempts." }, "recorded_cost_per_task": { "type": [ "string", "null" ], "description": "Settled historical charges for scored tasks and corpus preparation divided by scored tasks. Excludes failed attempts and unbilled unknown usage; not an estimate at current rates." }, "duration_ms": { "type": [ "number", "null" ] }, "answer_characters": { "type": [ "number", "null" ] }, "completion_tokens": { "type": [ "number", "null" ] }, "reasoning_tokens": { "type": [ "number", "null" ] }, "missing_reason": { "type": [ "string", "null" ] } } } } } } } } } } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The figures are being computed and will be served shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } } } } } }, "/benchmarks/variants/{endpointId}": { "get": { "operationId": "getBenchmarkVariant", "summary": "Benchmark task evidence for a serving variant", "tags": [ "catalogue" ], "security": [], "description": "Current variant results and up to 1,000 task attempts per selected run. No customer requests, answer text, internal generation identifiers or credentials are included. Computed at most once a minute per gateway, and served for up to ten minutes past that while it is recomputed; `Last-Modified` states when. A reader waits at most six seconds for a computation and is otherwise answered 503 with `Retry-After` while it completes.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The currently served endpoint UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Variant and bounded task evidence in a data envelope.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "variant", "tasks" ], "properties": { "variant": { "type": "object", "required": [ "id", "model_id", "model_name", "provider", "provider_slug", "quantization", "inference", "inference_types", "results" ], "properties": { "id": { "type": "string", "format": "uuid" }, "model_id": { "type": "string" }, "model_name": { "type": "string" }, "provider": { "type": "string" }, "provider_slug": { "type": "string" }, "quantization": { "type": [ "string", "null" ] }, "inference": { "type": "string" }, "inference_types": { "type": "array", "items": { "type": "string" } }, "not_applicable": { "type": "object", "description": "Suites this variant never collects, keyed by suite id, with the reason.", "additionalProperties": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "required": [ "suite_id", "run_id", "protocol", "provenance", "state", "expected", "completed", "score", "metrics", "started_at", "completed_at", "cost_per_task", "actual_cost", "duration_ms", "answer_characters", "completion_tokens", "reasoning_tokens", "missing_reason" ], "properties": { "suite_id": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "protocol": { "type": "string", "description": "Hash of the complete dataset and evaluation protocol." }, "comparison_protocol": { "type": "string", "description": "Comparison identity retaining the full protocol except provider chat output ceilings. The exact request settings remain in provenance." }, "sample_fingerprint": { "type": "string", "description": "Hash of the scored item/repetition set; partial averages require an identical sample." }, "provenance": { "type": "object", "properties": { "dataset_revision": { "type": "string" }, "evaluator_revision": { "type": "string" }, "protocol": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "sources": { "type": "array", "items": { "type": "string" } } } }, "state": { "type": "string", "enum": [ "collecting", "complete", "blocked" ] }, "expected": { "type": "integer" }, "completed": { "type": "integer" }, "repetitions": { "type": "integer", "description": "Required trials per dataset question." }, "prerequisite_expected": { "type": "integer", "description": "Required corpus preparation batches, separate from scored queries." }, "prerequisite_completed": { "type": "integer" }, "score": { "type": [ "number", "null" ] }, "metrics": { "type": "object", "additionalProperties": { "type": "number" } }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_per_task": { "type": [ "string", "null" ], "description": "Decimal USD per scored task, repriced at current rates." }, "actual_cost": { "type": [ "string", "null" ], "description": "Measured historical spend across all attempts." }, "recorded_cost_per_task": { "type": [ "string", "null" ], "description": "Settled historical charges for scored tasks and corpus preparation divided by scored tasks. Excludes failed attempts and unbilled unknown usage; not an estimate at current rates." }, "duration_ms": { "type": [ "number", "null" ] }, "answer_characters": { "type": [ "number", "null" ] }, "completion_tokens": { "type": [ "number", "null" ] }, "reasoning_tokens": { "type": [ "number", "null" ] }, "missing_reason": { "type": [ "string", "null" ] } } } } } }, "tasks": { "type": "object", "additionalProperties": { "type": "array", "maxItems": 1000, "items": { "type": "object", "properties": { "item": { "type": "string" }, "repetition": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "pending", "evaluation_error", "scored", "collected", "transport_error", "invalid", "truncated" ] }, "score": { "type": [ "number", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "answer_characters": { "type": [ "integer", "null" ] } } } } } } } } } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "404": { "description": "Variant is not currently served." }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The figures are being computed and will be served shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } } } } } }, "/stats/public": { "get": { "operationId": "getPublicStats", "summary": "Marketplace usage", "description": "Usage aggregates over the last 30 days for the public rankings and activity pages. Every billed request counts, the marketplace's own paid probe traffic included. Counts only, no money. Requests are the one measure every API type has, so `models` and `authors` are ranked on them; `tokens` is null where no request of the model, author or API type reported a token count, as for an image or video generation, and a null is never a zero. Unwrapped: no `data` envelope. Computed at most once a minute per gateway, and served for up to five minutes past that while it is recomputed; `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The aggregates.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "totals": { "requests": 128410, "tokens": 984120333, "models_served": 42 }, "window_days": 30, "daily": [ { "date": "2026-08-16", "requests": 4210, "prompt_tokens": 30112004, "completion_tokens": 1840221, "requests_by_api_type": { "chat": 3900, "images": 310 }, "tokens_by_api_type": { "chat": 31952225 } } ], "api_types": [ { "api_type": "chat", "requests": 118200, "tokens": 984120333 }, { "api_type": "images", "requests": 10210, "tokens": null } ], "models": [ { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "author": "deepseek", "name": "DeepSeek V4 Flash 0731", "api_type": "chat", "requests": 8102, "tokens": 61200311 } ], "authors": [ { "author": "deepseek", "requests": 8102, "tokens": 61200311, "share": 0.42 } ] } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/site-discount": { "get": { "operationId": "getSiteDiscount", "summary": "Active site promotion", "description": "The site promotion shown to customers. A provider endpoint discount counts toward the promotion; the customer receives the larger fraction. An absent or expired promotion returns `discount: null`. The response is not cached.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "The active promotion or null.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "discount" ], "properties": { "discount": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "fraction", "ends_at" ], "properties": { "fraction": { "type": "string", "description": "Exact decimal fraction between zero and one." }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] } } } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/promotions": { "get": { "operationId": "getPromotions", "summary": "Active marketplace promotions", "description": "The site offer and approved providers with an active catalogue offer and a live model endpoint. An endpoint discount counts toward the larger active offer. The response is not cached.", "tags": [ "catalogue" ], "security": [], "responses": { "200": { "description": "Active site and provider promotions.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "site", "providers" ], "properties": { "site": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "fraction", "ends_at" ], "properties": { "fraction": { "type": "string", "description": "Exact decimal fraction between zero and one." }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "providers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "fraction", "ends_at" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "fraction": { "type": "string" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "The status board", "description": "Every approved provider with its live endpoints' health, measured uptime, response time, the most recent error and success over a 7-day window, and a 24-hour hourly history. Response time rather than time to first token, because every endpoint has one and an endpoint that never streams has no first-token figure. `uptime_1d_samples` is the counted attempts behind `uptime_1d`, which is what separates a measured 100% from a lucky one. History buckets exist only for hours that had attempts. Unwrapped: no `data` envelope. Computed at most once every 30 seconds per gateway, and never served older than that: a read past it waits for the recomputation. `Last-Modified` states when.", "tags": [ "catalogue" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "description": "Validators from earlier responses; a current match returns 304 without a body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The board, providers by slug and endpoints by model then endpoint id.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Validator of the exact response body." }, "Last-Modified": { "schema": { "type": "string" }, "description": "When these figures were computed." } }, "content": { "application/json": { "example": { "providers": [ { "slug": "impcc", "name": "ImpCC", "endpoints": [ { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "endpoint_id": "5f0c…", "health": "healthy", "uptime_1d": 98.7, "uptime_1d_samples": 1240, "uptime_7d": 99.2, "response_p50": 2.61, "response_1d_p50": 2.74, "last_error": { "at": "2026-08-16T11:04:05.000Z", "status_code": 500, "error_type": "provider_error" }, "last_success_at": "2026-08-16T11:59:31.000Z", "history": [ { "hour": "2026-08-16T11:00:00.000Z", "ok": 118, "error": 2 } ] } ] } ] } } } }, "304": { "description": "The body is the one If-None-Match names; no response body." }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/key": { "get": { "operationId": "getKey", "summary": "The presented key", "description": "What the key is, what it has spent and what its ceiling leaves. `limit_remaining` is measured over the window the ceiling resets in, so a monthly ceiling is compared against this month. A key with no ceiling reports `null` for all three ceiling fields rather than a zero.", "tags": [ "account" ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "example": { "data": { "label": "sk-hd-v1-3f9a…", "name": "production", "limit": 10, "limit_remaining": 4.5, "limit_reset": "monthly", "usage": 5.5, "usage_daily": 0.2, "usage_weekly": 1.1, "usage_monthly": 5.5, "is_free_tier": false, "expires_at": null } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/key": { "get": { "operationId": "getKeyAlias", "summary": "The presented key (alias)", "description": "The same read as `GET /key`, served at the path a Bifrost OpenRouter provider validates a key against before it routes anything. Answers identically.", "tags": [ "account" ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "example": { "data": { "label": "sk-hd-v1-3f9a…", "name": "production", "limit": 10, "limit_remaining": 4.5, "limit_reset": "monthly", "usage": 5.5, "usage_daily": 0.2, "usage_weekly": 1.1, "usage_monthly": 5.5, "is_free_tier": false, "expires_at": null } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/keys": { "post": { "operationId": "exchangeAuthCode", "summary": "Trade an authorization code for a key", "description": "The second half of the PKCE flow. An application sends a person to `/auth` on the site with a `callback_url` and the S256 `code_challenge` of a verifier it keeps; approving there returns the browser to the callback with a one-time `code`, and this route trades that code and the verifier for a key. The code lives ten minutes and is consumed as it is read, so a retry is refused exactly as a replay is. The key belongs to the approving account, is named after the callback origin, and is listed and revocable beside every other key on their account page. No credential opens this route: the code is the credential, and it is worth nothing without the verifier.", "tags": [ "auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthKeysRequest" }, "example": { "code": "9f1c0a2e5d7b4c8f", "code_verifier": "nR3kQ7pY1sW9zL5xV2bH8mJ4tC6dF0gA3eU7iO1yP5q", "code_challenge_method": "S256" } } } }, "responses": { "200": { "description": "The key, in plaintext. It is shown here and nowhere else.", "content": { "application/json": { "example": { "key": "sk-hd-v1-3f9a…", "user_id": "usr_01J8Z0X2QZ" } } } }, "400": { "description": "The body did not parse, or the code is unknown, expired, already exchanged, issued for another callback, or does not match the verifier. The four are one message: telling them apart would say which codes exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/credits": { "get": { "operationId": "getCredits", "summary": "The account's balance", "description": "Credited and debited totals for the account the key belongs to. The balance is the difference; both figures are exact.", "tags": [ "account" ], "responses": { "200": { "description": "The totals.", "content": { "application/json": { "example": { "data": { "total_credits": 100, "total_usage": 12.3 } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/generation": { "get": { "operationId": "getGeneration", "summary": "One generation", "description": "A recorded generation or a funded request awaiting a final record. record_state is recorded or unrecorded. An unrecorded request does not establish whether execution stopped: final tokens, timings and cost remain null, while reservation reports the recorded state and exact decimal amount. usage_observations contains up to 100 latest per-dispatch measurements, with usage_observations_truncated indicating omitted older attempts. Observations are not summed or declared billable; response_complete establishes receipt, not successful inference or final usage. Absent measurements remain null and explicit zero remains zero. Recorded image/video generations may carry media_billing, a versioned content-free receipt containing the frozen basis, native measurements, per-unit components and exact totalUsd; absent or unsupported receipts are null. Exact quantities use numerator and denominator integer strings. Historical pixel counts keep their unit. Recorded generations retain their recorded token, timing and cost fields; usage_reported carries the provenance of tokens_prompt and tokens_completion, and is true where the endpoint sent a usage document, false where it sent none and the two counts are therefore null, and null for a record written before the verdict existed. Scoped to the key's own account; an id on another account reads as absent.", "tags": [ "account" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The generation id, as returned in `X-Generation-Id` or the response `id`.", "schema": { "type": "string", "example": "gen-01J8Z0X2QZ" } } ], "responses": { "200": { "description": "The generation record or retained request evidence.", "content": { "application/json": { "example": { "data": { "id": "gen-01J8Z0X2QZ", "record_state": "recorded", "model": "deepseek/deepseek-v4-flash-0731-abliterated", "provider_name": "ImpCC", "created_at": "2026-08-16T11:59:31.000Z", "streamed": true, "cancelled": false, "latency": 412, "generation_time": 2198, "finish_reason": "stop", "native_finish_reason": "stop", "tokens_prompt": 9, "tokens_completion": 3, "usage_reported": true, "native_tokens_prompt": 9, "native_tokens_completion": 3, "native_tokens_reasoning": null, "native_tokens_cached": null, "num_media_prompt": null, "total_cost": 0.0000021, "usage": 0.0000021, "cache_discount": null, "app_id": null, "upstream_id": "chatcmpl-abc" } } } } }, "400": { "description": "`id` is missing or empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No generation or funded request with that id on the key's account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/activity": { "get": { "operationId": "getActivity", "summary": "The account's usage for one day", "description": "Requests, tokens and spend for one UTC day on the key's account, in the row shape OpenRouter's `/activity` publishes. Without `date` the day the account's daily spend window is currently in. `group_by` (default `model`) sets what a row is: `model` aggregates across every endpoint and key that served it, `endpoint` splits a model's rows by which endpoint served them, and `key` splits by which API key spent them and adds `api_key_hash` to every row. Grouping only ever splits a day's rows further; the sum of any field over a grouped day's rows equals the same model's row at the default grouping.", "tags": [ "account" ], "parameters": [ { "name": "date", "in": "query", "description": "The UTC day to report, `YYYY-MM-DD`.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-08-16" } }, { "name": "api_key_hash", "in": "query", "description": "Restrict to one API key on the account, by its SHA-256 hash (the form `/key` and the request log publish, never the key itself).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "group_by", "in": "query", "description": "How to split a day into rows: `model` (default), `endpoint` or `key`. See the operation description.", "schema": { "type": "string", "enum": [ "model", "endpoint", "key" ], "default": "model" } }, { "name": "user_id", "in": "query", "description": "Rejected with a `400`: the public API reports the whole account behind the key, not one organization member.", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "description": "Rejected with a `400`: the public API reports the whole account behind the key, not one workspace within it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One row per the requested grouping, ordered by model id.", "content": { "application/json": { "example": { "data": [ { "date": "2026-08-16", "model": "deepseek/deepseek-v4-flash-0731-abliterated", "model_permaslug": "deepseek/deepseek-v4-flash-0731-abliterated", "endpoint_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "provider_name": "Example Compute", "requests": 12, "prompt_tokens": 90210, "completion_tokens": 4821, "reasoning_tokens": 512, "usage": "0.0213", "spend": "0.0213", "byok_usage_inference": "0" } ] } } } }, "400": { "description": "`date` is not a UTC date in `YYYY-MM-DD` form, `group_by` is not `model`, `endpoint` or `key`, `api_key_hash` is not a 64-character lowercase hex hash, or `user_id`/`workspace_id` was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/status": { "get": { "operationId": "getProviderStatus", "summary": "The presented key's provider: endpoints and last pull", "description": "The provider the presented key's account belongs to: every live, pending-health, provider-not-ready or disabled endpoint it serves, with the same health, measured figures and pricing `GET /models/{author}/{slug}/endpoints` publishes about them to a customer choosing one, beside the outcome of the most recent pull of any of the provider's source documents. Each endpoint also carries its probe schedule as `last_probe`, and what its newest failed probe was answered with as `last_failure` — including the status your own server returned and the path it was asked for, which is the one place an origin routing a rail nowhere can be told from a marketplace fault. Both are `null` where there is nothing to report, never a zero. `last_pull` is `null` before the first pull. Withdrawn endpoints are not listed and are not counted; the provider dashboard's own `include=withdrawn` view has no equivalent here.", "tags": [ "provider" ], "responses": { "200": { "description": "The provider's endpoints and its last pull.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "models", "withdrawn_count", "last_pull" ], "properties": { "models": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "model_id": { "type": "string" }, "model_name": { "type": "string" }, "endpoint_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "live", "pending_health", "provider_not_ready", "disabled" ], "description": "Withdrawn endpoints are never listed here." }, "health_tier": { "type": "string", "enum": [ "unknown", "healthy", "degraded", "down" ] }, "quantization": { "type": [ "string", "null" ], "description": "`int2` … `fp32`, or `null` when declared none." }, "context_length": { "type": "integer", "minimum": 0 }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 0 }, "declared_input_modalities": { "type": [ "array", "null" ], "description": "Input modality objects as declared in the source document; `null` when undeclared.", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" } }, "additionalProperties": true } }, "declared_output_modalities": { "type": [ "array", "null" ], "description": "Output modality objects as declared in the source document; `null` when undeclared.", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" } }, "additionalProperties": true } }, "declared_pricing_skus": { "type": "array", "description": "Pricing lines from the provider document, including their qualifiers and overrides.", "items": { "type": "object", "additionalProperties": false, "required": [ "scope", "modality", "type", "unit", "cost_usd" ], "properties": { "scope": { "type": "string", "enum": [ "input", "output", "request" ] }, "modality": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "cost_usd": { "type": "string" }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "when", "cost_usd" ], "properties": { "when": { "$ref": "#/components/schemas/PricingPredicate" }, "cost_usd": { "type": "string" } } } }, "utc_start": { "type": "integer" }, "utc_end": { "type": "integer" }, "utc_days": { "type": "array", "items": { "type": "string" } }, "ttl_seconds": { "type": "integer" }, "implicit": { "type": "boolean" } } } }, "declared_capacity_limits": { "type": "array", "description": "Positive capacity ceilings declared by the provider, distinct from live occupancy.", "items": { "type": "object", "additionalProperties": false, "required": [ "scope", "modality", "type", "unit", "per", "value" ], "properties": { "scope": { "type": "string", "enum": [ "input", "output", "request" ] }, "modality": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "per": { "type": "string" }, "value": { "type": "integer", "minimum": 1 } } } }, "pricing": { "type": "object", "additionalProperties": false, "description": "This endpoint's declared prices, decimal strings per unit. Every key names the unit it meters. A unit the endpoint declared no price for is absent from this object, never `0`. Native media scalar keys are present only for one unambiguous, unconditional output tariff; conditional and windowed native rates are omitted from the scalar projection. A price per audio input token is never published, because the marketplace holds no price in that unit.", "properties": { "prompt": { "type": "string", "description": "USD per input token." }, "completion": { "type": "string", "description": "USD per output token." }, "input_cache_read": { "type": "string", "description": "USD per prompt token read from cache." }, "input_cache_write": { "type": "string", "description": "USD per prompt token written to cache." }, "internal_reasoning": { "type": "string", "description": "USD per reasoning token, where the endpoint prices reasoning apart from completion." }, "request": { "type": "string", "description": "USD per request, charged flat." }, "image_megapixel": { "type": "string", "description": "USD per 1,000,000 pixels of delivered image output under a linear area tariff." }, "audio_second": { "type": "string", "description": "USD per second of audio, whether consumed on a transcription or generated in a reply." }, "character": { "type": "string", "description": "USD per character synthesized." }, "input_cache_write_1h": { "type": "string", "description": "USD per prompt token written to a cache that holds it for an hour, where the endpoint prices that lifetime apart from its default one. `input_cache_write` is the price of a write carrying no lifetime." }, "image": { "type": "string", "description": "USD per image supplied in the prompt, charged per image rather than per pixel." }, "audio_output": { "type": "string", "description": "USD per audio token generated in a reply." }, "image_output": { "type": "string", "description": "USD per delivered output image." }, "image_output_token": { "type": "string", "description": "USD per output image token. Heimdallm extension." }, "video_second": { "type": "string", "description": "USD per second of delivered video output, including fractional seconds. Heimdallm extension." }, "mesh_output": { "type": "string", "description": "USD per delivered mesh, charged whole. The face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. Heimdallm extension." }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "Conditional prices. All conditions in an entry must match; later matching entries win per price key. Windowed rates follow default-rate overrides, with declaration order preserved within each group. Present only where at least one condition can be represented." } } }, "discount_to_user": { "type": [ "number", "null" ], "description": "The fraction this endpoint's document takes off its declared prices, or `null` where it declares none. This is the declaration itself, so absence is never spelled `0` here." }, "is_free": { "type": "boolean", "description": "Whether this endpoint's document declares it free. A free endpoint is served at no cost: every unit its document prices is charged at zero, whatever figures `pricing` quotes beside the flag, and a unit the document prices nowhere is still unpriced rather than free." }, "effective_pricing": { "type": "object", "additionalProperties": { "type": "string" }, "description": "What a customer is charged per unit: the prices above with this endpoint's discount applied, or `\"0\"` throughout where the document declares the endpoint free, in the same unit vocabulary and with the same units absent. Identical to `pricing` where neither is declared." }, "pricing_overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "The conditional prices this endpoint declares, as the public catalogue projects them: each a condition field beside the declared price it selects. Empty where the document states one price per unit. A condition the projection carries no field for keeps its price out rather than publishing a rate without what selects it, and the unit names are the catalogue's rather than the document's, because the projection is the reading that decides which conditions can be stated at all." }, "effective_pricing_overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "The same rows as a customer is charged them, with this endpoint's discount applied. Identical to `pricing_overrides` where no discount is declared." }, "measured_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the figures below were last computed. `null` for an endpoint nothing has measured." }, "uptime_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "ttft_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "response_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_5m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_5m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_30m": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "uptime_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "uptime_last_7d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "latency_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "latency_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_30m_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "throughput_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "throughput_last_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "ttft_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "ttft_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_30m": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "response_last_1d": { "type": [ "object", "null" ], "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } }, "required": [ "p50", "p75", "p90", "p99" ] }, "perf_last_30m_by_workload": { "type": "null" }, "render_timing": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "fixed_seconds", "seconds_per_megapixel" ], "description": "What a render costs before it draws anything and what each megapixel adds, gated the same as any other measured figure. `null` until the gate clears; `render_timing_samples` and `render_timing_sizes` are published beside it whether or not it has, so a reader can tell a window short of the gate from an endpoint no rendering traffic has reached.", "properties": { "fixed_seconds": { "type": "number", "minimum": 0 }, "seconds_per_megapixel": { "type": "number", "minimum": 0 } } }, "render_timing_samples": { "type": [ "integer", "null" ], "minimum": 0, "description": "Renders counted toward `render_timing`, across every size, whether or not the gate cleared." }, "render_timing_sizes": { "type": [ "integer", "null" ], "minimum": 0, "description": "The distinct sizes among those renders, the fit's second gate." }, "tool_call_success_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of the day's demanded tool asks (`tool_choice: \"required\"` or a named function) that produced a tool call. `null` short of the sample gate, which an `\"auto\"` turn never counts against either way." }, "tool_call_success_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "runaway_rate_1d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The measured share of generations that ran away, per day." }, "runaway_rate_1d_samples": { "type": [ "integer", "null" ], "minimum": 0 }, "zdr_status": { "type": [ "string", "null" ], "enum": [ "pending", "approved", "denied", null ], "description": "The provider-wide ZDR vetting verdict, where this endpoint declares the claim; `null` where it declares none." }, "zdr_note": { "type": [ "string", "null" ], "description": "The reason a denial was given. Present only beside a `denied` zdr_status." }, "last_probe": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "at", "outcome", "error", "requested_at", "next_at" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a probe last ran against this endpoint. `null` where none has run yet." }, "outcome": { "type": [ "string", "null" ], "enum": [ "success", "error", "capability", "client_error", "aborted", "infrastructure", "blocked_address", null ], "description": "How that probe ended. `null` where none has run yet." }, "error": { "type": [ "string", "null" ], "description": "What the probe wrote about the failure. `null` where the last probe succeeded." }, "requested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a probe was last asked for through `POST /providers/probe-now`. A request is still outstanding while this is newer than `at`." }, "next_at": { "type": "string", "format": "date-time", "description": "When the next probe is due." } } }, { "type": "null" } ], "description": "The probe schedule of this endpoint, or `null` where no probe has ever been planned against it." }, "last_failure": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "at", "status", "error_type", "upstream_status", "upstream_path", "upstream_message" ], "properties": { "at": { "type": "string", "format": "date-time", "description": "When the failed attempt was recorded." }, "status": { "type": [ "integer", "null" ], "description": "The status the marketplace mapped the answer to and handed the caller. `null` where the attempt was recorded without one." }, "error_type": { "type": [ "string", "null" ], "description": "How the marketplace classified the failure, e.g. `provider_unavailable`." }, "upstream_status": { "type": [ "integer", "null" ], "description": "The status your own server answered with. `null` where no server answered: a fault on the marketplace’s side, a timeout, or an address it does not connect to." }, "upstream_path": { "type": [ "string", "null" ], "description": "The path your server was asked for, which is what an origin routing a rail nowhere answers 404 to. `null` where no server answered." }, "upstream_message": { "type": [ "string", "null" ], "description": "The sentence your server returned beside that status. `null` where it returned none, and never present for a customer’s own request." } } }, { "type": "null" } ], "description": "What the newest failed probe of this endpoint was answered with, or `null` where no probe of it has failed. A customer’s own failed request is never reported here." }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" } }, "required": [ "model_id", "model_name", "endpoint_id", "status", "health_tier", "quantization", "context_length", "max_completion_tokens", "declared_input_modalities", "declared_output_modalities", "declared_pricing_skus", "declared_capacity_limits", "pricing", "discount_to_user", "is_free", "effective_pricing", "pricing_overrides", "effective_pricing_overrides", "measured_at", "uptime_samples", "ttft_samples", "response_samples", "uptime_last_5m", "uptime_last_5m_samples", "uptime_last_30m", "uptime_last_30m_samples", "uptime_last_1d", "uptime_last_1d_samples", "uptime_last_7d", "latency_last_30m", "latency_last_30m_samples", "throughput_last_30m", "throughput_last_30m_samples", "throughput_last_1d", "throughput_last_1d_samples", "ttft_last_30m", "ttft_last_1d", "response_last_30m", "response_last_1d", "perf_last_30m_by_workload", "render_timing", "render_timing_samples", "render_timing_sizes", "tool_call_success_1d", "tool_call_success_1d_samples", "runaway_rate_1d", "runaway_rate_1d_samples", "zdr_status", "zdr_note", "last_probe", "last_failure", "first_seen_at", "last_seen_at" ] } }, "withdrawn_count": { "type": "integer", "minimum": 0, "description": "Endpoints withdrawn from this provider, not counted among `models`." }, "last_pull": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "source_id", "trigger", "outcome", "http_status", "started_at", "finished_at", "models_seen", "endpoints_upserted", "endpoints_withdrawn", "errors", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "admin" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "ok", "partial", "invalid", "unreachable", "unauthorized", "blocked_address", null ], "description": "`null` while the pull has not finished." }, "http_status": { "type": [ "integer", "null" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "models_seen": { "type": "integer", "minimum": 0 }, "endpoints_upserted": { "type": "integer", "minimum": 0 }, "endpoints_withdrawn": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "doc_id", "path", "code", "message" ], "properties": { "doc_id": { "type": [ "string", "null" ], "description": "The model id the issue is about; `null` for one about the document as a whole." }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "doc_id", "path", "code", "message" ], "properties": { "doc_id": { "type": [ "string", "null" ], "description": "The model id the issue is about; `null` for one about the document as a whole." }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, { "type": "null" } ], "description": "The most recent pull of any of this provider’s sources, or `null` before the first." } } }, "example": { "models": [ { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "model_name": "Acme: Base 1", "endpoint_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "live", "health_tier": "healthy", "quantization": "fp16", "context_length": 131072, "max_completion_tokens": 8192, "pricing": { "prompt": "0.000002", "completion": "0.000004" }, "measured_at": "2026-08-16T11:59:31.000Z", "uptime_samples": 1240, "ttft_samples": 84, "response_samples": 84, "uptime_last_5m": 100, "uptime_last_5m_samples": 12, "uptime_last_30m": 100, "uptime_last_30m_samples": 60, "uptime_last_1d": 98.7, "uptime_last_1d_samples": 1240, "uptime_last_7d": 99.2, "latency_last_30m": null, "latency_last_30m_samples": 3, "throughput_last_30m": null, "throughput_last_30m_samples": 3, "throughput_last_1d": null, "throughput_last_1d_samples": 3, "ttft_last_30m": null, "ttft_last_1d": null, "response_last_30m": { "p50": 2.61, "p75": 2.9, "p90": 3.4, "p99": 4.1 }, "response_last_1d": { "p50": 2.74, "p75": 3.05, "p90": 3.5, "p99": 4.3 }, "perf_last_30m_by_workload": null, "render_timing": null, "render_timing_samples": 0, "render_timing_sizes": 0, "tool_call_success_1d": 98.2, "tool_call_success_1d_samples": 340, "runaway_rate_1d": 1.4, "runaway_rate_1d_samples": 620, "zdr_status": null, "zdr_note": null, "last_probe": { "at": "2026-08-16T11:59:31.000Z", "outcome": "success", "error": null, "requested_at": null, "next_at": "2026-08-16T12:29:31.000Z" }, "last_failure": null, "first_seen_at": "2026-06-01T00:00:00.000Z", "last_seen_at": "2026-08-16T11:59:31.000Z" }, { "model_id": "acme/rerank-1", "model_name": "Acme: Rerank 1", "endpoint_id": "7c2d1b90-4e6a-4f3b-9c5d-8a1e2f4b6c0d", "status": "pending_health", "health_tier": "unknown", "quantization": null, "context_length": 8192, "max_completion_tokens": null, "pricing": { "request": "0.000002" }, "measured_at": null, "uptime_samples": null, "ttft_samples": null, "response_samples": null, "uptime_last_5m": null, "uptime_last_5m_samples": null, "uptime_last_30m": null, "uptime_last_30m_samples": null, "uptime_last_1d": null, "uptime_last_1d_samples": null, "uptime_last_7d": null, "latency_last_30m": null, "latency_last_30m_samples": null, "throughput_last_30m": null, "throughput_last_30m_samples": null, "throughput_last_1d": null, "throughput_last_1d_samples": null, "ttft_last_30m": null, "ttft_last_1d": null, "response_last_30m": null, "response_last_1d": null, "perf_last_30m_by_workload": null, "render_timing": null, "render_timing_samples": null, "render_timing_sizes": null, "tool_call_success_1d": null, "tool_call_success_1d_samples": null, "runaway_rate_1d": null, "runaway_rate_1d_samples": null, "zdr_status": null, "zdr_note": null, "last_probe": { "at": "2026-08-16T11:57:02.000Z", "outcome": "error", "error": "the endpoint answered 502 provider_unavailable", "requested_at": "2026-08-16T11:56:40.000Z", "next_at": "2026-08-16T12:57:02.000Z" }, "last_failure": { "at": "2026-08-16T11:57:02.000Z", "status": 502, "error_type": "provider_unavailable", "upstream_status": 404, "upstream_path": "/v1/rerank", "upstream_message": "not found" }, "first_seen_at": "2026-08-10T00:00:00.000Z", "last_seen_at": "2026-08-16T11:57:02.000Z" } ], "withdrawn_count": 0, "last_pull": { "id": "9c1f6a2e-1b3d-4c5f-8a7e-2d6b0c4f8a1e", "source_id": "5f0c7e2a-3b1d-4a6f-9c8e-1d2b3a4c5e6f", "trigger": "manual", "outcome": "ok", "http_status": 200, "started_at": "2026-08-16T11:58:00.000Z", "finished_at": "2026-08-16T11:58:04.000Z", "models_seen": 1, "endpoints_upserted": 1, "endpoints_withdrawn": 0, "errors": [], "warnings": [] } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The presented key’s account does not belong to a provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/pull-now": { "post": { "operationId": "postProviderPullNow", "summary": "Pull the presented key's provider's models document now", "description": "Re-reads one of the provider's source documents immediately rather than waiting for its schedule, and returns the resulting pull run. `source_id` names which source; it is optional only where the provider holds exactly one active (enabled, not admin-disabled) source, and required where it holds more than one. Refused, at the same interval the schedule itself keeps to, when the named source (or the provider's whole set of sources when none is named) was pulled too recently — `Retry-After` names when it may be asked again. The provider must be approved.", "tags": [ "provider" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source_id": { "type": "string", "format": "uuid", "description": "Which source to pull. Omitted, the provider’s one active source is pulled; refused with a 400 where more than one is active." } } }, "example": {} } } }, "responses": { "200": { "description": "The pull that was just run.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "run" ], "properties": { "run": { "type": "object", "additionalProperties": false, "required": [ "id", "source_id", "trigger", "outcome", "http_status", "started_at", "finished_at", "models_seen", "endpoints_upserted", "endpoints_withdrawn", "errors", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "admin" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "ok", "partial", "invalid", "unreachable", "unauthorized", "blocked_address", null ], "description": "`null` while the pull has not finished." }, "http_status": { "type": [ "integer", "null" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "models_seen": { "type": "integer", "minimum": 0 }, "endpoints_upserted": { "type": "integer", "minimum": 0 }, "endpoints_withdrawn": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "doc_id", "path", "code", "message" ], "properties": { "doc_id": { "type": [ "string", "null" ], "description": "The model id the issue is about; `null` for one about the document as a whole." }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "doc_id", "path", "code", "message" ], "properties": { "doc_id": { "type": [ "string", "null" ], "description": "The model id the issue is about; `null` for one about the document as a whole." }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "run": { "id": "9c1f6a2e-1b3d-4c5f-8a7e-2d6b0c4f8a1e", "source_id": "5f0c7e2a-3b1d-4a6f-9c8e-1d2b3a4c5e6f", "trigger": "manual", "outcome": "ok", "http_status": 200, "started_at": "2026-08-16T11:58:00.000Z", "finished_at": "2026-08-16T11:58:04.000Z", "models_seen": 1, "endpoints_upserted": 1, "endpoints_withdrawn": 0, "errors": [], "warnings": [] } } } } }, "400": { "description": "`source_id` is not a UUID, names no source of this provider, or was left out while the provider holds more than one active source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The provider is not approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The presented key’s account does not belong to a provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The named source is disabled, or the provider holds no active source to pull.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/probe-now": { "post": { "operationId": "postProviderProbeNow", "summary": "Probe one of the presented key’s provider’s endpoints now", "description": "Makes one endpoint due for a health probe immediately rather than waiting out the failure backoff, which holds a repeatedly failing endpoint for as long as its streak says. `endpoint_id` names the endpoint and must be one of this provider's; a withdrawn endpoint, and one belonging to somebody else, are both answered as though they did not exist. The answer is the schedule rather than a verdict: the probe runs on the marketplace's next tick, and the request has been served once `last_probe` on `GET /providers/status` reports an `at` newer than its `requested_at`. Refused when the endpoint was probed, or asked for, too recently — `Retry-After` names when it may be asked again. The provider must be approved.", "tags": [ "provider" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "endpoint_id" ], "properties": { "endpoint_id": { "type": "string", "format": "uuid", "description": "Which endpoint to probe, as `GET /providers/status` publishes it. One endpoint is always named: a provider lists many, and every probe is a real paid request." } } }, "example": { "endpoint_id": "7c2d1b90-4e6a-4f3b-9c5d-8a1e2f4b6c0d" } } } }, "responses": { "200": { "description": "The endpoint’s schedule, with the request recorded on it.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schedule" ], "properties": { "schedule": { "type": "object", "additionalProperties": false, "required": [ "endpoint_id", "requested_at", "next_probe_at", "last_probe_at" ], "properties": { "endpoint_id": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time", "description": "When this request was recorded." }, "next_probe_at": { "type": "string", "format": "date-time", "description": "When the endpoint is due. A request makes it due at once; the probe itself runs on the next tick." }, "last_probe_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a probe last ran against this endpoint, or `null` where none has run yet. The request has been served once this passes `requested_at`." } } } } }, "example": { "schedule": { "endpoint_id": "7c2d1b90-4e6a-4f3b-9c5d-8a1e2f4b6c0d", "requested_at": "2026-08-16T12:04:00.000Z", "next_probe_at": "2026-08-16T12:04:00.000Z", "last_probe_at": "2026-08-16T11:57:02.000Z" } } } } }, "400": { "description": "`endpoint_id` is missing or is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The provider is not approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The presented key’s account does not belong to a provider, or names no endpoint of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/earnings": { "get": { "operationId": "getProviderEarnings", "summary": "The presented key's provider's earnings", "description": "The provider's earnings for one month: totals, a breakdown by model, and a breakdown by the statement that claims each part (a part not yet claimed by any statement reads `statement: null`). Every amount is an exact decimal USD string. Without `month`, the current month.", "tags": [ "provider" ], "parameters": [ { "name": "month", "in": "query", "description": "The UTC month to report, `YYYY-MM`. Defaults to the current month.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-08" } } ], "responses": { "200": { "description": "The month's earnings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "month", "totals", "by_model", "by_statement" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "totals": { "type": "object", "additionalProperties": false, "required": [ "gross", "platform_cut", "net", "generation_count" ], "properties": { "gross": { "type": "string", "description": "Exact decimal USD, before the platform cut." }, "platform_cut": { "type": "string", "description": "Exact decimal USD the marketplace retains." }, "net": { "type": "string", "description": "Exact decimal USD paid to the provider: gross minus platform_cut." }, "generation_count": { "type": "integer", "minimum": 0 } } }, "by_model": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "model_id", "gross", "platform_cut", "net", "generation_count" ], "properties": { "model_id": { "type": "string" }, "gross": { "type": "string" }, "platform_cut": { "type": "string" }, "net": { "type": "string" }, "generation_count": { "type": "integer", "minimum": 0 } } } }, "by_statement": { "type": "array", "description": "Which statement pays each part of the month. A statement claims the earnings unclaimed when its period closed, so a month can split across the statement of the month and a later one that picked up a late arrival; the part nothing has claimed yet carries `statement: null`.", "items": { "type": "object", "additionalProperties": false, "required": [ "statement", "gross", "platform_cut", "net", "generation_count" ], "properties": { "statement": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "period_start", "period_end", "status", "payout_reference", "paid_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "open", "finalized", "held", "paid" ] }, "payout_reference": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "null" } ] }, "gross": { "type": "string" }, "platform_cut": { "type": "string" }, "net": { "type": "string" }, "generation_count": { "type": "integer", "minimum": 0 } } } } } }, "example": { "month": "2026-08", "totals": { "gross": "182.400000", "platform_cut": "18.240000", "net": "164.160000", "generation_count": 9130 }, "by_model": [ { "model_id": "deepseek/deepseek-v4-flash-0731-abliterated", "gross": "182.400000", "platform_cut": "18.240000", "net": "164.160000", "generation_count": 9130 } ], "by_statement": [ { "statement": { "id": "2c9e4f7a-8b1d-4e6a-9f3c-7d2b5a8e1c4f", "period_start": "2026-08-01", "period_end": "2026-09-01", "status": "open", "payout_reference": null, "paid_at": null }, "gross": "182.400000", "platform_cut": "18.240000", "net": "164.160000", "generation_count": 9130 } ] } } } }, "400": { "description": "`month` is not formatted `YYYY-MM`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The presented key’s account does not belong to a provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/statements": { "get": { "operationId": "getProviderStatements", "summary": "The presented key's provider's statement history", "description": "Every statement issued to the provider, newest period first. `earliest_earned_month` is the earliest month of an earning the statement claims, which reads earlier than `period_start` when the statement picked up an earning that settled after its own month was already paid.", "tags": [ "provider" ], "responses": { "200": { "description": "The statement history.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "statements" ], "properties": { "statements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "period_start", "period_end", "gross", "platform_cut", "net", "generation_count", "status", "payout_reference", "paid_at", "created_at", "earliest_earned_month" ], "properties": { "id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "gross": { "type": "string" }, "platform_cut": { "type": "string" }, "net": { "type": "string" }, "generation_count": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "open", "finalized", "held", "paid" ] }, "payout_reference": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "earliest_earned_month": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "The earliest month of an earning this statement claims. Reads earlier than period_start when the statement picked up an earning that settled after its own month was already paid; `null` where the statement claims nothing yet." } } } } } }, "example": { "statements": [ { "id": "2c9e4f7a-8b1d-4e6a-9f3c-7d2b5a8e1c4f", "period_start": "2026-07-01", "period_end": "2026-08-01", "gross": "150.000000", "platform_cut": "15.000000", "net": "135.000000", "generation_count": 8010, "status": "paid", "payout_reference": "0xabc123…", "paid_at": "2026-08-05T00:00:00.000Z", "created_at": "2026-08-01T00:05:00.000Z", "earliest_earned_month": "2026-07" } ] } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The presented key’s account does not belong to a provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/keys": { "get": { "operationId": "listKeys", "summary": "List keys", "description": "Every key in the management key's own workspace, newest first. Served only to a management key.", "tags": [ "keys" ], "responses": { "200": { "description": "The keys.", "content": { "application/json": { "example": { "data": [ { "hash": "3fa85f64571745...", "name": "customer instance", "label": "sk-hd-v1-3f9a…", "disabled": false, "limit": "10", "limit_reset": "monthly", "usage": "0", "created_at": "2026-08-16T11:59:31.000Z", "updated_at": "2026-08-16T11:59:31.000Z" } ] } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A management key was sent to a route it cannot use: `/keys` is served only to a management key, and a management key is refused everywhere else because it never spends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createKey", "summary": "Create a key", "description": "A new key in the management key's own workspace. `key` carries the plaintext, returned once and never stored; `data.hash` is its SHA-256 hex, the identifier every other route in this section addresses it by. A key created here spends against the same account balance the management key's own workspace draws from.", "tags": [ "keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyCreateRequest" }, "example": { "name": "customer instance", "limit": "10", "limit_reset": "monthly" } } } }, "responses": { "201": { "description": "The key, with its plaintext.", "content": { "application/json": { "example": { "key": "sk-hd-v1-3f9a2c…", "data": { "hash": "3fa85f64571745...", "name": "customer instance", "label": "sk-hd-v1-3f9a…", "disabled": false, "limit": "10", "limit_reset": "monthly", "usage": "0", "created_at": "2026-08-16T11:59:31.000Z", "updated_at": "2026-08-16T11:59:31.000Z" } } } } }, "400": { "description": "The body did not parse, or `name` is the reserved shape of a playground grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A management key was sent to a route it cannot use: `/keys` is served only to a management key, and a management key is refused everywhere else because it never spends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/keys/{hash}": { "get": { "operationId": "getKeyByHash", "summary": "Read one key", "description": "One key, by the hash `POST /keys` or `GET /keys` reported for it.", "tags": [ "keys" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "The key’s SHA-256 hex, as `POST /keys` or `GET /keys` reported it.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "example": "3fa85f64571745..." } } ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "example": { "data": { "hash": "3fa85f64571745...", "name": "customer instance", "label": "sk-hd-v1-3f9a…", "disabled": false, "limit": "10", "limit_reset": "monthly", "usage": "0.42", "created_at": "2026-08-16T11:59:31.000Z", "updated_at": "2026-08-16T11:59:31.000Z" } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A management key was sent to a route it cannot use: `/keys` is served only to a management key, and a management key is refused everywhere else because it never spends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such key in the management key’s own workspace. Identical whether the hash is unknown or names a key elsewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateKey", "summary": "Edit a key", "description": "Every member is optional; at least one is required. `disabled: true` revokes the key exactly as `DELETE` does — the row stays and keeps its ledger attribution, it simply stops authenticating.", "tags": [ "keys" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "The key’s SHA-256 hex, as `POST /keys` or `GET /keys` reported it.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "example": "3fa85f64571745..." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyUpdateRequest" }, "example": { "limit": "25", "limit_reset": "weekly" } } } }, "responses": { "200": { "description": "The key as it now stands.", "content": { "application/json": { "example": { "data": { "hash": "3fa85f64571745...", "name": "customer instance", "label": "sk-hd-v1-3f9a…", "disabled": false, "limit": "25", "limit_reset": "weekly", "usage": "0.42", "created_at": "2026-08-16T11:59:31.000Z", "updated_at": "2026-08-16T12:10:04.000Z" } } } } }, "400": { "description": "The body did not parse, or carried no member to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A management key was sent to a route it cannot use: `/keys` is served only to a management key, and a management key is refused everywhere else because it never spends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such key in the management key’s own workspace. Identical whether the hash is unknown or names a key elsewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "revokeKey", "summary": "Revoke a key", "description": "Disables the key; the row stays and keeps its ledger attribution. Idempotent — revoking an already-revoked key answers the same way.", "tags": [ "keys" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "The key’s SHA-256 hex, as `POST /keys` or `GET /keys` reported it.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "example": "3fa85f64571745..." } } ], "responses": { "200": { "description": "The key is revoked.", "content": { "application/json": { "example": { "data": { "success": true } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A management key was sent to a route it cannot use: `/keys` is served only to a management key, and a management key is refused everywhere else because it never spends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such key in the management key’s own workspace. Identical whether the hash is unknown or names a key elsewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/files": { "post": { "operationId": "uploadFile", "summary": "Store a file", "description": "Stores one file on the account the key draws from, as `multipart/form-data` with the bytes in a `file` part. The file expires 48 hours after it is stored, and the response states the instant in `expires_at`. One file is capped at 32 MiB and an account at 512 MiB across every file it holds, counting only files that have not expired; the type must be one the store accepts (`application/json`, `application/pdf`, `image/gif`, `image/jpeg`, `image/png`, `image/webp`, `text/csv`, `text/markdown`, `text/plain`). A part sent as `application/octet-stream` is typed from its filename extension. The filename is kept as one path segment: separators, control characters and quotes are stripped from it.", "tags": [ "files" ], "requestBody": { "required": true, "description": "The file, in a part named `file`.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The bytes to store, with the filename and content type of the part." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "The file was stored.", "content": { "application/json": { "example": { "data": { "id": "file_2f1c4a7e9b0d46538a1c7e5f3b204d61", "filename": "handbook.pdf", "mime_type": "application/pdf", "size_bytes": 184320, "created_at": "2026-08-16T11:59:31.000Z", "expires_at": "2026-08-18T11:59:31.000Z", "downloadable": true } } } } }, "400": { "description": "The body was not multipart, carried no `file` part, carried an empty one, or named a type the store does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Storing the file would put the account past its file quota. `metadata` carries `quota_bytes`, `used_bytes` and `file_bytes`, so a client can say how much to free.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The file is larger than the 32 MiB one file may hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The key store that stored files are sealed under could not be reached. Retry shortly: this says nothing about the file, which is never reported absent because of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listFiles", "summary": "List files", "description": "Every unexpired file on the key’s own account, newest first. `next_cursor` is the id to pass as `after` for the page behind this one, and is `null` on the last page.", "tags": [ "files" ], "parameters": [ { "name": "limit", "in": "query", "description": "Files per page, 1 through 100. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "The id the previous page ended on. An id naming no file of this account is refused as unknown rather than answered as empty.", "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "One page of files.", "content": { "application/json": { "example": { "data": [ { "id": "file_2f1c4a7e9b0d46538a1c7e5f3b204d61", "filename": "handbook.pdf", "mime_type": "application/pdf", "size_bytes": 184320, "created_at": "2026-08-16T11:59:31.000Z", "expires_at": "2026-08-18T11:59:31.000Z", "downloadable": true } ], "next_cursor": null } } } }, "400": { "description": "`limit` is outside 1 through 100, or `after` names no file of this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/files/{id}": { "get": { "operationId": "getFile", "summary": "Read one file’s metadata", "description": "What the store holds about one file, without its content. `downloadable` reports that the bytes are held and will be served at `/files/{id}/content`, and `expires_at` is the instant the file stops existing. A file past that instant answers 404, as a deleted one does.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id `POST /files` returned, of the form `file_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "example": { "data": { "id": "file_2f1c4a7e9b0d46538a1c7e5f3b204d61", "filename": "handbook.pdf", "mime_type": "application/pdf", "size_bytes": 184320, "created_at": "2026-08-16T11:59:31.000Z", "expires_at": "2026-08-18T11:59:31.000Z", "downloadable": true } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such file on the key’s own account. Identical whether the id is unknown, malformed, expired, deleted, or names a file another account stored. A file whose sealing key the key store has lost, which only a loss of its data causes, answers the same way for its content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "deleteFile", "summary": "Delete a file", "description": "Removes the file and its content, and frees what it held against the account quota. Not idempotent: a second delete answers 404, because a file that is gone and a file that was never stored are the same answer.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id `POST /files` returned, of the form `file_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The file is gone.", "content": { "application/json": { "example": { "data": { "success": true } } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such file on the key’s own account. Identical whether the id is unknown, malformed, expired, deleted, or names a file another account stored. A file whose sealing key the key store has lost, which only a loss of its data causes, answers the same way for its content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/files/{id}/content": { "get": { "operationId": "downloadFileContent", "summary": "Download a file", "description": "The stored bytes, served whole under the type the file was stored as, with the filename in `Content-Disposition`. Ranges are not offered. The bytes are held sealed under a key that lives outside the database, so this reads them back only while that key exists, which is for longer than the file lives.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file id `POST /files` returned, of the form `file_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The file content.", "headers": { "Content-Disposition": { "description": "`attachment`, with the filename the file was stored under.", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such file on the key’s own account. Identical whether the id is unknown, malformed, expired, deleted, or names a file another account stored. A file whose sealing key the key store has lost, which only a loss of its data causes, answers the same way for its content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The key store that stored files are sealed under could not be reached. Retry shortly: this says nothing about the file, which is never reported absent because of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/batches": { "post": { "operationId": "createBatch", "summary": "Submit a batch", "description": "Submits requests to run in the background against one endpoint: `/v1/chat/completions`, `/v1/responses` or `/v1/messages`. Answers `202` with `status: \"validating\"` once the batch is stored; nothing has run or been charged yet. `requests` holds up to 1000 items of `{ custom_id, body }`, each `custom_id` unique within the batch and each `body` the request its endpoint takes, with `stream` left out because every request is answered in full. `model` and `provider` (`only`, `allow_fallbacks`), when stated, apply to every request that does not state its own; a body that names a different `model` fails on its own. Each body is parsed against the endpoint's schema when the batch is accepted, and one that does not parse fails alone, in the results, with the error the live route would have answered, while the rest of the batch runs. A batch whose every request fails that way ends `failed`. Every request is routed, held, settled and billed exactly as the same body posted to the endpoint would be, under the key that submitted the batch and its spend limit as it stands when the request is sent, and carries a generation of its own; a batch earns no discount. A request the account cannot fund, or no endpoint serves, fails alone with that answer. Requests run oldest batch first, at most 8 of an account's at a time by default. An account may have 10 batches waiting or running at once. A batch still running when its completion window closes ends `expired`. The outcome of each request is written as one line of a file in the account's file store when the batch ends, and the requests and replies the batch held are cleared in the same step. While the batch runs they are stored sealed, under a key that lives outside the database and is destroyed no more than 50 hours after the value was written. A request whose key is gone when its turn comes is not sent and is not charged; a charged request whose reply is gone when the batch ends fails with the charge named in `error.request_id`, and is not run again.", "tags": [ "batches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" }, "example": { "endpoint": "/v1/chat/completions", "model": "acme/alpha-v1", "completion_window": "24h", "requests": [ { "custom_id": "req-0001", "body": { "messages": [ { "role": "user", "content": "Summarize the first report." } ] } }, { "custom_id": "req-0002", "body": { "messages": [ { "role": "user", "content": "Summarize the second report." } ] } } ] } } } }, "responses": { "202": { "description": "The batch was stored. `status` is `validating` until the runner takes it, and nothing has run yet; `request_counts.failed` already counts any request whose body did not parse.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" }, "example": { "id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "object": "batch", "endpoint": "/v1/chat/completions", "model": "acme/alpha-v1", "completion_window": "24h", "status": "validating", "created_at": 1786881571, "expires_at": 1786967971, "finalized_at": null, "request_counts": { "total": 2, "completed": 0, "failed": 0 }, "results_file_id": null, "results": null, "error": null } } } }, "400": { "description": "The envelope did not parse: an `endpoint` the API does not batch, no `requests` or more than the batch holds, a `custom_id` missing or repeated, a `body` that is not an object, or a member the submission does not take. A `body` that does not parse against its endpoint is not this error; it fails alone, in the results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The request body is larger than this route accepts. The inline assets a request carries are bounded by their own decoded-byte budget, which is read only once a body has arrived; a body over the route’s size limit is refused here instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "The account already has 10 batches waiting or running, or the key is over its request rate. `metadata` carries `limit` and `active` for the first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The key store that requests are stored sealed under could not be reached. Nothing was stored: repeat the submission shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listBatches", "summary": "List batches", "description": "Batches on the key’s own account, newest first. `status` may be repeated to include several. `created_after` and `created_before` take unix seconds, a date or an ISO 8601 instant, and exclude the instant itself. To read the next page, pass the previous page’s `last_id` as `after`; there is no offset. Every item carries `results: null`, and `GET /batches/{id}` has the results.", "tags": [ "batches" ], "parameters": [ { "name": "limit", "in": "query", "description": "Batches per page, 1 through 100. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "The `last_id` of the previous page. An id naming no batch of this account is refused as unknown rather than answered as empty.", "schema": { "type": "string", "pattern": "^batch_[0-9a-f]{32}$" } }, { "name": "status", "in": "query", "description": "Only batches in this status. Repeat the parameter to include more than one.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "validating", "in_progress", "cancelling", "completed", "failed", "expired", "cancelled" ] } } }, { "name": "created_after", "in": "query", "description": "Only batches created strictly after this instant.", "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "Only batches created strictly before this instant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of batches, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchList" }, "example": { "object": "list", "data": [ { "id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "object": "batch", "endpoint": "/v1/chat/completions", "model": "acme/alpha-v1", "completion_window": "24h", "status": "validating", "created_at": 1786881571, "expires_at": 1786967971, "finalized_at": null, "request_counts": { "total": 2, "completed": 0, "failed": 0 }, "results_file_id": null, "results": null, "error": null } ], "first_id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "last_id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "has_more": false } } } }, "400": { "description": "`limit` is outside 1 through 100, `status` names no status, a time bound names no instant, or `after` names no batch of this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/batches/{id}": { "get": { "operationId": "getBatch", "summary": "Retrieve a batch", "description": "A batch with its status and request counts. `completed`, `failed`, `expired` and `cancelled` are terminal. A batch that has ended carries `results_file_id`, the file its results were written to, and `results`, the same lines inline in submission order, for as long as that file is held, which is 48 hours from the batch ending. After that both are null and the batch still reports how it ended and its counts. `request_counts.completed` and `.failed` are the requests that ended in each way; a request stopped or expired before it was sent is in neither, so `total` less the two is what the batch did not run. A failed batch states the reason in `error.message`. Each result has exactly one of `response` and `error`. `response.body` is what the endpoint answered, `response.request_id` is the id the request was billed under and `X-Generation-Id` carries on a live request, and `error` names the type and message of the answer the live route would have given.", "tags": [ "batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id `POST /batches` returned, of the form `batch_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^batch_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The batch as it stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" }, "example": { "id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "object": "batch", "endpoint": "/v1/chat/completions", "model": "acme/alpha-v1", "completion_window": "24h", "status": "completed", "created_at": 1786881571, "expires_at": 1786967971, "finalized_at": 1786881702, "request_counts": { "total": 2, "completed": 1, "failed": 1 }, "results_file_id": "file_2f1c4a7e9b0d46538a1c7e5f3b204d61", "results": [ { "id": "breq_7e0c1a94d3b84f2a9c56e81d0b3f2a47", "custom_id": "req-0001", "response": { "status_code": 200, "request_id": "gen-1786881609-aBcDeFgHiJkLmNoPqRsT", "body": { "id": "gen-1786881609-aBcDeFgHiJkLmNoPqRsT", "object": "chat.completion" } }, "error": null }, { "id": "breq_a3c4e5f6071829304a5b6c7d8e9f0a1b", "custom_id": "req-0002", "response": null, "error": { "type": "invalid_request", "message": "Invalid request: messages: Too small: expected array to have >=1 items", "param": null, "code": 400, "request_id": null } } ], "error": null } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such batch on the key’s own account. Identical whether the id is unknown, malformed, or names a batch another account submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/batches/{id}/cancel": { "post": { "operationId": "cancelBatch", "summary": "Cancel a batch", "description": "Stops a batch. Dispatch stops at once and the requests already in flight are cut; `status` is `cancelling` until what ran has settled, and the batch then becomes `cancelled`. A request that completed keeps its reply and its charge. A request that was cut, or had not been sent, is listed in the results as stopped and is not charged, except where it was charged before it was cut, in which case its error names the charge in `request_id`. Cancelling a batch that is already `cancelling` or `cancelled` answers its document unchanged. A batch that ended another way cannot be cancelled and answers 409.", "tags": [ "batches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The batch id `POST /batches` returned, of the form `batch_` followed by 32 hex characters.", "schema": { "type": "string", "pattern": "^batch_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "The batch, `cancelling` or already `cancelled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" }, "example": { "id": "batch_5d1f0c9e2a7b4e36b8a4c1d27e90f3a5", "object": "batch", "endpoint": "/v1/chat/completions", "model": "acme/alpha-v1", "completion_window": "24h", "status": "cancelling", "created_at": 1786881571, "expires_at": 1786967971, "finalized_at": null, "request_counts": { "total": 2, "completed": 0, "failed": 0 }, "results_file_id": null, "results": null, "error": null } } } }, "401": { "description": "The key is missing, unknown, revoked, expired or past its spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such batch on the key’s own account. Identical whether the id is unknown, malformed, or names a batch another account submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The batch already ended as `completed`, `failed` or `expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/deposits/x402": { "get": { "operationId": "getX402Terms", "summary": "The x402 rail terms", "description": "What the signed-authorization deposit rail accepts, or `{ \"enabled\": false }` and nothing else when it is not configured: an address or a network published by a rail that cannot take a payment describes an offer no client could tell from a payable one. No key required, so an agent can read the terms before holding one.", "tags": [ "deposits" ], "security": [], "responses": { "200": { "description": "The terms, or the flag on its own.", "content": { "application/json": { "example": { "enabled": true, "x402_version": 2, "scheme": "exact", "pay_to": "0x0000000000000000000000000000000000000000", "min_amount": "1", "max_amount": "1000", "max_timeout_seconds": 120, "networks": [ { "network": "eip155:8453", "chain_id": 8453, "chain_name": "Base", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "asset_symbol": "USDC", "asset_decimals": 6, "confirmations": 60, "confirmation_seconds": 120 } ] } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "settleX402Deposit", "summary": "Settle an x402 deposit", "description": "Without a `PAYMENT-SIGNATURE` header the answer is a 402 carrying the protocol's own `PaymentRequired` object, which is not the house error envelope every other 402 on this API is. Resubmitting with the base64 `PaymentPayload` in that header verifies and settles it. The credit posts at the chain's confirmation depth, not with the response. Which account a settled payment credits is decided by the payer's wallet binding where one exists, and by the presenting key otherwise; a key naming a different account than the binding is a 409 refused before anything settles. An authorization is identified by its chain, asset, payer and EIP-3009 nonce, so the same nonce can never settle twice and replaying one answers what was recorded for it.", "tags": [ "deposits" ], "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402DepositRequest" }, "example": { "amount": "25.00", "network": "eip155:8453" } } } }, "responses": { "200": { "description": "Settled, or recorded as settling where the outcome never came back. `PAYMENT-RESPONSE` carries the same `SettlementResponse` base64-encoded.", "content": { "application/json": { "example": { "data": { "id": "dep_01J8Z0X2QZ", "status": "settled", "network": "eip155:8453", "transaction": "0xabc…", "payer": "0xdef…", "amount": "25", "confirmations": 60, "confirmation_seconds": 120 } } } } }, "400": { "description": "The amount is not a decimal USD figure, falls outside the published bounds, or carries more decimal places than the asset does. The bounds are re-read on every submission rather than carried on the offer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "The protocol's `PaymentRequired` object, also carried base64-encoded in `PAYMENT-REQUIRED`. Accepted assets with a pinned EIP-712 domain include `extra.name` and `extra.version`; Base native USDC uses USD Coin / 2.", "content": { "application/json": { "example": { "x402Version": 2, "error": "Payment is required to credit this deposit.", "resource": { "url": "https://api-staging.heimdallm.com/api/v1/deposits/x402", "description": "Heimdallm account credit, 25 USD", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "25000000", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "payTo": "0x0000000000000000000000000000000000000000", "maxTimeoutSeconds": 120, "extra": { "name": "USD Coin", "version": "2" } } ], "extensions": {} } } } }, "409": { "description": "The rail is not configured, the key names an account the payer's wallet binding contradicts, or the authorization credits nobody.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/deposits/stripe": { "get": { "operationId": "getStripeTerms", "summary": "The card rail terms", "description": "The bounds a card deposit may fall between and the publishable key a browser is sent to Checkout with, or `{ \"enabled\": false }` and nothing else. Nothing here takes money: the Checkout Session is created on the browser session plane, where a signed-in account names who the credit lands on.", "tags": [ "deposits" ], "security": [], "responses": { "200": { "description": "The terms, or the flag on its own.", "content": { "application/json": { "example": { "enabled": true, "publishable_key": "pk_live_…", "min_amount": "5", "max_amount": "2000", "currency": "usd" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/deposits/stripe/webhook": { "post": { "operationId": "receiveStripeWebhook", "summary": "Card payment events", "description": "Where Stripe delivers what became of a Checkout Session. Listed because it is served on this plane, not because a customer calls it. The signature is the authentication, so no key and no cookie apply, and the body is read as the bytes that arrived rather than as a parsed object, because a re-serialized parse verifies only by luck. A 2xx tells Stripe to stop retrying, so it is answered only once the event is durably resolved.", "tags": [ "deposits" ], "security": [], "requestBody": { "required": true, "description": "The Stripe event, verbatim, at most 64 KiB, signed in the `Stripe-Signature` header.", "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The event was resolved and will not be delivered again.", "content": { "application/json": { "example": { "received": true } } } }, "400": { "description": "The signature does not verify against a secret the card rail holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The card rail is not configured here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests for the key, or for the address when no key was sent. `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "The marketplace failed to serve the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The card rail holds no webhook secret to verify a delivery against, so the event must be delivered again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key in `Authorization: Bearer sk-hd-v1-…`, minted on the account dashboard. Keys are shown once, at creation." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "The same API key as `bearerAuth`, sent as `x-api-key` — the header the Anthropic SDKs and the Claude Code CLI send when configured with `ANTHROPIC_API_KEY`. Presenting both headers with different values is refused." } }, "schemas": { "ModelSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "canonical_slug", "hugging_face_id", "name", "created", "expiration_date", "description", "context_length", "architecture", "license", "parameter_count", "weights_dtype", "pricing", "top_provider", "per_request_limits", "supported_parameters", "default_parameters", "family", "author", "tags", "endpoint_count", "links", "supported_voices", "supported_dimensions", "supported_languages" ], "properties": { "id": { "type": "string", "description": "The model id, `author/slug`." }, "canonical_slug": { "type": "string", "description": "Equal to `id`." }, "hugging_face_id": { "type": [ "string", "null" ], "description": "The Hugging Face repository id, or `null` when the model declares none." }, "name": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds the model was released, as declared by the provider." }, "expiration_date": { "type": [ "string", "null" ], "description": "The date after which the model may be removed, as `YYYY-MM-DD` in UTC, from the `deprecation_date` the provider document declares. `null` where no provider has declared one, which is a model with no announced end rather than one ending today." }, "description": { "type": [ "string", "null" ] }, "context_length": { "type": "integer", "minimum": 0, "description": "The model's own declared context window." }, "architecture": { "type": "object", "additionalProperties": false, "required": [ "modality", "input_modalities", "output_modalities", "tokenizer", "instruct_type" ], "properties": { "modality": { "type": "string", "description": "`input_modalities` joined by `+`, an arrow, then `output_modalities` joined by `+`." }, "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "video", "audio", "file" ] } }, "output_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "video", "speech", "transcription", "embeddings", "rerank", "decisions", "audio", "mesh" ] } }, "tokenizer": { "type": [ "string", "null" ], "description": "The tokenizer family the endpoint serving the model declares (`GPT`, `Claude`, `Llama3`), read from the same endpoint `pricing` and `top_provider` are. `null` where that endpoint declares none." }, "instruct_type": { "type": "null", "description": "Always `null`: no provider declaration and no column carries a prompt-template name." } } }, "license": { "type": [ "string", "null" ], "description": "The licence the weights are published under, spelled as the Hugging Face repository spells it: an SPDX id for most repositories (`apache-2.0`, `mit`), or the name a model card gives when it publishes under a licence of its own (`llama3.1`, `ltx-2.x-community-license-agreement`). `null` when neither the provider document nor the repository it names states one, which is unknown rather than unlicensed." }, "parameter_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The parameters the weights hold, summed over every tensor in the safetensors index. `null` when neither the provider document nor the repository it names states it, never `0`." }, "weights_dtype": { "type": [ "string", "null" ], "description": "The dtype most of the parameters are stored in, as safetensors names it: `BF16`, `F16`, `F32`, `F8_E4M3`, `I8`, `I32`. This is the storage width the index reports rather than the `quantization` an endpoint declares, so a build packing 4-bit values into `int32` containers reads `I32` here. `null` when neither the provider document nor the repository it names states it." }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "discount" ], "description": "The summary endpoint's prices as a request is charged them, decimal strings per unit and already net of the larger of the endpoint's discount and any active site promotion. A rate can carry more than 24 decimals where a discount multiplied a declaration's own precision; a charge is that rate times the units consumed, floored once at the ledger's 24 decimals. Every key names the unit it meters. A unit the endpoint declared no price for is absent from this object, never `0`. Native media scalar keys are present only for one unambiguous, unconditional output tariff; conditional and windowed native rates are omitted from the scalar projection. A price per audio input token is never published, because the marketplace holds no price in that unit.", "properties": { "prompt": { "type": "string", "description": "USD per input token." }, "completion": { "type": "string", "description": "USD per output token." }, "input_cache_read": { "type": "string", "description": "USD per prompt token read from cache." }, "input_cache_write": { "type": "string", "description": "USD per prompt token written to cache." }, "internal_reasoning": { "type": "string", "description": "USD per reasoning token, where the endpoint prices reasoning apart from completion." }, "request": { "type": "string", "description": "USD per request, charged flat." }, "image_megapixel": { "type": "string", "description": "USD per 1,000,000 pixels of delivered image output under a linear area tariff." }, "audio_second": { "type": "string", "description": "USD per second of audio, whether consumed on a transcription or generated in a reply." }, "character": { "type": "string", "description": "USD per character synthesized." }, "input_cache_write_1h": { "type": "string", "description": "USD per prompt token written to a cache that holds it for an hour, where the endpoint prices that lifetime apart from its default one. `input_cache_write` is the price of a write carrying no lifetime." }, "image": { "type": "string", "description": "USD per image supplied in the prompt, charged per image rather than per pixel." }, "audio_output": { "type": "string", "description": "USD per audio token generated in a reply." }, "image_output": { "type": "string", "description": "USD per delivered output image." }, "image_output_token": { "type": "string", "description": "USD per output image token. Heimdallm extension." }, "video_second": { "type": "string", "description": "USD per second of delivered video output, including fractional seconds. Heimdallm extension." }, "mesh_output": { "type": "string", "description": "USD per delivered mesh, charged whole. The face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. Heimdallm extension." }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "Conditional prices. All conditions in an entry must match; later matching entries win per price key. Windowed rates follow default-rate overrides, with declaration order preserved within each group. Present only where at least one condition can be represented." }, "discount": { "type": "number", "description": "Heimdallm extension: the effective fraction taken off the list price to reach the prices above, including any active site promotion. A list price is `price / (1 - discount)`. Always present: `0` where nothing is taken off, and negative where the endpoint charges above its list." } } }, "top_provider": { "type": "object", "additionalProperties": false, "required": [ "context_length", "max_completion_tokens", "is_moderated" ], "properties": { "context_length": { "type": "integer", "minimum": 0, "description": "The summary endpoint's declared context window." }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The output ceiling the summary endpoint declares, or `null` when it declares none." }, "is_moderated": { "type": "boolean" } } }, "per_request_limits": { "type": "null" }, "supported_parameters": { "type": "array", "items": { "type": "string" }, "description": "The union of parameters every live endpoint on the model declares." }, "parameter_offers": { "type": "array", "description": "Distinct typed parameter domains declared by live sellers, grouped by output modality. Each offer is one endpoint declaration; use the endpoint listing for provider identity and exact routing constraints.", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "reasoning": { "type": "object", "additionalProperties": false, "properties": { "supported_efforts": { "type": "array", "items": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ] }, "description": "The explicitly declared effort domain, strongest first. Absent when the domain is unknown; never null or an inferred promise of all API values. Capability refutations are published separately as `refuted_reasoning_efforts` on the endpoint." }, "mandatory": { "type": "boolean", "description": "Present as `false` when the endpoint declares `none` or a boolean reasoning switch. Otherwise omitted: the absence of a disable declaration does not prove mandatory thinking." }, "default_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The valid declared effort default for a request that omits effort. The value `none` means reasoning is off by default. Absent when no valid default is declared." }, "default_enabled": { "type": "boolean", "description": "The declared boolean thinking default, or whether an effort default differs from `none` when no independent thinking switch is declared. Absent when defaults are missing or conflicting; a switch without a default does not inherit the effort default." }, "supports_max_tokens": { "type": "boolean", "description": "Present and `true` only for a declared integer or range reasoning token budget. This describes the endpoint declaration; forwarding the control depends on the adapter." } } }, "video_generation": { "type": "object", "additionalProperties": false, "properties": { "generate_audio": { "type": "object", "additionalProperties": false, "properties": { "supported_values": { "type": "array", "items": { "type": "boolean" }, "description": "Explicitly declared soundtrack choices. Absent when the accepted domain is unknown." }, "default": { "type": "boolean", "description": "The declared soundtrack default. Absent when missing or conflicting; there is no universal API default." } } } } }, "default_parameters": { "type": "object", "additionalProperties": false, "description": "The sampling the model's author recommends, as the provider declares it or as the repository `hugging_face_id` names states it in `generation_config.json`. Advice a caller may adopt, not anything an endpoint enforces: a request carrying its own value is served with that value, and a request carrying none is served with whatever the engine behind it runs. A member nobody stated is absent, never `0` and never the neutral setting, since 0 is a real temperature and 1.0 a real repetition penalty. The object is always present and is `{}` on a model nothing is known about.", "properties": { "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "The recommended sampling temperature." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "The recommended nucleus sampling mass, in (0, 1]." }, "top_k": { "type": "integer", "minimum": 0, "description": "The recommended number of likeliest tokens to sample from." }, "repetition_penalty": { "type": "number", "exclusiveMinimum": 0, "maximum": 2, "description": "The recommended multiplicative repetition penalty, in (0, 2]." } } }, "hugging_face": { "type": "object", "additionalProperties": false, "required": [ "id", "read_at" ], "description": "What the Hugging Face repository `hugging_face_id` names states about the weights, and the moment that statement was read. Present only where a reading of the repository exists: a model naming no repository, and one whose repository has not been read, carry no such member at all, so the member is itself the statement that a reading was taken and `read_at` dates it. Within the member, a fact the repository states no value for is absent — never `null` and never an empty array — which is what separates a card stating none from a card nobody has read.", "properties": { "id": { "type": "string", "description": "The repository the reading was taken of, spelled as the Hub spells it. A declared `hugging_face_id` differing from this only by case resolves to the same repository." }, "read_at": { "type": "integer", "minimum": 0, "description": "Unix seconds the repository was read. Every other member of this object is what the repository stated at that moment, not what it states today." }, "availability": { "type": "string", "enum": [ "public", "gated", "unavailable" ], "description": "What the Hub shows an anonymous reader. `public` answers and serves its files, `gated` answers while its files need the licence accepted, and `unavailable` is a repository the Hub does not show at all: private, deleted, or an id that resolves to nothing." }, "languages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The languages the model card states the weights serve, as it spells them and in its own order. Absent where the card states none, which most cards do and which says nothing about the languages the weights handle." }, "papers": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The arXiv ids the listing credits, as bare ids (`2606.19348`). Absent where it credits none." }, "datasets": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The Hub dataset repositories the listing credits, as `owner/name`. Absent where it credits none." }, "weights_revision": { "type": "string", "description": "The commit the repository resolved to when it was read: the weights a reader fetching it received. Absent where the listing states none, which is never evidence that the repository holds one revision." }, "weights_updated_at": { "type": "integer", "minimum": 0, "description": "Unix seconds that commit was published. Absent where the listing states none, which is never evidence that the repository has not changed." }, "downloads": { "type": "integer", "minimum": 0, "description": "How many times the Hub reports the repository fetched, as of the reading. Absent where the listing states none." }, "likes": { "type": "integer", "minimum": 0, "description": "How many times the Hub reports the repository starred, as of the reading. Absent where the listing states none." }, "evaluations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "metrics" ], "properties": { "task": { "type": "string", "description": "The task the card's `model-index` names for this result. Absent where it names none." }, "dataset": { "type": "string", "description": "The dataset the card's `model-index` names for this result. Absent where it names none." }, "metrics": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "number" } } }, "minItems": 1 } } }, "minItems": 1, "description": "The evaluation results the card's `model-index` states, in the order it lists them. Absent where the card publishes none." } } }, "family": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "author": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "endpoint_count": { "type": "integer", "minimum": 1, "description": "The number of live endpoints serving the model." }, "links": { "type": "object", "additionalProperties": false, "required": [ "details" ], "properties": { "details": { "type": "string" } } }, "speech": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "voices", "formats" ], "properties": { "voices": { "type": "array", "items": { "type": "string" }, "description": "The voice identifiers it answers to, as the provider spells them. A voice named `default` is the one it falls back to." }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ] }, "description": "The codecs it encodes into." }, "min_speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "max_speed": { "type": "number", "minimum": 0.25, "maximum": 4 } } }, { "type": "null" } ], "description": "What the model speaks, as the union across its live endpoints: every voice and codec any of them declares, and the widest speed range any of them honours. A union is a discovery aid rather than a promise — one endpoint speaks each of these voices and no endpoint speaks all of them, so what a single endpoint speaks is read from `speech_envelope` on the endpoints listing `links.details` names. Present only on a model whose output modality includes `speech`, and `null` there when no endpoint has declared an envelope." }, "supported_voices": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The same voices `speech.voices` carries, flat. Always present: `null` says the model synthesizes no speech, and `null` on a model that does says no live endpoint of it has declared an envelope." }, "supported_dimensions": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "The truncated vector widths a `dimensions` request on this model may name, read off its cheapest embeddings endpoint. Always present: `null` says the model produces no embeddings, and `null` on a model that does says its cheapest endpoint declares no width." }, "supported_languages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The languages a `language` request on this model may name, read off its cheapest transcription or speech endpoint. Always present: `null` says the model transcribes or speaks nothing, and `null` on a model that does says its cheapest endpoint declares no list." } } }, "SdkModel": { "type": "object", "additionalProperties": false, "required": [ "id", "canonical_slug", "hugging_face_id", "name", "created", "expiration_date", "description", "context_length", "architecture", "license", "parameter_count", "weights_dtype", "pricing", "top_provider", "per_request_limits", "supported_parameters", "default_parameters", "family", "author", "tags", "endpoint_count", "links", "supported_voices", "supported_dimensions", "supported_languages", "object", "owned_by" ], "properties": { "id": { "type": "string", "description": "The model id, `author/slug`." }, "canonical_slug": { "type": "string", "description": "Equal to `id`." }, "hugging_face_id": { "type": [ "string", "null" ], "description": "The Hugging Face repository id, or `null` when the model declares none." }, "name": { "type": "string" }, "created": { "type": "integer", "description": "Unix seconds the model was released, as declared by the provider." }, "expiration_date": { "type": [ "string", "null" ], "description": "The date after which the model may be removed, as `YYYY-MM-DD` in UTC, from the `deprecation_date` the provider document declares. `null` where no provider has declared one, which is a model with no announced end rather than one ending today." }, "description": { "type": [ "string", "null" ] }, "context_length": { "type": "integer", "minimum": 0, "description": "The model's own declared context window." }, "architecture": { "type": "object", "additionalProperties": false, "required": [ "modality", "input_modalities", "output_modalities", "tokenizer", "instruct_type" ], "properties": { "modality": { "type": "string", "description": "`input_modalities` joined by `+`, an arrow, then `output_modalities` joined by `+`." }, "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "video", "audio", "file" ] } }, "output_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "video", "speech", "transcription", "embeddings", "rerank", "decisions", "audio", "mesh" ] } }, "tokenizer": { "type": [ "string", "null" ], "description": "The tokenizer family the endpoint serving the model declares (`GPT`, `Claude`, `Llama3`), read from the same endpoint `pricing` and `top_provider` are. `null` where that endpoint declares none." }, "instruct_type": { "type": "null", "description": "Always `null`: no provider declaration and no column carries a prompt-template name." } } }, "license": { "type": [ "string", "null" ], "description": "The licence the weights are published under, spelled as the Hugging Face repository spells it: an SPDX id for most repositories (`apache-2.0`, `mit`), or the name a model card gives when it publishes under a licence of its own (`llama3.1`, `ltx-2.x-community-license-agreement`). `null` when neither the provider document nor the repository it names states one, which is unknown rather than unlicensed." }, "parameter_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The parameters the weights hold, summed over every tensor in the safetensors index. `null` when neither the provider document nor the repository it names states it, never `0`." }, "weights_dtype": { "type": [ "string", "null" ], "description": "The dtype most of the parameters are stored in, as safetensors names it: `BF16`, `F16`, `F32`, `F8_E4M3`, `I8`, `I32`. This is the storage width the index reports rather than the `quantization` an endpoint declares, so a build packing 4-bit values into `int32` containers reads `I32` here. `null` when neither the provider document nor the repository it names states it." }, "pricing": { "type": "object", "additionalProperties": false, "required": [ "discount" ], "description": "The summary endpoint's prices as a request is charged them, decimal strings per unit and already net of the larger of the endpoint's discount and any active site promotion. A rate can carry more than 24 decimals where a discount multiplied a declaration's own precision; a charge is that rate times the units consumed, floored once at the ledger's 24 decimals. Every key names the unit it meters. A unit the endpoint declared no price for is absent from this object, never `0`. Native media scalar keys are present only for one unambiguous, unconditional output tariff; conditional and windowed native rates are omitted from the scalar projection. A price per audio input token is never published, because the marketplace holds no price in that unit.", "properties": { "prompt": { "type": "string", "description": "USD per input token." }, "completion": { "type": "string", "description": "USD per output token." }, "input_cache_read": { "type": "string", "description": "USD per prompt token read from cache." }, "input_cache_write": { "type": "string", "description": "USD per prompt token written to cache." }, "internal_reasoning": { "type": "string", "description": "USD per reasoning token, where the endpoint prices reasoning apart from completion." }, "request": { "type": "string", "description": "USD per request, charged flat." }, "image_megapixel": { "type": "string", "description": "USD per 1,000,000 pixels of delivered image output under a linear area tariff." }, "audio_second": { "type": "string", "description": "USD per second of audio, whether consumed on a transcription or generated in a reply." }, "character": { "type": "string", "description": "USD per character synthesized." }, "input_cache_write_1h": { "type": "string", "description": "USD per prompt token written to a cache that holds it for an hour, where the endpoint prices that lifetime apart from its default one. `input_cache_write` is the price of a write carrying no lifetime." }, "image": { "type": "string", "description": "USD per image supplied in the prompt, charged per image rather than per pixel." }, "audio_output": { "type": "string", "description": "USD per audio token generated in a reply." }, "image_output": { "type": "string", "description": "USD per delivered output image." }, "image_output_token": { "type": "string", "description": "USD per output image token. Heimdallm extension." }, "video_second": { "type": "string", "description": "USD per second of delivered video output, including fractional seconds. Heimdallm extension." }, "mesh_output": { "type": "string", "description": "USD per delivered mesh, charged whole. The face count is geometry the request chose and not a quantity anybody is charged for, because generation cost does not scale with it. Heimdallm extension." }, "overrides": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" }, "properties": { "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window opens, inclusive." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "The HHMM UTC clock time the window closes, exclusive. Below `utc_start` it wraps midnight." }, "utc_days": { "type": "array", "items": { "type": "string" }, "description": "The lowercase UTC day names the window covers; absent, it covers every day." }, "min_prompt_tokens": { "type": "integer", "description": "The price applies where the prompt is strictly longer than this, in tokens." } } }, "description": "Conditional prices. All conditions in an entry must match; later matching entries win per price key. Windowed rates follow default-rate overrides, with declaration order preserved within each group. Present only where at least one condition can be represented." }, "discount": { "type": "number", "description": "Heimdallm extension: the effective fraction taken off the list price to reach the prices above, including any active site promotion. A list price is `price / (1 - discount)`. Always present: `0` where nothing is taken off, and negative where the endpoint charges above its list." } } }, "top_provider": { "type": "object", "additionalProperties": false, "required": [ "context_length", "max_completion_tokens", "is_moderated" ], "properties": { "context_length": { "type": "integer", "minimum": 0, "description": "The summary endpoint's declared context window." }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "The output ceiling the summary endpoint declares, or `null` when it declares none." }, "is_moderated": { "type": "boolean" } } }, "per_request_limits": { "type": "null" }, "supported_parameters": { "type": "array", "items": { "type": "string" }, "description": "The union of parameters every live endpoint on the model declares." }, "parameter_offers": { "type": "array", "description": "Distinct typed parameter domains declared by live sellers, grouped by output modality. Each offer is one endpoint declaration; use the endpoint listing for provider identity and exact routing constraints.", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "reasoning": { "type": "object", "additionalProperties": false, "properties": { "supported_efforts": { "type": "array", "items": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ] }, "description": "The explicitly declared effort domain, strongest first. Absent when the domain is unknown; never null or an inferred promise of all API values. Capability refutations are published separately as `refuted_reasoning_efforts` on the endpoint." }, "mandatory": { "type": "boolean", "description": "Present as `false` when the endpoint declares `none` or a boolean reasoning switch. Otherwise omitted: the absence of a disable declaration does not prove mandatory thinking." }, "default_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The valid declared effort default for a request that omits effort. The value `none` means reasoning is off by default. Absent when no valid default is declared." }, "default_enabled": { "type": "boolean", "description": "The declared boolean thinking default, or whether an effort default differs from `none` when no independent thinking switch is declared. Absent when defaults are missing or conflicting; a switch without a default does not inherit the effort default." }, "supports_max_tokens": { "type": "boolean", "description": "Present and `true` only for a declared integer or range reasoning token budget. This describes the endpoint declaration; forwarding the control depends on the adapter." } } }, "video_generation": { "type": "object", "additionalProperties": false, "properties": { "generate_audio": { "type": "object", "additionalProperties": false, "properties": { "supported_values": { "type": "array", "items": { "type": "boolean" }, "description": "Explicitly declared soundtrack choices. Absent when the accepted domain is unknown." }, "default": { "type": "boolean", "description": "The declared soundtrack default. Absent when missing or conflicting; there is no universal API default." } } } } }, "default_parameters": { "type": "object", "additionalProperties": false, "description": "The sampling the model's author recommends, as the provider declares it or as the repository `hugging_face_id` names states it in `generation_config.json`. Advice a caller may adopt, not anything an endpoint enforces: a request carrying its own value is served with that value, and a request carrying none is served with whatever the engine behind it runs. A member nobody stated is absent, never `0` and never the neutral setting, since 0 is a real temperature and 1.0 a real repetition penalty. The object is always present and is `{}` on a model nothing is known about.", "properties": { "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "The recommended sampling temperature." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "The recommended nucleus sampling mass, in (0, 1]." }, "top_k": { "type": "integer", "minimum": 0, "description": "The recommended number of likeliest tokens to sample from." }, "repetition_penalty": { "type": "number", "exclusiveMinimum": 0, "maximum": 2, "description": "The recommended multiplicative repetition penalty, in (0, 2]." } } }, "hugging_face": { "type": "object", "additionalProperties": false, "required": [ "id", "read_at" ], "description": "What the Hugging Face repository `hugging_face_id` names states about the weights, and the moment that statement was read. Present only where a reading of the repository exists: a model naming no repository, and one whose repository has not been read, carry no such member at all, so the member is itself the statement that a reading was taken and `read_at` dates it. Within the member, a fact the repository states no value for is absent — never `null` and never an empty array — which is what separates a card stating none from a card nobody has read.", "properties": { "id": { "type": "string", "description": "The repository the reading was taken of, spelled as the Hub spells it. A declared `hugging_face_id` differing from this only by case resolves to the same repository." }, "read_at": { "type": "integer", "minimum": 0, "description": "Unix seconds the repository was read. Every other member of this object is what the repository stated at that moment, not what it states today." }, "availability": { "type": "string", "enum": [ "public", "gated", "unavailable" ], "description": "What the Hub shows an anonymous reader. `public` answers and serves its files, `gated` answers while its files need the licence accepted, and `unavailable` is a repository the Hub does not show at all: private, deleted, or an id that resolves to nothing." }, "languages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The languages the model card states the weights serve, as it spells them and in its own order. Absent where the card states none, which most cards do and which says nothing about the languages the weights handle." }, "papers": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The arXiv ids the listing credits, as bare ids (`2606.19348`). Absent where it credits none." }, "datasets": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The Hub dataset repositories the listing credits, as `owner/name`. Absent where it credits none." }, "weights_revision": { "type": "string", "description": "The commit the repository resolved to when it was read: the weights a reader fetching it received. Absent where the listing states none, which is never evidence that the repository holds one revision." }, "weights_updated_at": { "type": "integer", "minimum": 0, "description": "Unix seconds that commit was published. Absent where the listing states none, which is never evidence that the repository has not changed." }, "downloads": { "type": "integer", "minimum": 0, "description": "How many times the Hub reports the repository fetched, as of the reading. Absent where the listing states none." }, "likes": { "type": "integer", "minimum": 0, "description": "How many times the Hub reports the repository starred, as of the reading. Absent where the listing states none." }, "evaluations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "metrics" ], "properties": { "task": { "type": "string", "description": "The task the card's `model-index` names for this result. Absent where it names none." }, "dataset": { "type": "string", "description": "The dataset the card's `model-index` names for this result. Absent where it names none." }, "metrics": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "number" } } }, "minItems": 1 } } }, "minItems": 1, "description": "The evaluation results the card's `model-index` states, in the order it lists them. Absent where the card publishes none." } } }, "family": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "author": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "endpoint_count": { "type": "integer", "minimum": 1, "description": "The number of live endpoints serving the model." }, "links": { "type": "object", "additionalProperties": false, "required": [ "details" ], "properties": { "details": { "type": "string" } } }, "speech": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "voices", "formats" ], "properties": { "voices": { "type": "array", "items": { "type": "string" }, "description": "The voice identifiers it answers to, as the provider spells them. A voice named `default` is the one it falls back to." }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ] }, "description": "The codecs it encodes into." }, "min_speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "max_speed": { "type": "number", "minimum": 0.25, "maximum": 4 } } }, { "type": "null" } ], "description": "What the model speaks, as the union across its live endpoints: every voice and codec any of them declares, and the widest speed range any of them honours. A union is a discovery aid rather than a promise — one endpoint speaks each of these voices and no endpoint speaks all of them, so what a single endpoint speaks is read from `speech_envelope` on the endpoints listing `links.details` names. Present only on a model whose output modality includes `speech`, and `null` there when no endpoint has declared an envelope." }, "supported_voices": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The same voices `speech.voices` carries, flat. Always present: `null` says the model synthesizes no speech, and `null` on a model that does says no live endpoint of it has declared an envelope." }, "supported_dimensions": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "The truncated vector widths a `dimensions` request on this model may name, read off its cheapest embeddings endpoint. Always present: `null` says the model produces no embeddings, and `null` on a model that does says its cheapest endpoint declares no width." }, "supported_languages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The languages a `language` request on this model may name, read off its cheapest transcription or speech endpoint. Always present: `null` says the model transcribes or speaks nothing, and `null` on a model that does says its cheapest endpoint declares no list." }, "object": { "type": "string", "enum": [ "model" ], "description": "Always `\"model\"`." }, "owned_by": { "type": "string", "description": "Equal to `author`, the model's weights creator." } } }, "ErrorEnvelope": { "type": "object", "description": "Every failure on this API. `error.code` equals the HTTP status. Once a streaming response has started the status can no longer change, so the error arrives instead as a final SSE chunk with an `error` member, followed by `data: [DONE]`.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "The HTTP status, repeated." }, "message": { "type": "string", "description": "What went wrong, in plain words." }, "metadata": { "type": "object", "description": "`error_type` carries the stable classification; other members depend on the failure, such as `parameter` on a rejected field or `family_variants` on a model redirect." } } } }, "example": { "error": { "code": 402, "message": "Insufficient credits.", "metadata": { "error_type": "payment_required" } } } }, "ResponsesErrorEnvelope": { "type": "object", "description": "The Responses dialect's error body, which a request with `stream: true` refused before its stream opened answers with. `code` is null, as on the OpenAI wire; `type` is the OpenAI class of the status, and `metadata` is the one `ErrorEnvelope` carries, including the engine's own `provider_message` where one came back.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "description": "The OpenAI error class for the status, such as `invalid_request_error`." }, "code": { "type": "null" }, "metadata": { "type": "object", "description": "As on `ErrorEnvelope`." } } } }, "example": { "error": { "message": "The provider rejected the request", "type": "invalid_request_error", "code": null, "metadata": { "error_type": "provider_error", "provider_message": "reasoning_effort must be low or high" } } } }, "ResponsesStreamErrorEvent": { "type": "object", "description": "The `data` of the `error` event a committed Responses stream sends when it fails. `response.failed` follows it.", "required": [ "type", "code", "message", "param" ], "properties": { "type": { "type": "string", "enum": [ "error" ] }, "code": { "type": "null" }, "message": { "type": "string", "description": "What went wrong, followed by the engine's own diagnostic where one came back." }, "param": { "type": "null" } } }, "ResponsesFailedEvent": { "type": "object", "description": "The `data` of the `response.failed` event that ends a committed Responses stream which failed.", "required": [ "type", "sequence_number", "response" ], "properties": { "type": { "type": "string", "enum": [ "response.failed" ] }, "sequence_number": { "type": "integer", "minimum": 0, "description": "One past the last event before it." }, "response": { "type": "object", "required": [ "id", "object", "status", "model", "error" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "status": { "type": "string", "enum": [ "failed" ] }, "model": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "enum": [ "invalid_prompt", "rate_limit_exceeded", "context_length_exceeded", "server_error" ], "description": "`invalid_prompt` for a rejected request, `server_error` for a failure worth retrying." }, "message": { "type": "string" } } } } } } }, "AnthropicErrorEnvelope": { "type": "object", "description": "The Anthropic dialect's error body: what a request with `stream: true` refused before its stream opened answers with, and the `data` of the `error` event a committed stream ends on. `metadata` is the one `ErrorEnvelope` carries.", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "description": "The Anthropic error class for the status, such as `invalid_request_error`." }, "message": { "type": "string" }, "metadata": { "type": "object", "description": "As on `ErrorEnvelope`." } } } }, "example": { "type": "error", "error": { "type": "invalid_request_error", "message": "The provider rejected the request", "metadata": { "error_type": "provider_error" } } } }, "ManagementKeyCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A label for the key, up to 80 characters. Refused when it has the shape of a playground grant name." }, "limit": { "type": [ "string", "null" ], "description": "A spend ceiling as a decimal USD string, or omitted/null for none. A decimal USD-per-million-token string such as \"1.50\", compared exactly against the endpoint's declared per-token price. Never a float." }, "limit_reset": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ], "description": "How the ceiling resets, or omitted/null for a lifetime ceiling." } }, "example": { "name": "customer instance", "limit": "10", "limit_reset": "monthly" } }, "ManagementKeyUpdateRequest": { "type": "object", "additionalProperties": false, "required": [], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Renames the key." }, "limit": { "type": [ "string", "null" ], "description": "Replaces the spend ceiling; null removes it." }, "limit_reset": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ], "description": "Replaces the reset window; null makes the ceiling a lifetime one." }, "disabled": { "type": "boolean", "description": "True revokes the key exactly as `DELETE` does. False on an already-live key changes nothing." } }, "example": { "limit": "25", "limit_reset": "weekly" } }, "ChatCompletionRequest": { "type": "object", "additionalProperties": true, "required": [ "messages" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallback list, at most 20. The first id that can be routed serves the request." }, "messages": { "type": "array", "description": "The conversation, at least one message. A `user` message's content is a string or an array of `text`, `image_url`, `video_url`, `audio_url`, `input_audio` and `file` parts; a `*_url` part carries either a URL the endpoint fetches or a `data:` URL carrying the bytes. Each part is routed only to endpoints declaring an input for the modality it needs, in the source and format it carries, and an `input_audio` part reaches an endpoint that takes audio as `audio_url` rewritten as a data URL. A `file` part carries its document inline as `file_data`, or names one stored with `/files` as `file_id`, never both: the marketplace reads the stored bytes into the request before routing, so an endpoint is sent a data URL it declared it accepts and never an id, and a stored image reaches the model as an `image_url` part. A request may name at most 16 stored files, 32 MiB in all. An `assistant` message may carry a previous reply's `reasoning_details`, sent back exactly as received, so a provider that binds it to a signature or holds it encrypted can verify or replay the same sequence." }, "stream": { "type": "boolean", "description": "Answer with SSE chunks instead of one object." }, "store": { "type": "boolean", "description": "false is a storage opt-out: vetted ZDR endpoints satisfy it without a provider parameter. true is unsupported because chat completions are not stored and is rejected with 400." }, "enable_thinking": { "type": "boolean", "description": "Enable or disable thinking where the endpoint declares this control. Dynamo endpoints receive it as chat_template_kwargs.enable_thinking only when that nested boolean is declared." }, "stream_options": { "type": "object", "description": "The final usage chunk does not depend on include_usage. Set include_tool_dispatch: true with stream: true and tools to receive named tool_call_dispatch events from qualified endpoints. This option is consumed by the marketplace and omitted upstream.", "properties": { "include_usage": { "type": "boolean" }, "include_tool_dispatch": { "type": "boolean" } } }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Nucleus sampling mass in (0, 1]. Zero is rejected with 400, not replaced with a default." }, "top_k": { "type": "integer", "minimum": -1, "description": "Sample from the k likeliest tokens; -1 disables the filter where an endpoint declares it." }, "min_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Floor on a token's probability relative to the likeliest one; forwarded when the endpoint declares min_p." }, "top_a": { "type": "number", "minimum": 0, "maximum": 1, "description": "Accepted for compatibility; omitted from the upstream chat body." }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "Penalise repetition by count." }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "Penalise tokens already present." }, "repetition_penalty": { "type": "number", "exclusiveMinimum": 0, "maximum": 2, "description": "Multiplicative repetition penalty in (0, 2]; forwarded when the endpoint declares repetition_penalty." }, "seed": { "type": "integer", "description": "Ask for a reproducible sample where the engine offers one." }, "stop": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "Up to eight sequences that end the generation." }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576, "description": "Ceiling on generated tokens." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576, "description": "The OpenAI spelling of the same ceiling." }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "Per-token bias in [-100, 100], keyed by token id." }, "logprobs": { "type": "boolean", "description": "Return log probabilities." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "How many alternatives per position." }, "response_format": { "type": "object", "description": "`{ \"type\": \"text\" }`, `{ \"type\": \"json_object\" }` or `{ \"type\": \"json_schema\", \"json_schema\": { … } }`." }, "structured_outputs": { "type": "boolean", "description": "Routing marker: send it to be routed only to endpoints whose schema adherence has been verified." }, "tools": { "type": "array", "maxItems": 1536, "description": "Up to 1536 function tools the model may call. Names must match [a-zA-Z0-9_-]{1,128}." }, "tool_choice": { "type": [ "string", "object" ], "description": "`none`, `auto`, `required`, or one named function." }, "parallel_tool_calls": { "type": "boolean", "description": "Allow more than one call per turn." }, "reasoning": { "type": "object", "description": "`effort` is translated to reasoning_effort when declared by an OpenAI-compatible endpoint; the shorthand takes precedence. `max_tokens` supplies the Anthropic thinking budget. The object itself is never forwarded." }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "The shorthand for `reasoning.effort`. A level an endpoint has been shown to refuse is filtered out of routing on its own, and the rest of the declaration stands." }, "include_reasoning": { "type": "boolean", "description": "Put reasoning on the reply where the model emits it." }, "verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How much answer to produce." }, "n": { "type": "integer", "minimum": 1, "maximum": 1, "description": "One choice per request." }, "user": { "type": "string", "description": "An opaque end-user identifier, at most 256 characters." }, "session_id": { "type": "string", "maxLength": 256, "description": "The conversation this turn belongs to, keying session affinity. Outranks `prompt_cache_key` and the `X-Session-Id` header. The resolved id is forwarded to the serving endpoint as `x-session-id`." }, "prompt_cache_key": { "type": "string", "maxLength": 256, "description": "A cache affinity hint used when `session_id` is absent. Outranks the `X-Session-Id` header and is carried to the serving endpoint as `x-session-id`, rather than as a body parameter." }, "metadata": { "type": "object", "description": "Opaque members echoed on the generation record." }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] }, "description": "What the reply may carry. Naming `image` or `audio` asks for generated media in `message.images` or `message.audio`; absent takes the endpoint's own default, which for a text model is prose." }, "image_config": { "type": "object", "description": "How a generated image is drawn: `n`, `resolution`, `aspect_ratio`, `size`, `quality`, `output_format`, `background`, `output_compression` and `seed` — the drawing members of the image contract. A chat turn resolves `resolution` and `aspect_ratio` against the endpoint that serves it, exactly as `POST /images` does." }, "audio": { "type": "object", "required": [ "voice", "format" ], "description": "The voice and container for generated speech, as `{ \"voice\": \"alloy\", \"format\": \"wav\" }`. Both members are required: an engine asked for audio has to be told what to speak with and what to encode to, and the marketplace picks neither for you." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." }, "route": { "type": "string", "enum": [ "fallback", "sort" ], "deprecated": true, "description": "Alias for sort.partition: fallback groups by model; sort orders across models. An explicit provider.sort.partition wins, followed by this alias, then the workspace partition. Other values receive HTTP 400 naming route." }, "transforms": { "type": "array", "items": { "type": "string", "enum": [ "middle-out" ] }, "description": "Prompt transforms. `[\"middle-out\"]` asks for middle-out compression against the chosen endpoint's context window, applied after routing has picked that endpoint. The system message, the earliest user turn and the latest turns are kept, messages are dropped from the middle, and a tool call is never separated from its result. `usage` reports what was actually sent. `[]` declines compression, and so does an absent member. Any other element receives HTTP 400 naming the element and its value." }, "plugins": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Which plugin to apply. `context-compression` is the only served id." } }, "additionalProperties": true }, "description": "The same ask as `transforms`, written as a plugin. `[{ \"id\": \"context-compression\" }]` asks for middle-out compression, and an entry may carry configuration beside its `id`, which is accepted and not read. `context-compression` is the only served id, and any other, `web` included, receives HTTP 400 naming the id." }, "usage": { "type": "object", "description": "Usage accounting. `{ \"include\": true }` puts `usage` on the reply, cost included." } } }, "AnthropicMessagesRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "messages", "max_tokens" ], "properties": { "models": { "type": "array", "items": { "type": "string" }, "description": "Fallback list, at most 20. The first id that can be routed serves the request." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." }, "route": { "type": "string", "enum": [ "fallback", "sort" ], "deprecated": true, "description": "Alias for sort.partition: fallback groups by model; sort orders across models. An explicit provider.sort.partition wins, followed by this alias, then the workspace partition. Other values receive HTTP 400 naming route." }, "transforms": { "type": "array", "items": { "type": "string", "enum": [ "middle-out" ] }, "description": "Prompt transforms. `[\"middle-out\"]` asks for middle-out compression against the chosen endpoint's context window, applied after routing has picked that endpoint. The system message, the earliest user turn and the latest turns are kept, messages are dropped from the middle, and a tool call is never separated from its result. `usage` reports what was actually sent. `[]` declines compression, and so does an absent member. Any other element receives HTTP 400 naming the element and its value." }, "plugins": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Which plugin to apply. `context-compression` is the only served id." } }, "additionalProperties": true }, "description": "The same ask as `transforms`, written as a plugin. `[{ \"id\": \"context-compression\" }]` asks for middle-out compression, and an entry may carry configuration beside its `id`, which is accepted and not read. `context-compression` is the only served id, and any other, `web` included, receives HTTP 400 naming the id." }, "model": { "type": "string", "description": "A marketplace model id, the same as `/chat/completions` takes." }, "messages": { "type": "array", "description": "The conversation, at least one message. Each is a `user` or `assistant` turn whose content is a string or an array of `text`, `image`, `tool_use` and `tool_result` blocks. A `system` turn placed among them is accepted, and its text joins the leading system prompt rather than staying where it sits. An `image` or `document` block whose `source` is `{ \"type\": \"file\", \"file_id\": \"…\" }` names a file stored with `/files`, which is read into the request before routing." }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Ceiling on generated tokens (required)." }, "system": { "type": [ "string", "array" ], "description": "A system prompt, as a string or an array of `text` blocks. The text of any `system` turn in `messages` follows it, a blank line apart, in one leading system message." }, "metadata": { "type": "object", "description": "Opaque request metadata; accepted and ignored." }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "Up to eight sequences that end the generation." }, "stream": { "type": "boolean", "description": "Answer with an Anthropic event stream instead of one object." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Nucleus sampling mass." }, "top_k": { "type": "integer", "minimum": 0, "description": "Sample from the k likeliest tokens." }, "tools": { "type": "array", "description": "Tools the model may call, each a `name`, optional `description` and `input_schema`. The client runs them: an entry whose `type` names one of Anthropic's hosted web search versions (`web_search_20250305` and later) asks for a search the marketplace does not run and is refused with HTTP 400, while a function the client declares under the name `web_search` is its own." }, "tool_choice": { "type": "object", "description": "How tools may be used: `auto`, `any`, `none`, or a named `tool`." }, "thinking": { "type": "object", "description": "Extended-thinking config; accepted and ignored, since a routed model decides for itself." } } }, "AnthropicCountTokensRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "A marketplace model id." }, "messages": { "type": "array", "description": "The conversation to count, in the Messages shape." }, "system": { "type": [ "string", "array" ], "description": "A system prompt, counted alongside the messages." }, "tools": { "type": "array", "description": "Tool definitions, counted alongside the messages." } } }, "ResponsesRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "input" ], "properties": { "models": { "type": "array", "items": { "type": "string" }, "description": "Fallback list, at most 20. The first id that can be routed serves the request." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." }, "route": { "type": "string", "enum": [ "fallback", "sort" ], "deprecated": true, "description": "Alias for sort.partition: fallback groups by model; sort orders across models. An explicit provider.sort.partition wins, followed by this alias, then the workspace partition. Other values receive HTTP 400 naming route." }, "transforms": { "type": "array", "items": { "type": "string", "enum": [ "middle-out" ] }, "description": "Prompt transforms. `[\"middle-out\"]` asks for middle-out compression against the chosen endpoint's context window, applied after routing has picked that endpoint. The system message, the earliest user turn and the latest turns are kept, messages are dropped from the middle, and a tool call is never separated from its result. `usage` reports what was actually sent. `[]` declines compression, and so does an absent member. Any other element receives HTTP 400 naming the element and its value." }, "plugins": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Which plugin to apply. `context-compression` is the only served id." } }, "additionalProperties": true }, "description": "The same ask as `transforms`, written as a plugin. `[{ \"id\": \"context-compression\" }]` asks for middle-out compression, and an entry may carry configuration beside its `id`, which is accepted and not read. `context-compression` is the only served id, and any other, `web` included, receives HTTP 400 naming the id." }, "model": { "type": "string", "description": "A marketplace model id, the same as `/chat/completions` takes." }, "prompt_cache_key": { "type": "string", "maxLength": 256, "description": "A cache affinity hint that outranks the `X-Session-Id` header. The resolved id reaches the serving endpoint as `x-session-id`." }, "input": { "type": [ "string", "array" ], "description": "The conversation: a string, or an array of `message`, `function_call` and `function_call_output` items. An `input_file` content block carries `file_data` or `file_url`, or names a file stored with `/files` as `file_id`, which is read into the request before routing." }, "instructions": { "type": "string", "description": "A system prompt, prepended to the conversation." }, "tools": { "type": "array", "description": "Tools the model may call, each a flat `{ type: \"function\", name, description, parameters }`." }, "tool_choice": { "type": [ "string", "object" ], "description": "How tools may be used: `auto`, `none`, `required`, or a named function." }, "reasoning": { "type": "object", "description": "Reasoning config; its `effort` maps to `reasoning_effort`." }, "text": { "type": "object", "description": "Output shape. `format` is `{\"type\":\"text\"}` (prose, the default), `{\"type\":\"json_object\"}` (JSON mode, sent as `response_format`) or `{\"type\":\"json_schema\",\"name\":…,\"schema\":…,\"strict\":…}`, which is sent as a `json_schema` `response_format` and routed only to endpoints declaring `structured_outputs`. Any other `format.type` is refused with HTTP 400 before inference." }, "stream": { "type": "boolean", "description": "Answer with a `response.*` event stream instead of one object." }, "max_output_tokens": { "type": "integer", "minimum": 1, "description": "Ceiling on generated tokens." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature." }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "description": "Nucleus sampling mass." }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "False asks for at most one tool call per turn. Advisory: forwarded where the serving endpoint declares parallel_tool_calls, and otherwise reported unhonoured. Response objects report parallel_tool_calls: true as a placeholder." }, "previous_response_id": { "type": "null", "description": "Omit or set to null. A non-null value is refused with HTTP 400 naming previous_response_id; send the full conversation in input." }, "background": { "type": [ "boolean", "null" ], "enum": [ false, null ], "description": "Omit or set to false/null for foreground execution. True is refused with HTTP 400 naming background." }, "store": { "type": [ "boolean", "null" ], "description": "Accepted without effect; responses are not retained server-side." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Ignored response-include hints." }, "metadata": { "type": "object", "description": "Opaque request metadata; accepted and ignored." }, "user": { "type": "string", "description": "Accepted without effect; not forwarded by the Responses translation." } } }, "CompletionRequest": { "type": "object", "additionalProperties": true, "required": [ "prompt" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Fallback list, at most 20. The first id that can be routed serves the request." }, "prompt": { "type": "string", "description": "The text to continue." }, "stream": { "type": "boolean", "description": "Return text deltas as SSE, ending with usage and [DONE]." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature." }, "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Nucleus sampling mass in (0, 1]. Zero is rejected with 400, not replaced with a default." }, "top_k": { "type": "integer", "minimum": -1, "description": "Sample from the k likeliest tokens; -1 disables the filter where an endpoint declares it." }, "frequency_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "Penalise repetition by count." }, "presence_penalty": { "type": "number", "minimum": -2, "maximum": 2, "description": "Penalise tokens already present." }, "repetition_penalty": { "type": "number", "exclusiveMinimum": 0, "maximum": 2, "description": "Multiplicative repetition penalty in (0, 2]; forwarded when the endpoint declares repetition_penalty." }, "seed": { "type": "integer", "description": "Ask for a reproducible sample." }, "stop": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "Sequences that end the generation." }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 1048576, "description": "Ceiling on generated tokens." }, "logprobs": { "type": "integer", "description": "How many log probabilities to return per position." }, "echo": { "type": "boolean", "description": "Repeat the prompt before the completion." }, "suffix": { "type": "string", "description": "Text to place after the completion." }, "user": { "type": "string", "description": "An opaque end-user identifier." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." }, "route": { "type": "string", "enum": [ "fallback", "sort" ], "deprecated": true, "description": "Alias for sort.partition: fallback groups by model; sort orders across models. An explicit provider.sort.partition wins, followed by this alias, then the workspace partition. Other values receive HTTP 400 naming route." } } }, "EmbeddingsRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "input": { "type": [ "string", "array" ], "description": "One text or a batch of them, pre-tokenized integer arrays, or a multimodal batch — items of `{ content: [...] }` whose parts are `{ type: \"text\", text }`, `{ type: \"image_url\", image_url: { url } }`, or `{ type: \"input_audio\" | \"input_video\" | \"input_file\", : { data, format } }` carrying the bytes base64-encoded. A multimodal input is refused on a model whose declared input modalities do not cover the parts it carries. A multimodal model can embed a content item and a plain string in two bases whose vectors are not interchangeable, so an index and the queries run against it use one shape." }, "input_type": { "type": "string", "description": "Hint at how the vectors will be used, e.g. `search_query`, `search_document`." }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "description": "How the vectors come back." }, "dimensions": { "type": "integer", "minimum": 1, "description": "Truncate to this many dimensions where the model allows it." }, "user": { "type": "string", "description": "An opaque end-user identifier." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." } } }, "DecisionsEntry": { "description": "Plain text or structured guidance.", "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ] }, "DecisionsChoiceQuestion": { "type": "object", "required": [ "type", "instructions", "criteria" ], "properties": { "type": { "type": "string", "enum": [ "choice" ], "description": "Choose one named option." }, "instructions": { "$ref": "#/components/schemas/DecisionsEntry" }, "criteria": { "type": "object", "minProperties": 1, "maxProperties": 255, "description": "Named options and their optional guidance.", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/DecisionsEntry" }, { "type": "null" } ] } } } }, "DecisionsScoreQuestion": { "type": "object", "required": [ "type", "instructions", "criteria" ], "properties": { "type": { "type": "string", "enum": [ "score" ], "description": "Score against ordered levels." }, "instructions": { "$ref": "#/components/schemas/DecisionsEntry" }, "criteria": { "type": "array", "minItems": 1, "description": "Ordered level guidance, starting at zero.", "items": { "$ref": "#/components/schemas/DecisionsEntry" } } } }, "DecisionsNoulQuestion": { "type": "object", "required": [ "type", "instructions" ], "properties": { "type": { "type": "string", "enum": [ "noul" ], "description": "Estimate the probability of true." }, "instructions": { "$ref": "#/components/schemas/DecisionsEntry" }, "criteria": { "type": "object", "required": [ "true", "false" ], "additionalProperties": false, "description": "Optional guidance for the true and false outcomes.", "properties": { "true": { "$ref": "#/components/schemas/DecisionsEntry" }, "false": { "$ref": "#/components/schemas/DecisionsEntry" } } } } }, "DecisionsChoiceAnswer": { "type": "object", "required": [ "type", "choice", "probabilities", "confidence" ], "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "choice": { "type": "string", "description": "Selected criteria key." }, "probabilities": { "type": "object", "description": "Probability of each criteria key.", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "answer_confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "DecisionsScoreAnswer": { "type": "object", "required": [ "type", "score", "probabilities", "legend", "confidence" ], "properties": { "type": { "type": "string", "enum": [ "score" ] }, "score": { "type": "number", "description": "Score between zero and the last level." }, "probabilities": { "type": "object", "description": "Probability of each zero-based level.", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "legend": { "type": "object", "description": "Guidance for each zero-based level.", "additionalProperties": { "$ref": "#/components/schemas/DecisionsEntry" } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "answer_confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "DecisionsNoulAnswer": { "type": "object", "required": [ "type", "noul" ], "properties": { "type": { "type": "string", "enum": [ "noul" ] }, "noul": { "type": "number", "minimum": 0, "maximum": 1 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "answer_confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "DecisionsRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "state", "questions" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "state": { "description": "The text or structured content judged by every question.", "oneOf": [ { "$ref": "#/components/schemas/DecisionsEntry" } ] }, "questions": { "type": "object", "minProperties": 1, "description": "Questions keyed by caller chosen identifiers; each carries a type, instructions and any criteria.", "maxProperties": 256, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/DecisionsChoiceQuestion" }, { "$ref": "#/components/schemas/DecisionsScoreQuestion" }, { "$ref": "#/components/schemas/DecisionsNoulQuestion" } ] } }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." }, "user": { "type": "string", "maxLength": 256, "description": "An opaque end-user identifier." }, "session_id": { "type": "string", "maxLength": 256, "description": "An opaque session identifier for routing affinity." }, "trace": { "type": "object", "additionalProperties": true, "description": "Trace metadata accepted by the marketplace and omitted from the upstream request." } } }, "DecisionsUsage": { "type": "object", "required": [ "input_tokens", "output_tokens", "cost" ], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "description": "Tokens processed over all question rows." }, "output_tokens": { "type": "integer", "enum": [ 0 ], "description": "No output tokens are generated." }, "cost": { "type": [ "number", "null" ], "description": "Charge in USD; null where the endpoint declared no applicable price." } } }, "DecisionsReply": { "type": "object", "required": [ "id", "model", "provider", "answers", "usage" ], "properties": { "id": { "type": "string", "description": "Generation identifier." }, "model": { "type": "string", "description": "Marketplace model identifier." }, "provider": { "type": "string", "description": "Serving provider." }, "answers": { "type": "object", "description": "One typed answer for each submitted question.", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/DecisionsChoiceAnswer" }, { "$ref": "#/components/schemas/DecisionsScoreAnswer" }, { "$ref": "#/components/schemas/DecisionsNoulAnswer" } ] } }, "usage": { "$ref": "#/components/schemas/DecisionsUsage" } } }, "RerankRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "query", "documents" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "query": { "type": "string", "description": "What the documents are scored against." }, "documents": { "type": "array", "minItems": 1, "maxItems": 2048, "description": "The documents to score. Each is a string, or an object carrying `text`, `image`, or both for a vision reranker. An image document requires an endpoint declaring image input; if none qualify, routing returns 503 with input_unsupported before calling a provider or reserving credit.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true, "properties": { "text": { "type": "string" }, "image": { "type": "string", "description": "A data URI or an https URL." } } } ] } }, "top_n": { "type": "integer", "minimum": 1, "description": "How many of the highest-scoring documents come back. Absent returns all of them." }, "return_documents": { "type": "boolean", "description": "Echo each result's document back beside its score, exactly as it was submitted." }, "user": { "type": "string", "description": "An opaque end-user identifier." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific parameters keyed by provider slug; only the matched provider key is read. Each name must be declared as a passthrough parameter by the endpoint that serves the request, and its value must satisfy the declared descriptor. An undeclared name or an inadmissible value is refused with HTTP 400; a declared one is forwarded to the provider unchanged." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." } } }, "SpeechRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "input": { "type": "string", "maxLength": 15000, "description": "The text to synthesize. Its length in characters is the unit billed." }, "voice": { "type": "string", "description": "A voice an endpoint of the model declares, which `GET /speech/models` publishes. Absent asks for whichever voice the endpoint defaults to. The reference contract's own names (`alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`, `verse`) are accepted wherever an endpoint declares them, and where none does the request resolves to the one voice the model's endpoints offer between them — named back in `X-Heimdall-Voice` — or answers 400 listing the voices it is served with." }, "response_format": { "type": "string", "enum": [ "mp3", "wav", "pcm", "opus", "flac", "aac", "mulaw", "alaw" ], "description": "The codec the audio comes back in. Absent is `mp3`." }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "description": "Playback rate, honoured only where the endpoint declares a range covering it." }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Sampling seed, honoured only where the endpoint declares it." }, "max_new_tokens": { "type": "integer", "minimum": 1, "maximum": 4096, "description": "Generation token limit, honoured only where the endpoint declares it." }, "instructions": { "type": "string", "description": "Free text steering delivery, where the endpoint honours it." }, "input_references": { "type": "array", "maxItems": 1, "description": "One voice sample to clone, at most 5 MiB of decoded bytes. Requires declared speech input_references and audio input. The sample takes precedence over voice and is not saved as a voice profile.", "items": { "type": "object", "additionalProperties": false, "required": [ "type", "input_audio" ], "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "additionalProperties": false, "required": [ "data", "format" ], "properties": { "data": { "type": "string", "description": "Raw audio bytes, base64-encoded, not a data URI." }, "format": { "type": "string", "description": "Container or codec of the sample." } } }, "transcript": { "type": "string", "description": "What the sample says, where it is known." }, "role": { "type": [ "string", "null" ], "enum": [ "reference", null ], "description": "What this item is for, `reference` when it is omitted or null. `reference`: Conditioning the engine applies however it applies that kind: an image to edit or keep the look of, a clip to follow, a voice to clone. Only the roles the endpoint lists under `reference_inputs` are accepted; any other is refused before inference, naming the ones that are." } } } }, "user": { "type": "string", "description": "An opaque end-user identifier." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific passthrough keyed by provider slug; only the serving provider's key is read." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." } } }, "TranscriptionRequest": { "type": "object", "additionalProperties": true, "required": [ "model" ], "description": "Either `multipart/form-data` — the audio as a `file` part, every other member a form field, coerced here from the string every field arrives as — or JSON with the audio as base64 bytes under `input_audio`, for an upload over the multipart route's 25 MB cap.", "properties": { "model": { "type": "string", "description": "Model id as `author/slug`, optionally suffixed `:free`, `:nitro` (fastest) or `:floor` (cheapest) or `:exacto` (measured tool-call reliability, requiring declared parameters). `:online` is refused with HTTP 400 because web search plugins are unsupported. `provider/slug` or `provider/author/slug` names the model that provider serves under that slug and routes to that provider alone; a catalogue id always takes precedence." }, "input_audio": { "type": "object", "additionalProperties": false, "required": [ "data", "format" ], "description": "Base64-encoded audio, on the JSON body variant only.", "properties": { "data": { "type": "string", "description": "Raw audio bytes, base64-encoded, not a data URI. A string that is not base64 is refused rather than decoded to whichever of its characters the alphabet holds." }, "format": { "type": "string", "description": "Container or codec, e.g. `wav`, `mp3`, `flac`, `m4a`, `ogg`, `webm`, `aac`." } } }, "language": { "type": "string", "description": "ISO-639-1 code of the spoken language, where known." }, "prompt": { "type": "string", "description": "Context to bias spelling and punctuation." }, "response_format": { "type": "string", "enum": [ "json", "text", "verbose_json" ], "description": "What the transcript comes back as." }, "max_completion_tokens": { "type": "integer", "minimum": 1, "description": "Transcript generation token limit, where the endpoint declares it." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sampling temperature." }, "timestamp_granularities": { "type": "array", "items": { "type": "string", "enum": [ "segment", "word" ] }, "description": "Repeat the field as `timestamp_granularities[]` for each level wanted." }, "stream": { "type": "boolean", "description": "Refused on this route: transcriptions do not stream." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific passthrough keyed by provider slug; only the serving provider's key is read." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Provider eligibility, ordering and measured performance preferences." } } }, "AuthKeysRequest": { "type": "object", "required": [ "code", "code_verifier" ], "properties": { "code": { "type": "string", "description": "The one-time code the callback URL was returned to the application with." }, "code_verifier": { "type": "string", "description": "The secret the application generated before sending the browser to `/auth` and hashed into `code_challenge`. 43 to 128 characters from `A-Z a-z 0-9 - . _ ~`, per RFC 7636." }, "code_challenge_method": { "type": "string", "enum": [ "S256" ], "description": "S256, the only method served. A `plain` challenge travels in the address bar as the very secret this exchange asks for, which is what PKCE exists to avoid." }, "callback_url": { "type": "string", "description": "The callback the code was issued for. Optional; when sent it must match, which binds a code to the address the application published rather than only to the verifier." } } }, "X402DepositRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "description": "USD as an exact decimal string, such as `\"25\"` or `\"25.00\"`. A number is refused: a float amount stops meaning what it says." }, "network": { "type": "string", "description": "CAIP-2 network id, such as `eip155:8453`. Optional where the rail quotes one chain, which leaves nothing to choose between." } } }, "Usage": { "type": "object", "description": "What an exchange consumed, as the endpoint that served it stated. A count the endpoint never stated is absent rather than zero, and `total_tokens` is sent only where both of its terms are. `cost` is the marketplace's own figure and is on every usage object it sends.", "required": [ "cost" ], "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens read from the request, where the endpoint stated a count." }, "completion_tokens": { "type": "integer", "description": "Tokens generated, where the endpoint stated a count." }, "total_tokens": { "type": "integer", "description": "The two counts summed, present only where both of them are." }, "prompt_tokens_details": { "type": "object", "description": "The share of `prompt_tokens` the endpoint served from or wrote to its own prefix cache, present only where it reported one.", "properties": { "cached_tokens": { "type": "integer", "description": "Prompt tokens served from the cache." }, "cache_write_tokens": { "type": "integer", "description": "Prompt tokens written into it." }, "audio_tokens": { "type": "integer", "description": "Prompt tokens that were audio." } } }, "completion_tokens_details": { "type": "object", "description": "The share of `completion_tokens` the endpoint reported separately, present only where it reported one.", "properties": { "reasoning_tokens": { "type": "integer", "description": "Generated tokens spent deliberating." }, "audio_tokens": { "type": "integer", "description": "Generated tokens that were audio." } } }, "cost": { "type": "number", "description": "USD charged for this generation. The marketplace holds the figure as ExactUsd and formats it to a number only at the wire boundary." }, "cost_details": { "type": "object", "description": "What the endpoint charged the marketplace, where the endpoint priced it.", "properties": { "upstream_inference_cost": { "type": [ "number", "null" ], "description": "The endpoint's own total." }, "upstream_inference_prompt_cost": { "type": "number", "description": "Its share for the prompt." }, "upstream_inference_completions_cost": { "type": "number", "description": "Its share for the completion." } } } } }, "ChatCompletionReply": { "type": "object", "description": "An OpenAI `chat.completion`, with the marketplace's own id, resolved model and serving provider written over whatever the endpoint sent. `usage` is absent on a reply the marketplace could not finish accounting for, which is the one shape that would otherwise have to publish counts nobody measured.", "required": [ "id", "object", "created", "model", "provider", "choices" ], "properties": { "id": { "type": "string", "description": "The generation id, as `X-Generation-Id` also carries." }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "provider": { "type": "string", "description": "The provider whose endpoint served it." }, "choices": { "type": "array", "items": { "type": "object" }, "description": "The answers, in the endpoint's own shape: an `index`, a `message` and a `finish_reason` per choice." }, "honoured": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per member the request carried whose honouring depends on the endpoint, whether it reached the engine. Each rail forwards its own core members under no declaration at all, and forwards everything else only where the serving endpoint names it in `supported_parameters`; `true` is that promise rather than a claim about what the engine did with the member. A member the request did not carry is absent rather than false, and a request carrying none of them has no `honoured` object at all. A streamed reply states the same verdict on the final frame, the one carrying `usage`: the headers are flushed before any endpoint has answered, so the frame that closes the accounting is the first point at which the endpoint that served the request is known. A stream that ended before the marketplace could close its accounting carries neither the usage frame nor the verdict." }, "usage": { "$ref": "#/components/schemas/Usage" }, "system_fingerprint": { "type": [ "string", "null" ], "description": "Carried through from the endpoint where it sent one." } } }, "CompletionReply": { "type": "object", "description": "An OpenAI `text_completion`, read the way `ChatCompletionReply` is read.", "required": [ "id", "object", "created", "model", "provider", "choices" ], "properties": { "id": { "type": "string", "description": "The generation id, as `X-Generation-Id` also carries." }, "object": { "type": "string", "enum": [ "text_completion" ] }, "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "provider": { "type": "string", "description": "The provider whose endpoint served it." }, "choices": { "type": "array", "items": { "type": "object" }, "description": "The completions: an `index`, a `text` and a `finish_reason` per choice." }, "honoured": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per member the request carried whose honouring depends on the endpoint, whether it reached the engine. Each rail forwards its own core members under no declaration at all, and forwards everything else only where the serving endpoint names it in `supported_parameters`; `true` is that promise rather than a claim about what the engine did with the member. A member the request did not carry is absent rather than false, and a request carrying none of them has no `honoured` object at all. A streamed reply states the same verdict on the final frame, the one carrying `usage`: the headers are flushed before any endpoint has answered, so the frame that closes the accounting is the first point at which the endpoint that served the request is known. A stream that ended before the marketplace could close its accounting carries neither the usage frame nor the verdict." }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "AnthropicUsage": { "type": "object", "description": "The Anthropic dialect's usage object. Both counts are members its clients read unconditionally, so a count the endpoint never stated is sent here as zero; what the marketplace measured is on the generation record, which holds the absence this wire has no room for. It has no `server_tool_use` member: that member counts searches Anthropic's API ran, and the marketplace runs none.", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Tokens read from the request." }, "output_tokens": { "type": "integer", "description": "Tokens generated." } } }, "AnthropicMessageReply": { "type": "object", "description": "An Anthropic `message`, translated from the completion the endpoint served.", "required": [ "id", "type", "role", "model", "content", "usage" ], "properties": { "id": { "type": "string", "description": "The message id this dialect names the turn by." }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string", "description": "The model id the request named." }, "content": { "type": "array", "items": { "type": "object" }, "description": "The reply's blocks: `text`, `tool_use` and `image` in the order they arrived. A search the model asked a client function for is a `tool_use` block; a `server_tool_use` or `web_search_tool_result` block never appears." }, "stop_reason": { "type": [ "string", "null" ], "description": "Why the turn ended." }, "stop_sequence": { "type": [ "string", "null" ], "description": "The stop sequence that ended it." }, "usage": { "$ref": "#/components/schemas/AnthropicUsage" } } }, "AnthropicCountTokensReply": { "type": "object", "description": "What the request would read, counted without generating anything.", "required": [ "input_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Tokens the messages come to." } } }, "ResponsesUsage": { "type": "object", "description": "The Responses dialect's usage object. All three members are ones its clients read unconditionally, so a count the endpoint never stated is sent here as zero, as it is on the Anthropic rail.", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "description": "Tokens read from the request." }, "output_tokens": { "type": "integer", "description": "Tokens generated." }, "total_tokens": { "type": "integer", "description": "The two summed." } } }, "ResponsesReply": { "type": "object", "description": "An OpenAI `response`, translated from the completion the endpoint served.", "required": [ "id", "object", "status", "model", "output", "usage" ], "properties": { "id": { "type": "string", "description": "The response id this dialect names the turn by." }, "object": { "type": "string", "enum": [ "response" ] }, "status": { "type": "string", "description": "`completed` or `incomplete`." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "output": { "type": "array", "items": { "type": "object" }, "description": "The output items: the assistant message, and a `function_call` per tool asked for." }, "incomplete_details": { "type": [ "object", "null" ], "description": "Why a turn stopped short, or null where it did not." }, "usage": { "$ref": "#/components/schemas/ResponsesUsage" } } }, "EmbeddingsUsage": { "type": "object", "description": "What an embedding read. `prompt_tokens` and `total_tokens` are the same figure and arrive together or not at all; an input the endpoint reported no count for carries neither.", "required": [ "cost" ], "properties": { "prompt_tokens": { "type": "integer", "description": "Tokens read from the input." }, "total_tokens": { "type": "integer", "description": "The same figure, under the name the reference uses." }, "prompt_tokens_details": { "type": "object", "description": "The per-modality share of `prompt_tokens`, present only where the input mixed modalities and the endpoint reported the split.", "properties": { "text_tokens": { "type": "integer", "description": "Tokens read from text." }, "image_tokens": { "type": "integer", "description": "Tokens read from images." }, "audio_tokens": { "type": "integer", "description": "Tokens read from audio." }, "video_tokens": { "type": "integer", "description": "Tokens read from video." }, "file_tokens": { "type": "integer", "description": "Tokens read from files." } } }, "cost": { "type": "number", "description": "USD charged for the embedding." } } }, "EmbeddingsReply": { "type": "object", "description": "An OpenAI embeddings list, with the marketplace's id, resolved model and provider.", "required": [ "object", "data", "model", "provider", "usage" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "id": { "type": "string", "description": "The generation id, as `X-Generation-Id` also carries." }, "data": { "type": "array", "items": { "type": "object" }, "description": "One `embedding` object per input, each with its `index` and vector." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "provider": { "type": "string", "description": "The provider whose endpoint served it." }, "honoured": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per member the request carried whose honouring depends on the endpoint, whether it reached the engine. Each rail forwards its own core members under no declaration at all, and forwards everything else only where the serving endpoint names it in `supported_parameters`; `true` is that promise rather than a claim about what the engine did with the member. A member the request did not carry is absent rather than false, and a request carrying none of them has no `honoured` object at all. A streamed reply states the same verdict on the final frame, the one carrying `usage`: the headers are flushed before any endpoint has answered, so the frame that closes the accounting is the first point at which the endpoint that served the request is known. A stream that ended before the marketplace could close its accounting carries neither the usage frame nor the verdict." }, "usage": { "$ref": "#/components/schemas/EmbeddingsUsage" } } }, "RerankUsage": { "type": "object", "description": "What a ranking cost. `search_units` is counted from the request the marketplace parsed and is therefore always known; a token count the endpoint never reported is absent.", "required": [ "search_units", "cost" ], "properties": { "search_units": { "type": "integer", "description": "One query against up to 100 documents, `ceil(documents / 100)`. Reported for reconciliation against the Cohere search-unit shape rather than as a charge of its own." }, "total_tokens": { "type": "integer", "description": "Tokens the ranking read, where the endpoint stated a count." }, "cost": { "type": "number", "description": "USD charged for the ranking." } } }, "RerankReply": { "type": "object", "description": "The ranking, highest score first.", "required": [ "id", "model", "provider", "results", "usage" ], "properties": { "id": { "type": "string", "description": "The generation id, as `X-Generation-Id` also carries." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "provider": { "type": "string", "description": "The provider whose endpoint served it." }, "results": { "type": "array", "items": { "type": "object" }, "description": "One entry per scored document: its `index` in the submitted array, its `relevance_score`, and under `return_documents` the document as the caller sent it." }, "honoured": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per member the request carried whose honouring depends on the endpoint, whether it reached the engine. Each rail forwards its own core members under no declaration at all, and forwards everything else only where the serving endpoint names it in `supported_parameters`; `true` is that promise rather than a claim about what the engine did with the member. A member the request did not carry is absent rather than false, and a request carrying none of them has no `honoured` object at all. A streamed reply states the same verdict on the final frame, the one carrying `usage`: the headers are flushed before any endpoint has answered, so the frame that closes the accounting is the first point at which the endpoint that served the request is known. A stream that ended before the marketplace could close its accounting carries neither the usage frame nor the verdict." }, "usage": { "$ref": "#/components/schemas/RerankUsage" } } }, "VideoJobRequest": { "type": "object", "description": "What a caller asks a video job for. `model` is the only member every request carries; everything else is optional because a model that animates a supplied frame needs no prompt, and geometry has two interchangeable spellings.", "required": [ "model" ], "properties": { "fps": { "description": "Frames per second, restricted to the serving endpoint’s frame grid.", "type": "integer", "minimum": 1, "maximum": 240 }, "negative_prompt": { "description": "Content the clip should avoid.", "type": "string", "maxLength": 32000 }, "steps": { "description": "Denoising steps, within the endpoint’s declared range.", "type": "integer", "minimum": 1, "maximum": 100 }, "guidance_scale": { "description": "Prompt adherence, within the endpoint’s declared range.", "type": "number", "minimum": 0, "maximum": 20 }, "reference_strength": { "description": "How closely to follow the supplied reference.", "type": "number", "minimum": 0.01, "maximum": 1 }, "sampler": { "description": "A sampler the endpoint declares.", "type": "string", "maxLength": 64 }, "scheduler": { "description": "A scheduler the endpoint declares.", "type": "string", "maxLength": 64 }, "model": { "type": "string", "description": "The model to render with, as the catalogue spells it." }, "prompt": { "type": "string", "description": "What the clip should show. Optional: a model that animates a supplied frame takes the picture in place of the words, and one that needs a prompt refuses a request without one." }, "duration": { "type": "number", "exclusiveMinimum": 0, "description": "Requested clip length in seconds. It is the meter: the bill is the delivered duration at the endpoint’s declared per-second rate." }, "resolution": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "1K", "2K", "4K" ], "description": "The resolution tier to render at, narrowed per model by `supported_resolutions`. Where an endpoint prices its tiers separately, this is what selects the rate." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9", "9:21" ], "description": "The shape to render at, narrowed per model by `supported_aspect_ratios`." }, "size": { "type": "string", "description": "Exact pixel dimensions as `WIDTHxHEIGHT`, interchangeable with a resolution tier and an aspect ratio." }, "seed": { "type": "integer", "description": "Fixing it makes a generation reproducible on the same endpoint." }, "generate_audio": { "type": "boolean", "description": "Whether to score a soundtrack into the clip. Omission leaves the choice to the endpoint’s own default. Sound is billed by the same per-second rate as the rest of the clip, so asking for it adds no second charge." }, "frame_images": { "type": "array", "items": { "type": "object", "required": [ "type", "image_url", "frame_type" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An inline base64 data URI, in one of the media types the endpoint declares for that kind. The marketplace fetches nothing on a caller’s behalf, so the bytes ride in the request rather than behind a URL." } } }, "frame_type": { "type": "string", "enum": [ "first_frame", "last_frame" ] } } }, "description": "Images to pin to the first and last frame. The role is on the image rather than on its position in the array, because an array of one carries no position that says which end it is." }, "input_references": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_url", "audio_url", "video_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An inline base64 data URI, in one of the media types the endpoint declares for that kind. The marketplace fetches nothing on a caller’s behalf, so the bytes ride in the request rather than behind a URL." } } }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An inline base64 data URI, in one of the media types the endpoint declares for that kind. The marketplace fetches nothing on a caller’s behalf, so the bytes ride in the request rather than behind a URL." } } }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An inline base64 data URI, in one of the media types the endpoint declares for that kind. The marketplace fetches nothing on a caller’s behalf, so the bytes ride in the request rather than behind a URL." } } }, "role": { "type": [ "string", "null" ], "enum": [ "reference", "canny", "depth", "normal", "openpose", "segmentation", "edges", "pose", "seg", null ], "description": "What this item is for, `reference` when it is omitted or null. `reference`: Conditioning the engine applies however it applies that kind: an image to edit or keep the look of, a clip to follow, a voice to clone. `canny`: An edge map in the Canny convention, white lines on black, that the render keeps the silhouettes of. `depth`: A depth pass, near bright and far dark, that the render keeps the geometry of. `normal`: A surface-normal pass, XYZ as RGB, that the render keeps the surface orientation of. `openpose`: A skeleton render in the OpenPose colour convention that the figures in the render take the stance of. `segmentation`: A flat-colour label pass, one colour per object, that the render keeps the layout of. `edges` is read as `canny`, `pose` is read as `openpose`, `seg` is read as `segmentation`. Only the roles the endpoint lists under `reference_inputs` are accepted; any other is refused before inference, naming the ones that are." } } }, "description": "Assets that condition the generation without being frames of it, each carrying what it is for as `role`: `reference` when absent, or a control pass the render keeps the structure of. An image is never a frame here — a pinned still is a `frame_images` item, and reaches the endpoint under `first_frame` or `last_frame`. A role is admitted per kind, as `GET /videos/models` lists under `supported_reference_roles`: a picture or a clip takes any control pass, and a sample takes `reference` alone. The job is routed only to an endpoint declaring every role the array carries for that kind, and a combination of control passes no endpoint loads together fails it naming the sets that are." }, "callback_url": { "type": "string", "format": "uri", "description": "Where to post the job once it reaches a terminal status, so a caller need not poll. HTTPS only: the notification names a job an API key can read, and a cleartext hop would publish it." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific passthrough keyed by provider slug; only the serving provider's key is read." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Routing preferences, plus the per-slug passthrough carrying an engine’s own knobs. Only the keys `GET /videos/models` publishes under `allowed_passthrough_parameters` are forwarded." } } }, "GenerationJobUsage": { "type": "object", "description": "What a job cost, once it has completed. Absent before then, because a job that has generated nothing has consumed nothing to report. One schema across every job rail, because what a job cost is the same answer whatever it produced.", "properties": { "cost": { "type": [ "number", "null" ], "description": "USD the generation was billed. Null where the units it consumed carry no declared price: an asset nothing priced is recorded unpriced and flagged, never reported as free." }, "is_byok": { "type": "boolean", "description": "Whether the request was served against the caller’s own provider key." } } }, "VideoJob": { "type": "object", "description": "A job as all three job routes report it. `id`, `polling_url` and `status` are always present; every other member appears once there is something to say, so an absent one is a fact not yet established rather than an empty one.", "required": [ "id", "polling_url", "status" ], "properties": { "id": { "type": "string", "description": "The job id, of the form `vjob_` and 32 hex characters." }, "polling_url": { "type": "string", "description": "Where to read the job next, relative to the API origin." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled", "expired" ], "description": "`pending` is accepted and not yet started, `in_progress` is rendering, and the other four are terminal: `completed` produced its clips, which stay fetchable until the job's window closes, or for 10 minutes after their first delivery, `failed` carries the reason, `cancelled` was stopped before it produced one, and `expired` is a job whose delivery window closed with nothing fetched from it; a job fetched from, even in part, stays `completed` after its window closes, with no content left to fetch." }, "generation_id": { "type": "string", "description": "The generation this job bills through, once it has been processed. Absent before then." }, "unsigned_urls": { "type": "array", "items": { "type": "string" }, "description": "Where each rendered clip can be fetched, in index order. Present while there is content to fetch; each stays readable until the job's window closes, or for 10 minutes after its first delivery." }, "clip_durations_seconds": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Seconds of finished clip, measured from what rendered rather than requested, one entry per `unsigned_urls` in the same order. Null where a clip’s own container carried no duration to read." }, "usage": { "$ref": "#/components/schemas/GenerationJobUsage" }, "error": { "type": "string", "description": "Why the job failed, in the caller’s terms. Present only on a failure." } } }, "BatchCreateRequest": { "type": "object", "description": "Requests to run together against one endpoint. The members are exactly these; anything else is refused.", "required": [ "endpoint", "requests" ], "properties": { "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/responses", "/v1/messages" ], "description": "The request shape every `body` is written in: the route of the same name, under `/v1`." }, "model": { "type": "string", "minLength": 1, "description": "A model for every request. A request whose `body` names no model takes it; one that names a different model fails on its own." }, "provider": { "type": "object", "additionalProperties": false, "description": "Provider preferences for every request whose `body` states none: the providers to use, and whether to fall back past them.", "properties": { "only": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 }, "maxItems": 64, "description": "Provider slugs to use." }, "allow_fallbacks": { "type": [ "boolean", "null" ], "description": "Whether another provider may serve a request the preferred ones cannot." } } }, "completion_window": { "type": "string", "enum": [ "24h" ], "default": "24h", "description": "How long the batch has to end, from its submission. A request not sent by then is not sent, and the batch ends `expired`." }, "requests": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "The requests, each a `custom_id` unique within the batch and a `body`.", "items": { "type": "object", "additionalProperties": false, "required": [ "custom_id", "body" ], "properties": { "custom_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The caller’s handle for the request, echoed in its result. Printable text without control characters." }, "body": { "type": "object", "additionalProperties": true, "description": "The request body the batch’s endpoint takes, without `stream`." } } } } } }, "Batch": { "type": "object", "description": "A batch as every route reports it. `results` is null everywhere except a retrieved batch that has ended and whose results file is still held.", "required": [ "id", "object", "endpoint", "model", "completion_window", "status", "created_at", "expires_at", "finalized_at", "request_counts", "results_file_id", "results", "error" ], "properties": { "id": { "type": "string", "pattern": "^batch_[0-9a-f]{32}$", "description": "The batch id, of the form `batch_` and 32 hex characters." }, "object": { "type": "string", "enum": [ "batch" ], "description": "Always `batch`." }, "endpoint": { "type": "string", "enum": [ "/v1/chat/completions", "/v1/responses", "/v1/messages" ], "description": "The endpoint every request targets." }, "model": { "type": [ "string", "null" ], "description": "The model the batch stated for every request, or null where each request names its own." }, "completion_window": { "type": "string", "enum": [ "24h" ], "description": "How long the batch had to end." }, "status": { "type": "string", "enum": [ "validating", "in_progress", "cancelling", "completed", "failed", "expired", "cancelled" ], "description": "`validating` is stored and waiting for the runner, `in_progress` is being sent, and `cancelling` is a cancellation waiting for the requests in flight to settle. The other four are terminal: `completed` means every request has an outcome, `failed` that no request was runnable, `expired` that the completion window closed first, and `cancelled` that the caller stopped it." }, "created_at": { "type": "integer", "description": "When the batch was stored, in unix seconds." }, "expires_at": { "type": "integer", "description": "When the completion window closes, in unix seconds." }, "finalized_at": { "type": [ "integer", "null" ], "description": "When the batch reached a terminal status, in unix seconds; null until it does." }, "request_counts": { "type": "object", "required": [ "total", "completed", "failed" ], "description": "The requests in the batch and how many ended each way. A request stopped or expired before it was sent is in neither count.", "properties": { "total": { "type": "integer", "description": "Requests in the batch." }, "completed": { "type": "integer", "description": "Requests that were answered." }, "failed": { "type": "integer", "description": "Requests that ended in an error." } } }, "results_file_id": { "type": [ "string", "null" ], "description": "The file in the account’s file store the results were written to, one JSON line per request. Null until the batch ends. The file expires 48 hours later and answers 404 from then on, as any expired file does; the id is cleared once the file has been removed." }, "results": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BatchResult" }, "description": "The outcome of every request in submission order. Null until the batch ends, in a list, and once the results file is gone." }, "error": { "type": [ "object", "null" ], "required": [ "message" ], "description": "Why the batch failed. Null on every batch that did not.", "properties": { "message": { "type": "string", "description": "The reason." } } } } }, "BatchResult": { "type": "object", "description": "One request’s outcome. Exactly one of `response` and `error` is non-null.", "required": [ "id", "custom_id", "response", "error" ], "properties": { "id": { "type": "string", "description": "The request’s id within the results, `breq_` and 32 hex characters." }, "custom_id": { "type": "string", "description": "The `custom_id` the request was submitted with." }, "response": { "type": [ "object", "null" ], "required": [ "status_code", "request_id", "body" ], "description": "What the endpoint answered, on a request that was answered.", "properties": { "status_code": { "type": "integer", "description": "The status the live route answers with: 200." }, "request_id": { "type": "string", "description": "The id the request was billed under, the value `X-Generation-Id` carries on a live request." }, "body": { "type": "object", "additionalProperties": true, "description": "The body the live route answers with." } } }, "error": { "type": [ "object", "null" ], "required": [ "type", "message", "param", "code", "request_id" ], "description": "Why the request has no reply.", "properties": { "type": { "type": "string", "description": "The error type the live route would have answered with, or `batch_cancelled`, `batch_expired`, `results_full` or `response_too_large`." }, "message": { "type": "string", "description": "What went wrong." }, "param": { "type": [ "string", "null" ], "description": "Always null." }, "code": { "type": [ "integer", "null" ], "description": "The status the live route would have answered with; null for a request that was never sent." }, "request_id": { "type": [ "string", "null" ], "description": "The id the request was charged under, where it was charged and its reply was not kept." } } } } }, "BatchList": { "type": "object", "description": "A page of batches, newest first.", "required": [ "object", "data", "first_id", "last_id", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" }, "description": "The batches." }, "first_id": { "type": [ "string", "null" ], "description": "The id of the first batch on the page." }, "last_id": { "type": [ "string", "null" ], "description": "The id of the last batch on the page; pass it as `after` for the next page." }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "MeshRefinementOptions": { "type": "object", "additionalProperties": false, "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 300, "description": "A live image-input model with tool support from /meshes/refinement/models." }, "max_duration_seconds": { "type": "integer", "minimum": 60, "maximum": 2400, "default": 2400 }, "max_tool_calls": { "type": "integer", "minimum": 1, "maximum": 60, "default": 60 }, "max_model_cost_usd": { "type": "string", "default": "2", "description": "Exact decimal USD ceiling for the scoped model grant, above zero and at most 100. Machine time is billed separately." } } }, "MeshRefinementReport": { "type": "object", "additionalProperties": false, "required": [ "state", "model" ], "properties": { "state": { "type": "string", "enum": [ "waiting_generation", "queued", "starting", "running", "completed", "cancelled", "failed" ] }, "model": { "type": "string" }, "elapsed_ms": { "type": "number" }, "tool_calls": { "type": "integer" }, "model_cost_usd": { "type": "string" }, "vm_cost_usd": { "type": "string" }, "model_generations": { "type": "array", "items": { "type": "string" } }, "census_before": { "type": "object", "additionalProperties": { "type": "number" } }, "census_after": { "type": "object", "additionalProperties": { "type": "number" } }, "before_images": { "type": "array", "items": { "type": "string" } }, "after_images": { "type": "array", "items": { "type": "string" } }, "assessment": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "selected_asset_index": { "type": "integer", "minimum": 0, "maximum": 1 } } }, "BenchmarkVideoRequest": { "type": "object", "required": [ "model", "prompt", "size", "fps", "seconds", "seed", "generate_audio" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "size": { "type": "string", "enum": [ "512x512" ] }, "fps": { "type": "integer", "enum": [ 24 ] }, "seconds": { "type": "number", "enum": [ 4.041666666666667 ] }, "seed": { "type": "integer", "minimum": 42, "maximum": 46 }, "generate_audio": { "type": "boolean", "enum": [ false ] } } }, "BenchmarkMeshRequest": { "type": "object", "required": [ "model", "prompt" ], "additionalProperties": false, "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 } } }, "MeshJobRequest": { "type": "object", "description": "What a caller asks a mesh job for. `model` is the only member every request carries. One of `prompt` and `input_references` has to be present. A provider whose mesh engine cannot combine text and views refuses a request naming both.", "required": [ "model" ], "properties": { "refinement": { "$ref": "#/components/schemas/MeshRefinementOptions", "description": "Optional marketplace Blender repair with a selected vision model. Generation, model calls, and machine time are billed separately." }, "model": { "type": "string", "description": "The model to generate with, as the catalogue spells it." }, "prompt": { "type": "string", "maxLength": 32000, "description": "What to build. Optional with a supplied view; an image-only engine refuses text alongside a view." }, "target_faces": { "type": "integer", "minimum": 4, "maximum": 20000000, "description": "The most faces the mesh may carry, and a ceiling rather than a target: a decimator lands at or below it. Bounded here only against a typo; what an endpoint generates is its `mesh_envelope`, which `GET /meshes/models` publishes, and a count outside it is an unrouted request." }, "voxel_resolution": { "type": "integer", "minimum": 512, "maximum": 2048, "description": "Shape cascade resolution in voxels along each axis, within the selected endpoint’s declared choices." }, "texture_size": { "type": "integer", "minimum": 64, "maximum": 8192, "description": "Square texture atlas edge in pixels, within the selected endpoint’s declared choices." }, "camera_fov": { "type": "number", "minimum": 1, "maximum": 170, "description": "Horizontal camera field of view in degrees, where the selected endpoint declares it." }, "generate_texture": { "type": "boolean", "description": "Whether to bake a texture into the mesh. Omission leaves the choice to the endpoint’s own default. A texture is billed by the declared per-mesh rate like the rest of the asset unless the endpoint declares a tier for it, so asking for it adds no second charge." }, "input_references": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } }, "description": "An inline base64 data URI." } } }, "description": "Views of one object to build from, at most four, because more views are a different rig and a different model. Inline only: the marketplace fetches nothing on this rail, so a URL it accepted would be an ask it could not carry out." }, "seed": { "type": "integer", "minimum": 0, "description": "Fixing it makes a generation reproducible on the same endpoint." }, "negative_prompt": { "type": "string", "maxLength": 32000, "description": "What the text-to-image stage should avoid." }, "steps": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Sampling steps, within the provider’s declared limits." }, "guidance_scale": { "type": "number", "minimum": 0, "maximum": 20, "description": "Conditioning strength, within the selected endpoint’s declared limits." }, "sampler": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A sampling algorithm supported by the selected endpoint." }, "scheduler": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A sampling schedule supported by the selected endpoint." }, "callback_url": { "type": "string", "format": "uri", "description": "Where to post the job once it reaches a terminal status, so a caller need not poll. HTTPS only: the notification names a job an API key can read, and a cleartext hop would publish it." }, "provider": { "type": "object", "additionalProperties": false, "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "require_parameters": { "type": "boolean" }, "data_collection": { "type": "string", "enum": [ "allow", "deny" ] }, "zdr": { "type": "boolean" }, "quantizations": { "type": "array", "items": { "type": "string" } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "type": "object", "additionalProperties": false, "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ], "default": "model" } } } ], "description": "Model grouping is the default; partition none sorts eligible endpoints across models. Explicit by outranks model suffixes and workspace defaults. Exacto orders by measured tool fidelity." }, "preferred_min_throughput": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Minimum generation tokens per second; recent throughput percentiles are descending performance floors." }, "preferred_max_latency": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "object", "additionalProperties": false, "properties": { "p50": { "type": "number", "minimum": 0 }, "p75": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "p99": { "type": "number", "minimum": 0 } } } ], "description": "Preferred performance, using gated 30-minute measurements. A number selects p50. All named cutoffs apply. Missing measurements retain their slots; measured failures move behind measured passes inside capacity/health partitions. No endpoint is excluded. Explicit provider order takes precedence. Maximum time to first token in seconds." }, "enforce_distillable_text": { "type": "boolean", "description": "True requires verified model-author text-distillation permission. No such permission is measured, so true receives HTTP 503 with no_route and distillable_text_unverified." }, "options": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific passthrough keyed by provider slug; only the serving provider's key is read." }, "max_price": { "type": "object", "properties": { "prompt": { "type": "number", "minimum": 0, "description": "USD per million prompt tokens." }, "completion": { "type": "number", "minimum": 0, "description": "USD per million completion tokens." }, "request": { "type": "number", "minimum": 0, "description": "USD per request, where an endpoint charges one." }, "image_output": { "type": "number", "minimum": 0, "description": "USD per delivered output image." }, "image_output_token": { "type": "number", "minimum": 0, "description": "USD per output image token. Heimdallm extension; this ceiling is per token." }, "video_second": { "type": "number", "minimum": 0, "description": "USD per second of delivered video output." }, "image_megapixel": { "type": "number", "minimum": 0, "description": "USD per megapixel of image output." }, "audio_second": { "type": "number", "minimum": 0, "description": "USD per second of audio input." }, "image": { "type": "number", "minimum": 0, "description": "USD per input image. Output image prices use image_output or image_megapixel and are independent of this input-image ceiling." }, "audio": { "type": "number", "minimum": 0, "description": "USD per audio input token. The marketplace publishes no per-audio-token price, so this ceiling excludes no endpoint; audio input is bounded by audio_second." } }, "description": "Hard maximum prices. `prompt` and `completion` ceilings are per million tokens; every other key is per unit." } }, "description": "Routing preferences, plus the per-slug passthrough carrying an engine’s own knobs. Only the keys `GET /meshes/models` publishes under `allowed_passthrough_parameters` are forwarded." } } }, "MeshJob": { "type": "object", "description": "A job as all three job routes report it. `id`, `polling_url` and `status` are always present; every other member appears once there is something to say, so an absent one is a fact not yet established rather than an empty one.", "required": [ "id", "polling_url", "status" ], "properties": { "refinement": { "$ref": "#/components/schemas/MeshRefinementReport" }, "id": { "type": "string", "description": "The job id, of the form `mjob_` and 32 hex characters." }, "polling_url": { "type": "string", "description": "Where to read the job next, relative to the API origin." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled", "expired" ], "description": "`pending` is accepted and not yet started, `in_progress` is generating, and the other four are terminal: `completed` produced its assets, which stay fetchable until the job's window closes, or for 10 minutes after their first delivery, `failed` carries the reason, `cancelled` was stopped before it produced one, and `expired` is a job whose delivery window closed with nothing fetched from it; a job fetched from, even in part, stays `completed` after its window closes, with no content left to fetch." }, "generation_id": { "type": "string", "description": "The generation this job bills through, once it has been processed. Absent before then." }, "unsigned_urls": { "type": "array", "items": { "type": "string" }, "description": "Where each generated mesh can be fetched, in index order. Present while there is content to fetch; each stays readable until the job's window closes, or for 10 minutes after its first delivery." }, "meshes": { "type": "array", "items": { "type": "object", "required": [ "faces", "vertices", "has_texture", "bounds" ], "properties": { "faces": { "type": "integer", "description": "Triangles across the asset’s primitives." }, "vertices": { "type": "integer", "description": "Positions across those primitives." }, "has_texture": { "type": "boolean", "description": "Whether a material in the asset samples an image it carries." }, "bounds": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "max": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "description": "The axis-aligned box the scene occupies, composed through its node transforms." } } }, "description": "The geometry of each delivered asset, one entry per `unsigned_urls` in the same order, read off the GLB itself. A figure here is a measurement and never a claim the endpoint made." }, "usage": { "$ref": "#/components/schemas/GenerationJobUsage" }, "error": { "type": "string", "description": "Why the job failed, in the caller’s terms. Present only on a failure." } } }, "MeshModelsListResponse": { "type": "object", "description": "Every served model with a mesh output. Each declared member is the union across the model’s live endpoints, and null where none of them declares it — undeclared, not empty.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "canonical_slug", "name", "created", "hugging_face_id", "mesh_envelope", "supported_inputs", "reference_inputs", "generate_texture", "seed", "pricing_skus", "allowed_passthrough_parameters" ], "properties": { "id": { "type": "string", "description": "The catalogue id a request names." }, "canonical_slug": { "type": "string", "description": "The model’s canonical id." }, "name": { "type": "string", "description": "Display name." }, "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "description": { "type": "string", "description": "What the model is." }, "hugging_face_id": { "type": [ "string", "null" ], "description": "The weights this model is served from, where the catalogue knows them." }, "parameter_offers": { "type": "array", "description": "Distinct typed request domains offered by live sellers, grouped by output modality.", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "mesh_envelope": { "type": [ "object", "null" ], "required": [ "max_faces", "min_faces", "texture" ], "properties": { "max_faces": { "type": "integer" }, "min_faces": { "type": "integer" }, "texture": { "type": "boolean" } }, "description": "The widest envelope across the model’s live endpoints: the lowest floor, the highest ceiling, and a texture any one of them bakes. A floor as well as a ceiling, because a decimator handed a target below the surface it can close lands above the target in silence." }, "supported_inputs": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "text", "image" ] }, "description": "Whether the model’s endpoints build from words, from views, or both." }, "reference_inputs": { "type": [ "object", "null" ], "description": "What a view may be sent as: the container types the endpoints read and the most views they condition on." }, "generate_texture": { "type": [ "boolean", "null" ], "description": "Whether a texture can be baked into the mesh." }, "seed": { "type": [ "boolean", "null" ], "description": "Whether a fixed seed makes the generation reproducible." }, "pricing_skus": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "The per-mesh rate as a decimal string, under `mesh_output` and under that name suffixed for each condition an endpoint prices separately. A listing carrying only suffixed names declares no untiered rate, which is a partial declaration rather than a free tier." }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" }, "description": "The keys an endpoint accepts under `provider.options`; direct request controls appear in `parameter_offers`." } } } } } }, "VideoModelsListResponse": { "type": "object", "description": "Every served model with a video output. Each `supported_*` member is the union across the model’s live endpoints, and null where none of them declares it — undeclared, not empty.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "canonical_slug", "name", "created", "hugging_face_id", "supported_resolutions", "supported_aspect_ratios", "supported_sizes", "supported_durations", "supported_frame_images", "supported_reference_roles", "generate_audio", "seed", "pricing_skus", "allowed_passthrough_parameters" ], "properties": { "id": { "type": "string", "description": "The catalogue id a request names." }, "canonical_slug": { "type": "string", "description": "The model’s canonical id." }, "name": { "type": "string", "description": "Display name." }, "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "description": { "type": "string", "description": "What the model is." }, "hugging_face_id": { "type": [ "string", "null" ], "description": "The weights this model is served from, where the catalogue knows them." }, "parameter_offers": { "type": "array", "description": "Distinct typed request domains offered by live sellers, grouped by output modality.", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "supported_resolutions": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "1K", "2K", "4K" ] }, "description": "The resolution tiers the model’s endpoints declare between them." }, "supported_aspect_ratios": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9", "9:21" ] }, "description": "The shapes the model’s endpoints declare between them." }, "supported_sizes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Exact `WIDTHxHEIGHT` sizes, where endpoints declare sizes rather than tiers." }, "supported_durations": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "The clip lengths in seconds the model’s endpoints declare." }, "supported_frame_images": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "first_frame", "last_frame" ] }, "description": "Which ends of the clip an image may be pinned to: an endpoint taking an image as `first_frame` or `last_frame` under `reference_inputs.video` is one a `frame_images` item of that type reaches." }, "supported_reference_roles": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "image": { "type": "array", "items": { "type": "string", "enum": [ "reference", "first_frame", "last_frame", "canny", "depth", "normal", "openpose", "segmentation" ] } }, "audio": { "type": "array", "items": { "type": "string", "enum": [ "reference" ] } }, "video": { "type": "array", "items": { "type": "string", "enum": [ "reference", "canny", "depth", "normal", "openpose", "segmentation" ] } } }, "description": "Per input kind, every role the model’s endpoints take a reference under, in the role table’s order; the two frame placements appear here as well as under `supported_frame_images`. A kind absent is one no endpoint takes a reference of, and null is a model no endpoint of which declares references at all." }, "generate_audio": { "type": [ "boolean", "null" ], "description": "Whether a soundtrack can be scored into the clip." }, "seed": { "type": [ "boolean", "null" ], "description": "Whether a fixed seed makes the generation reproducible." }, "pricing_skus": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "The per-second rate as a decimal string, under `duration_seconds` and under that name suffixed by a resolution for each tier priced separately. A listing carrying only suffixed names declares no untiered rate, which is a partial declaration rather than a free tier." }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" }, "description": "The keys an endpoint accepts under `provider.options`; direct request controls appear in `parameter_offers`." } } }, "description": "One entry per served video model." } } }, "TranscriptionUsage": { "type": "object", "description": "What a transcription was billed on: seconds of audio for a duration-priced endpoint, tokens for one priced by them, never both. `seconds` is whole seconds rounded up from what the endpoint measured. An unreported figure is absent rather than zero.", "required": [ "cost" ], "properties": { "seconds": { "type": "integer", "description": "Whole seconds of audio, rounded up." }, "input_tokens": { "type": "integer", "description": "Tokens read from the upload." }, "output_tokens": { "type": "integer", "description": "Tokens of transcript generated." }, "total_tokens": { "type": "integer", "description": "The two summed, present where either is." }, "cost": { "type": "number", "description": "USD charged for the transcription." } } }, "TranscriptionReply": { "type": "object", "description": "The transcript, plus whatever the requested `response_format` adds: `verbose_json` carries `task`, `duration`, `language`, `segments` and, where asked for, `words`.", "required": [ "text", "model", "provider", "usage" ], "properties": { "text": { "type": "string", "description": "The transcript." }, "model": { "type": "string", "description": "The catalogue id routing resolved the request to." }, "provider": { "type": "string", "description": "The provider whose endpoint served it." }, "task": { "type": "string", "description": "The task performed, under `verbose_json`." }, "duration": { "type": "number", "description": "The endpoint's own measurement of the upload, fractional." }, "language": { "type": "string", "description": "The language detected." }, "segments": { "type": "array", "items": { "type": "object" }, "description": "Timed segments, each carrying `speaker` where the endpoint returns diarization." }, "words": { "type": "array", "items": { "type": "object" }, "description": "Timed words, asked for through `timestamp_granularities`." }, "honoured": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per member the request carried whose honouring depends on the endpoint, whether it reached the engine. Each rail forwards its own core members under no declaration at all, and forwards everything else only where the serving endpoint names it in `supported_parameters`; `true` is that promise rather than a claim about what the engine did with the member. A member the request did not carry is absent rather than false, and a request carrying none of them has no `honoured` object at all. A streamed reply states the same verdict on the final frame, the one carrying `usage`: the headers are flushed before any endpoint has answered, so the frame that closes the accounting is the first point at which the endpoint that served the request is known. A stream that ended before the marketplace could close its accounting carries neither the usage frame nor the verdict." }, "usage": { "$ref": "#/components/schemas/TranscriptionUsage" } } }, "ImageProviderOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Provider-specific passthrough keyed by provider slug. Only the key matching the endpoint actually serving the request is read; the rest are ignored." }, "ImageProviderPreferences": { "type": "object", "properties": { "order": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "allow_fallbacks": { "type": "boolean" }, "only": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "ignore": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1 } }, "sort": { "oneOf": [ { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, { "$ref": "#/components/schemas/ImageProviderSortConfig" } ], "description": "Sorting strategy, applied when order is not given." }, "options": { "$ref": "#/components/schemas/ImageProviderOptions" } }, "description": "Routing preferences for an image request: a narrower set than chat carries, with per-provider passthrough options in their place." }, "ImageProviderSortConfig": { "type": "object", "required": [ "by" ], "properties": { "by": { "type": "string", "enum": [ "price", "throughput", "latency", "exacto" ] }, "partition": { "type": "string", "enum": [ "model", "none" ] } } }, "ImageRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "prompt" ], "description": "The reference Image API request body, parsed by POST /images.", "properties": { "model": { "type": "string", "minLength": 1, "description": "The image model to use." }, "prompt": { "type": "string", "minLength": 1, "description": "What to draw." }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Upper bound on images returned; an endpoint may return fewer." }, "resolution": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ], "description": "Resolution tier, resolved against the endpoint's envelope into the pixels it draws." }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "1:2", "1:4", "1:8", "2:1", "2:3", "2.35:1", "3:2", "3:4", "4:1", "4:3", "4:5", "5:2", "5:4", "8:1", "9:16", "16:9", "9:19.5", "19.5:9", "9:20", "20:9", "9:21", "21:9", "auto" ], "description": "Aspect ratio, snapped to the endpoint's own grid at the resolution tier." }, "size": { "type": "string", "description": "A tier or explicit WIDTHxHEIGHT pixels; pixels named beside a tier or a ratio are refused with 400." }, "quality": { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max" ], "description": "Rendering quality. Ignored by an endpoint with no such knob." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp", "svg" ], "description": "Encoding of the returned bytes. svg is vectorized markup, UTF-8 base64-encoded in b64_json." }, "background": { "type": "string", "enum": [ "auto", "transparent", "opaque" ], "description": "transparent requires an output_format carrying alpha (png or webp)." }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression for webp/jpeg output. Ignored for png." }, "seed": { "type": "integer", "description": "Ask for a reproducible render, where the provider supports it." }, "stream": { "type": "boolean", "description": "Relay the render as it is drawn, where the endpoint declares stream; the rest answer with the completed image alone." }, "input_references": { "type": "array", "maxItems": 16, "items": { "$ref": "#/components/schemas/ImageInputReference" }, "description": "Bounded inline image references. An https: URL parses here and is refused before dispatch: the marketplace fetches nothing on a caller's behalf." }, "provider": { "$ref": "#/components/schemas/ImageProviderPreferences", "description": "Routing preferences, plus per-provider passthrough under options keyed by provider slug." }, "user": { "type": "string", "maxLength": 256, "description": "An opaque end-user identifier, folded into a hashed id before it reaches a provider." } } }, "ImageInputReference": { "type": "object", "additionalProperties": false, "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "An inline base64 data URI, in one of the media types the endpoint declares for that kind. The marketplace fetches nothing on a caller’s behalf, so the bytes ride in the request rather than behind a URL." } } }, "role": { "type": [ "string", "null" ], "enum": [ "reference", "canny", "depth", "normal", "openpose", "segmentation", "edges", "pose", "seg", null ], "description": "What this item is for, `reference` when it is omitted or null. `reference`: Conditioning the engine applies however it applies that kind: an image to edit or keep the look of, a clip to follow, a voice to clone. `canny`: An edge map in the Canny convention, white lines on black, that the render keeps the silhouettes of. `depth`: A depth pass, near bright and far dark, that the render keeps the geometry of. `normal`: A surface-normal pass, XYZ as RGB, that the render keeps the surface orientation of. `openpose`: A skeleton render in the OpenPose colour convention that the figures in the render take the stance of. `segmentation`: A flat-colour label pass, one colour per object, that the render keeps the layout of. `edges` is read as `canny`, `pose` is read as `openpose`, `seg` is read as `segmentation`. Only the roles the endpoint lists under `reference_inputs` are accepted; any other is refused before inference, naming the ones that are." } } }, "GeneratedImageData": { "type": "object", "required": [ "b64_json" ], "properties": { "b64_json": { "type": "string", "description": "The image, base64-encoded." }, "media_type": { "type": "string", "description": "MIME type of the image, such as image/png. Shape is read from what arrived rather than restated beside it, so there is no per-image size member." } } }, "ImageReply": { "type": "object", "required": [ "created", "data" ], "description": "The reference reply body. No id, model or provider member: those travel on X-Generation-Id and X-Provider-Name instead.", "properties": { "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedImageData" } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ImagePartialImageEvent": { "type": "object", "required": [ "type", "partial_image_index", "b64_json" ], "properties": { "type": { "type": "string", "enum": [ "image_generation.partial_image" ] }, "partial_image_index": { "type": "integer", "minimum": 0 }, "b64_json": { "type": "string" } } }, "ImageTextChunkEvent": { "type": "object", "required": [ "type", "text", "phase" ], "description": "Text-based formats (svg) stream markup fragments alongside, or instead of, partial images.", "properties": { "type": { "type": "string", "enum": [ "image_generation.text_chunk" ] }, "text": { "type": "string" }, "phase": { "type": "string", "enum": [ "content", "reasoning", "draft" ], "description": "content is renderable output; reasoning and draft are intermediate provider phases." } } }, "ImageCompletedEvent": { "type": "object", "required": [ "type", "b64_json", "created" ], "properties": { "type": { "type": "string", "enum": [ "image_generation.completed" ] }, "b64_json": { "type": "string" }, "created": { "type": "integer" }, "media_type": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ImageStreamErrorEvent": { "type": "object", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "param": { "type": [ "string", "null" ] } } } } }, "ImageStreamEvent": { "oneOf": [ { "$ref": "#/components/schemas/ImagePartialImageEvent" }, { "$ref": "#/components/schemas/ImageTextChunkEvent" }, { "$ref": "#/components/schemas/ImageCompletedEvent" }, { "$ref": "#/components/schemas/ImageStreamErrorEvent" } ], "description": "The whole `data:` payload of one stream frame — nothing wraps it. The stream ends on a literal `[DONE]` line rather than the connection closing." }, "ImageEnumCapability": { "type": "object", "required": [ "type", "values" ], "properties": { "type": { "type": "string", "enum": [ "enum" ] }, "values": { "type": "array", "items": { "type": "string" } } } }, "ImageRangeCapability": { "type": "object", "required": [ "type", "min", "max" ], "properties": { "type": { "type": "string", "enum": [ "range" ] }, "min": { "type": "number" }, "max": { "type": "number" } } }, "ImageBooleanCapability": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "boolean" ] } } }, "ImageCapabilityDescriptor": { "oneOf": [ { "$ref": "#/components/schemas/ImageEnumCapability" }, { "$ref": "#/components/schemas/ImageRangeCapability" }, { "$ref": "#/components/schemas/ImageBooleanCapability" } ], "description": "A typed descriptor for one supported request parameter: an enum names its discrete values, a range its inclusive numeric span, a boolean that it is merely accepted." }, "ImageSupportedParameters": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ImageCapabilityDescriptor" }, "description": "The listed model carries the union across its endpoints, a coarse discovery aid; the endpoints listing carries each endpoint's own definitive set." }, "ImageModelArchitecture": { "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", "video", "speech", "transcription", "embeddings", "rerank", "decisions", "audio", "mesh" ] } } } }, "ImageModelListItem": { "type": "object", "required": [ "id", "name", "description", "created", "architecture", "supported_parameters", "supports_streaming", "endpoints" ], "description": "One entry on GET /images/models: every model with at least one live image endpoint.", "properties": { "id": { "type": "string", "description": "author/slug." }, "name": { "type": "string" }, "description": { "type": "string" }, "created": { "type": "integer", "description": "Unix timestamp, in seconds." }, "architecture": { "$ref": "#/components/schemas/ImageModelArchitecture" }, "supported_parameters": { "$ref": "#/components/schemas/ImageSupportedParameters" }, "parameter_offers": { "type": "array", "description": "Exact typed parameter domains offered by live sellers, grouped by output modality. The legacy supported_parameters map describes only standard image controls.", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "supports_streaming": { "type": "boolean", "description": "Whether any endpoint streams natively." }, "endpoints": { "type": "string", "description": "Relative URL to this model's endpoints listing." } } }, "ImageModelsListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageModelListItem" } } } }, "PricingPredicate": { "description": "A declared pricing condition or recursive composition. Parsing is bounded to 32 levels and 1024 JSON nodes.", "oneOf": [ { "type": "object", "required": [ "allOf" ], "additionalProperties": false, "properties": { "allOf": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingPredicate" } } } }, { "type": "object", "required": [ "anyOf" ], "additionalProperties": false, "properties": { "anyOf": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingPredicate" } } } }, { "type": "object", "required": [ "not" ], "additionalProperties": false, "properties": { "not": { "$ref": "#/components/schemas/PricingPredicate" } } }, { "type": "object", "minProperties": 1, "additionalProperties": { "oneOf": [ { "type": "object", "required": [ "equals" ], "additionalProperties": false, "properties": { "equals": { "type": [ "string", "number", "boolean" ] } } }, { "type": "object", "required": [ "gte" ], "additionalProperties": false, "properties": { "gte": { "type": "number" } } }, { "type": "object", "required": [ "lte" ], "additionalProperties": false, "properties": { "lte": { "type": "number" } } }, { "type": "object", "required": [ "min_items" ], "additionalProperties": false, "properties": { "min_items": { "type": "integer", "minimum": 0, "maximum": 2147483647 } } } ] } } ] }, "ImagePricingEntry": { "type": "object", "required": [ "billable", "unit", "cost_usd" ], "description": "One billable pricing line. cost_usd is a number, as the reference declares it: the marketplace holds the figure as ExactUsd and formats it to this number only at the wire boundary.", "properties": { "billable": { "type": "string", "enum": [ "output_image", "input_image", "input_font", "input_reference", "input_text" ] }, "unit": { "type": "string", "enum": [ "request", "image", "megapixel", "token" ] }, "cost_usd": { "type": "number" }, "sku_type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Declared pricing type. Heimdallm extension." }, "pricing_scope": { "type": "string", "enum": [ "input", "output", "request" ], "description": "Declared pricing scope. Heimdallm extension." }, "variant": { "type": "string", "description": "Distinguishes qualified lines sharing a billable and unit." }, "overrides": { "type": "array", "maxItems": 1024, "description": "Heimdallm extension: ordered declared overrides. The last matching condition selects the rate.", "items": { "type": "object", "required": [ "when", "cost_usd" ], "additionalProperties": false, "properties": { "when": { "$ref": "#/components/schemas/PricingPredicate" }, "cost_usd": { "type": "number", "minimum": 0 } } } }, "utc_start": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "UTC HHMM start with a valid minute component. Heimdallm extension." }, "utc_end": { "type": "integer", "minimum": 0, "maximum": 2359, "description": "UTC HHMM end with a valid minute component. Heimdallm extension." }, "utc_days": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "description": "Applicable UTC weekdays. Heimdallm extension." }, "ttl_seconds": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Qualified cache lifetime. Heimdallm extension." }, "implicit": { "type": "boolean", "description": "Whether the qualified cache entry is implicit. Heimdallm extension." } } }, "ImageEndpoint": { "type": "object", "required": [ "discount", "provider_name", "provider_slug", "provider_id", "provider_tag", "supported_parameters", "allowed_passthrough_parameters", "supports_streaming", "pricing" ], "description": "One endpoint on GET /images/models/{author}/{slug}/endpoints.", "properties": { "discount": { "type": "number", "exclusiveMaximum": 1, "description": "Heimdallm extension: the fraction taken off this endpoint's list rates to reach the lines below, so a list rate is cost_usd / (1 - discount). Always present: 0 where nothing is taken off, and negative where the endpoint charges above its list. The fraction sits beside the prices: inside pricing where it is an object, on the endpoint where it is an array of lines." }, "provider_name": { "type": "string" }, "provider_slug": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid", "description": "The provider's primary key. It holds when the provider's slug is changed." }, "provider_tag": { "type": [ "string", "null" ], "description": "The tag a provider.only/ignore/order entry names, or null." }, "supported_parameters": { "$ref": "#/components/schemas/ImageSupportedParameters" }, "render_parameters": { "type": "object", "description": "Exact typed parameter domains this endpoint declares, grouped by output modality. Any new parameter name is included when its provider declares it.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "allowed_passthrough_parameters": { "type": "array", "items": { "type": "string" }, "description": "Provider-specific keys accepted under provider.options[provider_slug]." }, "supports_streaming": { "type": "boolean" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/ImagePricingEntry" } } } }, "ImageModelEndpointsResponse": { "type": "object", "required": [ "id", "endpoints" ], "properties": { "id": { "type": "string" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ImageEndpoint" } } } } } } }