{ "openapi": "3.1.0", "info": { "title": "Instachat brain API", "version": "1.0.0", "summary": "OpenAI-compatible models, chat, responses, audio, search, media jobs and usage.", "description": "The customer-facing HTTP surface of the Instachat brain. Authenticate with `Authorization: Bearer `. Customer API keys (`ak_…`) are early access and issued on request, not self-serve: to obtain access, contact Instachat. Where issued, an API key acts as the account that created it, is metered and billed as that account, and opens only the operations in this document other than the API keys operations. Generated from `apps/services/brain/src/openapi/routes.ts`; do not edit by hand." }, "servers": [ { "url": "https://brain.intch.cc" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "tags": [ { "name": "Models", "description": "The model catalog this account may call." }, { "name": "Chat", "description": "OpenAI-compatible Chat Completions." }, { "name": "Responses", "description": "OpenAI-compatible Responses API." }, { "name": "Audio", "description": "OpenAI-compatible speech-to-text and text-to-speech." }, { "name": "Search", "description": "Quota-bound web search." }, { "name": "Media jobs", "description": "Asynchronous image, voice and video generation: create, then poll." }, { "name": "Usage", "description": "Plan meters and prepaid credit balance for the calling account." }, { "name": "API keys", "description": "Create, list and revoke `ak_` keys for the calling account (account token only)." } ], "paths": { "/api/billing/balance": { "get": { "operationId": "getBalance", "tags": [ "Usage" ], "summary": "Prepaid credit balance and this month's usage", "description": "Fail-closed: an unreadable ledger is a 503, never a zero balance.", "responses": { "200": { "description": "Balance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "balanceUsd", "balanceMicroUsd", "month", "minTopupUsd", "topupAmounts" ], "properties": { "userId": { "type": "string" }, "balanceUsd": { "type": "number" }, "balanceMicroUsd": { "type": "integer" }, "month": { "type": "object", "properties": { "messages": { "type": "integer" }, "tokensIn": { "type": "integer" }, "tokensOut": { "type": "integer" }, "costUsd": { "type": "number" }, "measured": { "type": "boolean", "description": "false = the usage counters could not be read; the zeros are not figures" } } }, "minTopupUsd": { "type": "number" }, "topupAmounts": { "type": "array", "items": { "type": "number" } } } } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Ledger unavailable (`ledger_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlainError" } } } } } } }, "/api/billing/usage": { "get": { "operationId": "getUsage", "tags": [ "Usage" ], "summary": "Plan and usage meters for the calling account", "description": "Caller-scoped: an account token always reads its own meters. Informational; an unreadable counter reads as 0 used.", "responses": { "200": { "description": "Usage meters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "plan", "yang", "twinMinutes", "cliPlan", "daily" ], "properties": { "userId": { "type": "string" }, "plan": { "type": "string" }, "yang": { "$ref": "#/components/schemas/Meter" }, "twinMinutes": { "$ref": "#/components/schemas/Meter" }, "cliPlan": { "type": [ "string", "null" ] }, "daily": { "type": [ "object", "null" ], "description": "Daily fair-use meter, present for CLI plan subscribers.", "properties": { "usedUsd": { "type": "number" }, "ceilingUsd": { "type": "number" } } } } } } } }, "401": { "description": "Missing or invalid bearer token, or an unknown account.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OpenAIError" }, { "$ref": "#/components/schemas/PlainError" } ] } } } } } } }, "/api/keys": { "get": { "operationId": "listApiKeys", "tags": [ "API keys" ], "summary": "List the account's API keys", "description": "Prefix, name, creation and last-use time of every live key on the calling account. The key itself is never returned. `last_used_at` is updated at most once a minute.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The keys, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "401": { "description": "Missing or invalid account token (`account_token_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "Called with an API key (`api_key_not_allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Key storage unavailable (`store_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } }, "post": { "operationId": "createApiKey", "tags": [ "API keys" ], "summary": "Create an API key", "description": "Mints an `ak_` key for the calling account. The full key is in this response ONLY: it is stored as a hash and can never be shown again. Requires the account token; an API key cannot create keys. At most 10 creates per hour and 20 live keys per account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A label for the key (one line)." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "The new key. Store `key` now; it is not retrievable later.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "pattern": "^ak_[A-Za-z0-9_-]{43}$" } } } ] } } } }, "400": { "description": "Invalid JSON or name (`invalid_json`, `invalid_name`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Missing or invalid account token (`account_token_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "Called with an API key (`api_key_not_allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "409": { "description": "The account already holds the maximum number of keys (`key_limit`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Too many keys created this hour (`rate_limit_exceeded`).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Key storage unavailable (`store_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/api/keys/{id}": { "delete": { "operationId": "revokeApiKey", "tags": [ "API keys" ], "summary": "Revoke an API key", "description": "Immediate: the next request with the revoked key is refused with 401 `invalid_api_key`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The key's `id` from the list.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revoked" ], "properties": { "id": { "type": "string" }, "revoked": { "const": true } } } } } }, "401": { "description": "Missing or invalid account token (`account_token_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "Called with an API key (`api_key_not_allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "404": { "description": "No such key on this account (`key_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Key storage unavailable (`store_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/audio/speech": { "post": { "operationId": "createSpeech", "tags": [ "Audio" ], "summary": "Synthesize speech (OpenAI-compatible)", "description": "Returns audio bytes. Input at most 2000 characters. Rate limited to 30 requests per minute per account. `wav` and `pcm` may stream (`stream: true`, chunked transfer); `ogg` (default) and `m4a` are returned whole.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "maxLength": 2000 }, "voice": { "type": "string", "description": "Optional voice name." }, "response_format": { "type": "string", "enum": [ "ogg", "wav", "pcm", "m4a" ], "default": "ogg", "description": "`wave`, `pcm16`, `mp4` and `aac` are accepted as aliases; anything else falls back to `ogg`." }, "language": { "type": "string", "description": "BCP-47 or two-letter hint for Latin-script languages." }, "stream": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Synthesized audio.", "content": { "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Missing, invalid or too long `input`, or an invalid option.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/audio/transcriptions": { "post": { "operationId": "createTranscription", "tags": [ "Audio" ], "summary": "Transcribe audio (OpenAI-compatible)", "description": "Multipart upload, at most 10 MB. Rate limited to 30 requests per minute per account.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The audio file (the field name `audio` is also accepted)." }, "language": { "type": "string", "description": "Optional language hint." } } } } } }, "responses": { "200": { "description": "Transcript.", "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } }, "400": { "description": "Not multipart, `file` missing, or file too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "500": { "description": "Transcription failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/chat/completions": { "post": { "operationId": "createChatCompletion", "tags": [ "Chat" ], "summary": "Create a chat completion (OpenAI-compatible)", "description": "Drop-in for the OpenAI Chat Completions API. `stream: true` returns Server-Sent Events (`data: {chunk}` lines, terminated by `data: [DONE]`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "A completion, or an SSE stream when `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE frames of chat.completion.chunk objects, then `data: [DONE]`." } } } }, "400": { "description": "Invalid JSON, empty `messages`, or a model this account may not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "402": { "description": "Prepaid credit balance exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "The account is not approved for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Rate limit or quota reached.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Temporarily unavailable (including a server restart in progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/images": { "post": { "operationId": "createImageJob", "tags": [ "Media jobs" ], "summary": "Start an asynchronous image job", "description": "Per-account entitlement required; off unless enabled for the account. Body at most 20 KiB; unknown fields are rejected.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Must equal `request_id` in the body. Replaying the same key with the same body returns the existing job.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJobCreate" } } } }, "responses": { "200": { "description": "Replay of a job that already reached a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJob" } } } }, "202": { "description": "Accepted; poll the GET endpoint with the same `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJob" } } } }, "400": { "description": "Invalid request body, or `Idempotency-Key` does not equal `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to image generation, or it is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "409": { "description": "The same `request_id` was already used with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "429": { "description": "A per-account limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "503": { "description": "The generation provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } }, "/v1/images/{request_id}": { "get": { "operationId": "getImageJob", "tags": [ "Media jobs" ], "summary": "Poll a image job", "description": "Owner-scoped: another account's job and an absent job are the same 404. Polling never reserves budget.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The job's `request_id` (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageJob" } } } }, "400": { "description": "`request_id` is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to image generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "404": { "description": "No such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "List the models this account may call", "description": "OpenAI-compatible model list. Managed accounts see only the `yin` / `yang` aliases with capability metadata; other accounts see the aliases followed by the full catalog.", "responses": { "200": { "description": "Model list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/responses": { "post": { "operationId": "createResponse", "tags": [ "Responses" ], "summary": "Create a model response (OpenAI Responses API)", "description": "Responses API facade over the same managed models as chat completions. Supported: string or item-array `input`, `instructions`, function `tools`, `tool_choice`, `previous_response_id`, `store` (default true, kept 30 days), `stream` (semantic SSE events). Hosted tool types and `background: true` are rejected with 400. Any field outside the supported set is a 400 `unsupported_parameter`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRequest" } } } }, "responses": { "200": { "description": "A response object, or an SSE stream when `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } }, "text/event-stream": { "schema": { "type": "string", "description": "Semantic SSE events (`response.created`, `response.output_text.delta`, …, `response.completed`), each with a `sequence_number`." } } } }, "400": { "description": "Invalid body, unsupported parameter or tool type, or unknown `previous_response_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "402": { "description": "Prepaid credit balance exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "The account is not approved for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "429": { "description": "Rate limit or quota reached.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "502": { "description": "The upstream model call failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "503": { "description": "Temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/responses/{id}": { "delete": { "operationId": "deleteResponse", "tags": [ "Responses" ], "summary": "Delete a stored response", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "const": "response" }, "deleted": { "const": true } } } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "404": { "description": "No such response for this account (`response_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } }, "get": { "operationId": "getResponse", "tags": [ "Responses" ], "summary": "Retrieve a stored response", "description": "Only the account that created the response can read it; any other id is a 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored response object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "404": { "description": "No such response for this account (`response_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } } } } }, "/v1/search": { "post": { "operationId": "webSearch", "tags": [ "Search" ], "summary": "Web search", "description": "Quota-bound web search with server-held provider credentials: no model call, no memory. Each request is at most one upstream call; limits are per account over a 10-minute and a daily window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 400 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Bare hostnames." }, "blocked_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Bare hostnames." }, "freshness": { "type": "string", "enum": [ "auto", "none" ], "default": "auto" } } } } } }, "responses": { "200": { "description": "Results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "searched_at", "provider" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "title", "url", "snippet" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } }, "searched_at": { "type": "string", "format": "date-time" }, "provider": { "type": "string" } } } } } }, "400": { "description": "Invalid request (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIError" } } } }, "403": { "description": "Account not approved (`account_not_approved`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } }, "429": { "description": "Quota reached (`rate_limited`).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } }, "502": { "description": "Upstream error (`search_upstream_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } }, "503": { "description": "Search unavailable (`search_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } }, "504": { "description": "Upstream timeout (`search_timeout`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchError" } } } } } } }, "/v1/videos": { "post": { "operationId": "createVideoJob", "tags": [ "Media jobs" ], "summary": "Start an asynchronous video job", "description": "Per-account entitlement required; off unless enabled for the account. Unknown fields are rejected.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Must equal `request_id` in the body. Replaying the same key with the same body returns the existing job.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJobCreate" } } } }, "responses": { "200": { "description": "Replay of a job that already reached a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" } } } }, "202": { "description": "Accepted; poll the GET endpoint with the same `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" } } } }, "400": { "description": "Invalid request body, or `Idempotency-Key` does not equal `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to video generation, or it is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "409": { "description": "The same `request_id` was already used with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "429": { "description": "A per-account limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "503": { "description": "The generation provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } }, "/v1/videos/{request_id}": { "get": { "operationId": "getVideoJob", "tags": [ "Media jobs" ], "summary": "Poll a video job", "description": "Owner-scoped: another account's job and an absent job are the same 404. Polling never reserves budget.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The job's `request_id` (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" } } } }, "400": { "description": "`request_id` is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to video generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "404": { "description": "No such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } }, "/v1/voices": { "post": { "operationId": "createVoiceJob", "tags": [ "Media jobs" ], "summary": "Start an asynchronous voice job", "description": "Per-account entitlement required; off unless enabled for the account. Unknown fields are rejected.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Must equal `request_id` in the body. Replaying the same key with the same body returns the existing job.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceJobCreate" } } } }, "responses": { "200": { "description": "Replay of a job that already reached a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceJob" } } } }, "202": { "description": "Accepted; poll the GET endpoint with the same `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceJob" } } } }, "400": { "description": "Invalid request body, or `Idempotency-Key` does not equal `request_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to voice generation, or it is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "409": { "description": "The same `request_id` was already used with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "429": { "description": "A per-account limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "503": { "description": "The generation provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } }, "/v1/voices/{request_id}": { "get": { "operationId": "getVoiceJob", "tags": [ "Media jobs" ], "summary": "Poll a voice job", "description": "Owner-scoped: another account's job and an absent job are the same 404. Polling never reserves budget.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The job's `request_id` (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceJob" } } } }, "400": { "description": "`request_id` is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "401": { "description": "Missing or invalid account token (`invalid_session`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "403": { "description": "The account is not entitled to voice generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "404": { "description": "No such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } }, "410": { "description": "The job's retrieval window has ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Account token." }, "apiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ak_…", "description": "A customer API key (`ak_…`). Early access, issued on request, not self-serve. Acts as, and is billed to, the account it belongs to." } }, "schemas": { "OpenAIError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] } } } } }, "SearchError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } }, "MediaError": { "type": "object", "required": [ "error", "code", "message" ], "description": "`error` and `code` carry the same token; match on it, never on `message`.", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "prefix", "created_at", "last_used_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "The first characters of the key, to tell keys apart." }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PlainError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Meter": { "type": "object", "required": [ "used", "limit" ], "properties": { "used": { "type": "number" }, "limit": { "type": [ "number", "null" ], "description": "null = unlimited." } } }, "Model": { "type": "object", "required": [ "id", "object", "owned_by" ], "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "created": { "type": "integer" }, "owned_by": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "context_window": { "type": "integer" }, "max_output_tokens": { "type": [ "integer", "null" ] }, "capabilities": { "type": "object", "properties": { "tools": { "type": "boolean" }, "images": { "type": "boolean" }, "reasoning": { "type": "boolean" } } } } }, "ModelList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "ChatMessage": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "description": "A string, or an array of OpenAI content parts (`text`, `image_url`).", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } }, { "type": "null" } ] }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object" } }, "tool_call_id": { "type": "string" } } }, "ChatCompletionRequest": { "type": "object", "required": [ "messages" ], "properties": { "model": { "type": "string", "description": "A model id from GET /v1/models (`yin` / `yang` for managed accounts)." }, "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatMessage" } }, "stream": { "type": "boolean", "default": false }, "tools": { "type": "array", "items": { "type": "object" }, "description": "OpenAI function tools." }, "tool_choice": {}, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "ChatCompletion": { "type": "object", "required": [ "id", "object", "choices" ], "properties": { "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "ResponseRequest": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "instructions": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Function tools only." }, "tool_choice": {}, "parallel_tool_calls": { "type": "boolean" }, "previous_response_id": { "type": "string" }, "store": { "type": "boolean", "default": true }, "stream": { "type": "boolean", "default": false }, "background": { "type": "boolean", "description": "Only `false` is supported." }, "max_output_tokens": { "type": "integer" }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "reasoning": { "type": "object" }, "metadata": { "type": "object" } } }, "Response": { "type": "object", "required": [ "id", "object", "status" ], "properties": { "id": { "type": "string" }, "object": { "const": "response" }, "created_at": { "type": "integer" }, "status": { "type": "string", "enum": [ "completed", "incomplete" ] }, "model": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "output": { "type": "array", "items": { "type": "object" }, "description": "OpenAI output items (`message`, `function_call`)." }, "previous_response_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object" }, "usage": { "type": "object" } } }, "ImageJobCreate": { "type": "object", "additionalProperties": false, "required": [ "request_id", "session_id", "prompt", "aspect_ratio" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-chosen idempotency id; must equal the `Idempotency-Key` header." }, "session_id": { "type": "string", "format": "uuid", "description": "Client conversation id the job belongs to." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "aspect_ratio": { "const": "1:1" } } }, "ImageJob": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "refused", "lost-in-restart" ] }, "image": { "type": "object", "description": "The generated image (present on `succeeded`)." }, "usage": { "type": "object", "description": "Present on `succeeded`." }, "failure": { "$ref": "#/components/schemas/MediaError", "description": "Present on `failed`, `refused` and `lost-in-restart`." } } }, "VoiceJobCreate": { "type": "object", "additionalProperties": false, "required": [ "request_id", "session_id", "text" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-chosen idempotency id; must equal the `Idempotency-Key` header." }, "session_id": { "type": "string", "format": "uuid", "description": "Client conversation id the job belongs to." }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "VoiceJob": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "refused", "lost-in-restart" ] }, "voice": { "type": "object", "description": "The generated audio (present on `succeeded`)." }, "usage": { "type": "object", "description": "Present on `succeeded`." }, "failure": { "$ref": "#/components/schemas/MediaError", "description": "Present on `failed`, `refused` and `lost-in-restart`." } } }, "VideoJobCreate": { "type": "object", "additionalProperties": false, "required": [ "request_id", "session_id", "prompt" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-chosen idempotency id; must equal the `Idempotency-Key` header." }, "session_id": { "type": "string", "format": "uuid", "description": "Client conversation id the job belongs to." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9" }, "duration": { "type": "integer", "minimum": 1, "maximum": 15, "default": 5, "description": "Seconds. With `image`, only 5 or 10." }, "image": { "type": "string", "description": "Optional relative path of an image in the account's workspace to animate." } } }, "VideoJob": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "refused", "lost-in-restart" ] }, "video": { "type": "object", "description": "The generated video, labelled AI-generated (present on `succeeded`)." }, "usage": { "type": "object", "description": "Present on `succeeded`." }, "failure": { "$ref": "#/components/schemas/MediaError", "description": "Present on `failed`, `refused` and `lost-in-restart`." } } } } } }