{ "openapi": "3.1.0", "info": { "title": "NagaAI API", "description": "NagaAI routes inference requests to a pool of upstream providers behind one endpoint. Requests speak the OpenAI or the Anthropic dialect, and the gateway selects a provider that serves the requested model. Two credentials exist and they are not interchangeable. An API key reaches models. A provisioning key manages the account: its keys, its balance, and its usage. Each operation declares which one it accepts. NagaAI charges the account in credits for the tokens a request consumes, at the published price of the model that served it. One credit costs one US dollar.", "termsOfService": "https://naga.ac/legal/terms", "contact": { "name": "NagaAI", "url": "https://naga.ac" }, "version": "2026-03-31", "summary": "One API to many model providers, in the OpenAI and Anthropic request formats." }, "servers": [ { "url": "https://api.naga.ac", "description": "Production" }, { "url": "http://localhost:8500", "description": "Local development" } ], "paths": { "/v1/account/activity": { "get": { "tags": [ "Account" ], "summary": "Get account activity", "description": "Returns the account's usage over a recent window, aggregated four ways. Requires a provisioning key.", "operationId": "get_account_activity", "parameters": [ { "name": "days", "in": "query", "description": "How many days back the report reaches, from 1 to 30; anything else draws a 400.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 30, "minimum": 0 } } ], "responses": { "200": { "description": "The usage report for the requested window: the per-day rows, the totals, and the breakdowns by model and by API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" }, "examples": { "basic": { "summary": "Thirty days of usage", "value": { "period_days": 30, "total_stats": { "total_requests": 1284, "total_cost": "3.7412", "total_input_tokens": 481233, "total_output_tokens": 92014 }, "daily_stats": [ { "date": "2026-08-23", "total_requests": 58, "total_cost": "0.1642", "total_input_tokens": 21044, "total_output_tokens": 4103 } ], "top_models": [ { "model_name": "gpt-4o-mini", "request_count": 902, "total_cost": "1.8120", "total_input_tokens": 301122, "total_output_tokens": 60553 } ], "api_key_usage": [ { "api_key_id": 42, "api_key_name": "production", "request_count": 1284, "total_cost": "3.7412", "total_input_tokens": 481233, "total_output_tokens": 92014 } ] } } } } }, "x-retry-safe": false }, "400": { "description": "`days` is outside the range this route accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/activity?days=30 \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\"" } ], "x-mcp": { "name": "naga_get_account_activity", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } } }, "/v1/account/balance": { "get": { "tags": [ "Account" ], "summary": "Get the account balance", "description": "Returns the account's credit balance. Requires a provisioning key.", "operationId": "get_account_balance", "responses": { "200": { "description": "The account's credit balance, as a decimal string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" }, "examples": { "basic": { "summary": "The balance, as a decimal string", "value": { "balance": "12.4750" } } } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/balance \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\"" } ], "x-mcp": { "name": "naga_get_account_balance", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } } }, "/v1/account/keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "Returns every API key on the account, disabled and expired ones included. Requires a provisioning key.", "operationId": "list_api_keys", "responses": { "200": { "description": "The account's API keys, newest first. No secret is among the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" }, "examples": { "basic": { "summary": "One key", "value": { "keys": [ { "id": 42, "name": "production", "created_at": "2026-08-01T09:14:22", "expires_at": null, "is_enabled": true, "credit_limit": 25.0, "default_routing_strategy": null } ] } } } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/keys \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\"" } ], "x-mcp": { "name": "naga_list_api_keys", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } }, "post": { "tags": [ "API Keys" ], "summary": "Create an API key", "description": "Creates an API key on the account and returns its secret this once. Requires a provisioning key.", "operationId": "create_api_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" }, "examples": { "basic": { "summary": "A key with a spending cap", "value": { "name": "production", "credit_limit": 25.0, "expires_at": "2027-01-01T00:00:00Z" } } } } }, "required": true }, "responses": { "200": { "description": "The freshly minted key, and the one answer carrying the secret itself.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" }, "examples": { "basic": { "summary": "The only answer carrying the secret itself", "value": { "id": 42, "name": "production", "key": "ng-xxxxxxxxxxxxxxxxxxxxxxxxxxxx", "created_at": "2026-08-01T09:14:22", "expires_at": "2027-01-01T00:00:00", "is_enabled": true, "credit_limit": 25.0, "default_routing_strategy": null, "message": "Store this key now — it is not shown again." } } } } }, "x-retry-safe": false }, "400": { "description": "The body is not valid JSON, or a field failed its constraint. The message names every field that failed, joined with `; `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/keys \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"production\",\n \"credit_limit\": 25.0,\n \"expires_at\": \"2027-01-01T00:00:00Z\"\n}'" } ], "x-mcp": { "name": "naga_create_api_key", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false } } } }, "/v1/account/keys/{key_id}": { "get": { "tags": [ "API Keys" ], "summary": "Get an API key", "description": "Returns one API key of the account, without its secret. Requires a provisioning key.", "operationId": "get_api_key", "parameters": [ { "name": "key_id", "in": "path", "description": "The key's `id`, as the listing reports it.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The key, without its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "basic": { "summary": "One key, without its secret", "value": { "id": 42, "name": "production", "created_at": "2026-08-01T09:14:22", "expires_at": null, "is_enabled": true, "credit_limit": 25.0, "default_routing_strategy": null } } } } }, "x-retry-safe": false }, "400": { "description": "No key with this id belongs to the account — and that is a 400 here, not a 404. A deleted id and another account's id answer the same way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/keys/42 \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\"" } ], "x-mcp": { "name": "naga_get_api_key", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } }, "delete": { "tags": [ "API Keys" ], "summary": "Delete an API key", "description": "Deletes one API key of the account, immediately and past undoing. Requires a provisioning key.", "operationId": "delete_api_key", "parameters": [ { "name": "key_id", "in": "path", "description": "The key's `id`, as the listing reports it.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "The key is gone. The answer carries no body at all.", "x-retry-safe": false }, "400": { "description": "No key with this id belongs to the account — and that is a 400 here, not a 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/keys/42 \\\n -X DELETE \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\"" } ], "x-mcp": { "name": "naga_delete_api_key", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } } }, "patch": { "tags": [ "API Keys" ], "summary": "Update an API key", "description": "Updates one API key of the account in place, changing only the fields sent. Requires a provisioning key.", "operationId": "update_api_key", "parameters": [ { "name": "key_id", "in": "path", "description": "The key's `id`, as the listing reports it.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" }, "examples": { "basic": { "summary": "Disable a key and rename it", "value": { "name": "production (rotated out)", "is_enabled": false } } } } }, "required": true }, "responses": { "200": { "description": "The key as it stands after the change, without its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "basic": { "summary": "The key as it stands after the change", "value": { "id": 42, "name": "production (rotated out)", "created_at": "2026-08-01T09:14:22", "expires_at": null, "is_enabled": false, "default_routing_strategy": "latency", "credit_limit": 25.0 } } } } }, "x-retry-safe": false }, "400": { "description": "No key with this id belongs to the account, the body is not valid JSON, or a field failed its constraint. This includes a `null` sent for a field that cannot be cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The provisioning key is missing, malformed, or belongs to no account. An ordinary API key fails here too: it reaches models, not the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-provisioning-key": { "summary": "401 — this route wants the provisioning key, not an inference key", "value": { "error": { "type": "invalid_request_error", "message": "Invalid provisioning key." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream provider could serve the request, or a store the gateway needs did not respond. `Retry-After`, when present, carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "provisioningBearerAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/account/keys/42 \\\n -X PATCH \\\n -H \"Authorization: Bearer $NAGA_PROVISIONING_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"production (rotated out)\",\n \"is_enabled\": false\n}'" } ], "x-mcp": { "name": "naga_update_api_key", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } } }, "/v1/audio/speech": { "post": { "tags": [ "Audio" ], "summary": "Create speech", "description": "Converts text into spoken audio and charges the account for what it counted. Requires an API key.", "operationId": "create_speech", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/audio", "description": "The OpenAI reference for these routes." }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechModel" }, "examples": { "basic": { "summary": "Read one sentence aloud", "value": { "model": "tts-1", "input": "Hello from NagaAI.", "voice": "alloy", "response_format": "mp3" } } } } }, "required": true }, "responses": { "200": { "description": "The synthesised audio itself, streamed as it is produced. `Content-Type` names the container `response_format` asked for, or `audio/mpeg` when the key was left out and the provider named none of its own.", "content": { "audio/mpeg": { "examples": { "speech": { "summary": "Spoken audio, mp3", "description": "The body is the audio file itself. Write it to disk or hand it to a player; there is no JSON around it.", "externalValue": "https://docs.naga.ac/examples/speech.mp3" } } }, "audio/opus": {}, "audio/aac": {}, "audio/flac": {}, "audio/wav": {}, "audio/pcm": {} }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/audio/speech \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"tts-1\",\n \"input\": \"Hello from NagaAI.\",\n \"voice\": \"alloy\",\n \"response_format\": \"mp3\"\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.audio.speech.create(\n model=\"tts-1\",\n input=\"Hello from NagaAI.\",\n voice=\"alloy\",\n response_format=\"mp3\",\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.audio.speech.create({\n model: \"tts-1\",\n input: \"Hello from NagaAI.\",\n voice: \"alloy\",\n response_format: \"mp3\",\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_speech", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/audio/transcriptions": { "post": { "tags": [ "Audio" ], "summary": "Create a transcription", "description": "Converts uploaded audio into text in the language that was spoken and charges the account for what it counted. Requires an API key. `/v1/audio/translations` answers in English instead.", "operationId": "create_transcription", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/audio", "description": "The OpenAI reference for these routes." }, "requestBody": { "description": "The audio to transcribe, as the part named `file`, beside the model to transcribe with and two optional hints.", "content": { "multipart/form-data": { "schema": { "type": "object", "description": "The `multipart/form-data` body of `POST /v1/audio/transcriptions` and of `POST /v1/audio/translations` — one audio upload and three text fields.", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "The model to transcribe or translate with, named by its id or alias." }, "file": { "type": "string", "description": "The audio file itself. The gateway converts the container where the provider needs another.", "contentMediaType": "application/octet-stream" }, "prompt": { "type": [ "string", "null" ], "description": "A free-form hint for the provider: names, jargon, expected style." }, "language": { "type": [ "string", "null" ], "description": "The language spoken in the audio, as a lower-case ISO 639-1 code. Any other shape draws a 400." } } }, "examples": { "basic": { "summary": "Transcribe one uploaded file", "value": { "model": "whisper-large-v3", "file": "audio.mp3" } } } } }, "required": true }, "responses": { "200": { "description": "The transcript, as one object with one key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioTextResponse" }, "examples": { "basic": { "summary": "What the model heard", "value": { "text": "Hello from NagaAI." } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -F 'model=whisper-large-v3' \\\n -F 'file=@audio.mp3'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.audio.transcriptions.create(\n model=\"whisper-large-v3\",\n file=open(\"audio.mp3\", \"rb\"),\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import fs from \"node:fs\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.audio.transcriptions.create({\n model: \"whisper-large-v3\",\n file: fs.createReadStream(\"audio.mp3\"),\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_transcription", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/audio/translations": { "post": { "tags": [ "Audio" ], "summary": "Create a translation", "description": "Converts uploaded audio into English text and charges the account for what it counted. Requires an API key. `/v1/audio/transcriptions` answers in the language that was spoken.", "operationId": "create_translation", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/audio", "description": "The OpenAI reference for these routes." }, "requestBody": { "description": "The audio to translate into English, as the part named `file`, beside the model to translate with and two optional hints.", "content": { "multipart/form-data": { "schema": { "type": "object", "description": "The `multipart/form-data` body of `POST /v1/audio/transcriptions` and of `POST /v1/audio/translations` — one audio upload and three text fields.", "required": [ "model", "file" ], "properties": { "model": { "type": "string", "description": "The model to transcribe or translate with, named by its id or alias." }, "file": { "type": "string", "description": "The audio file itself. The gateway converts the container where the provider needs another.", "contentMediaType": "application/octet-stream" }, "prompt": { "type": [ "string", "null" ], "description": "A free-form hint for the provider: names, jargon, expected style." }, "language": { "type": [ "string", "null" ], "description": "The language spoken in the audio, as a lower-case ISO 639-1 code. Any other shape draws a 400." } } }, "examples": { "basic": { "summary": "Translate one uploaded file into English", "value": { "model": "whisper-large-v3", "file": "bonjour.mp3" } } } } }, "required": true }, "responses": { "200": { "description": "The English translation, as one object with one key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioTextResponse" }, "examples": { "basic": { "summary": "The English of what the model heard", "value": { "text": "Hello, how are you?" } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/audio/translations \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -F 'model=whisper-large-v3' \\\n -F 'file=@bonjour.mp3'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.audio.translations.create(\n model=\"whisper-large-v3\",\n file=open(\"bonjour.mp3\", \"rb\"),\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import fs from \"node:fs\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.audio.translations.create({\n model: \"whisper-large-v3\",\n file: fs.createReadStream(\"bonjour.mp3\"),\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_translation", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/chat/completions": { "post": { "tags": [ "Chat Completions" ], "summary": "Create a chat completion", "description": "Creates a model response in the OpenAI Chat Completions dialect and charges the account for the tokens it used. Requires an API key. `/v1/responses` and `/v1/messages` serve the same models in the other two dialects.", "operationId": "create_chat_completion", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/chat", "description": "The OpenAI reference for this dialect." }, "parameters": [ { "name": "x-naga-routing-strategy", "in": "header", "description": "The routing strategy when the body names none. An unknown name is ignored. A NagaAI extension.", "required": false, "schema": { "$ref": "#/components/schemas/RoutingStrategyWire" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletions" }, "examples": { "basic": { "summary": "A plain completion", "value": { "model": "gpt-4o-mini", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Say hello in one word." } ] } }, "reasoning": { "summary": "Ask a reasoning model to think first", "value": { "model": "deepseek-r1", "messages": [ { "role": "user", "content": "What is 2+2?" } ], "reasoning_effort": "medium" } }, "streaming": { "summary": "Stream the answer, with a usage trailer", "value": { "model": "gpt-4o-mini", "messages": [ { "role": "user", "content": "Say hello in one word." } ], "stream": true, "stream_options": { "include_usage": true } } }, "tool-call": { "summary": "Offer the model a function to call", "value": { "model": "gpt-4o", "messages": [ { "role": "user", "content": "What's the weather in NYC?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } } ] } } } } }, "required": true }, "responses": { "200": { "description": "The completion. `application/json` carries one `chat.completion` object when `stream` is false; `text/event-stream` carries one `chat.completion.chunk` per event, then the `data: [DONE]` sentinel, when it is true.", "headers": { "x-naga-routing-strategy": { "schema": { "type": "string" }, "description": "The routing strategy NagaAI applied to this request." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionResponse" }, { "$ref": "#/components/schemas/ChatCompletionModel" } ], "description": "The completion. The gateway answers a request it does not forward with the second shape, which omits `logprobs` and `refusal`." }, "examples": { "basic": { "summary": "One `chat.completion` object", "value": { "id": "chatcmpl-6Zq1s8bF2wKcT4mN", "object": "chat.completion", "created": 1774000000, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello", "refusal": null }, "finish_reason": "stop", "logprobs": null } ], "usage": { "prompt_tokens": 18, "completion_tokens": 1, "total_tokens": 19, "prompt_tokens_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0 } } } }, "reasoning": { "summary": "The thinking arrives beside the answer", "value": { "id": "chatcmpl-7Bd0kR3nQyLpVs", "object": "chat.completion", "created": 1774000000, "model": "deepseek-r1", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "4", "refusal": null, "reasoning_content": "2 plus 2 equals 4", "reasoning_details": [ { "type": "reasoning.text", "index": 0, "id": "reasoning-text-0", "text": "2 plus 2 equals 4" } ] }, "finish_reason": "stop", "logprobs": null } ], "usage": { "prompt_tokens": 14, "completion_tokens": 9, "total_tokens": 23, "prompt_tokens_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 8 } } } }, "tool-call": { "summary": "The model asked for a function instead of answering", "value": { "id": "chatcmpl-5Nf2wXcH8tZrKm", "object": "chat.completion", "created": 1774000000, "model": "gpt-4o", "choices": [ { "index": 0, "message": { "role": "assistant", "content": null, "refusal": null, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"NYC\"}" } } ] }, "finish_reason": "tool_calls", "logprobs": null } ], "usage": { "prompt_tokens": 18, "completion_tokens": 1, "total_tokens": 19, "prompt_tokens_details": { "cached_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0 } } } } } }, "text/event-stream": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ChatChunk" }, { "$ref": "#/components/schemas/ChatCompletionChunkModel" }, { "$ref": "#/components/schemas/ChatErrorEnvelope" } ], "description": "One frame. The gateway answers a request it does not forward with the second shape, and replaces a frame with the third when the stream fails midway." }, "examples": { "basic": { "summary": "One `data:` line of a streamed answer", "value": { "id": "chatcmpl-6Zq1s8bF2wKcT4mN", "object": "chat.completion.chunk", "created": 1774000000, "model": "gpt-4o-mini", "choices": [ { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null, "logprobs": null } ] } }, "reasoning": { "summary": "A frame carrying reasoning, before any content", "value": { "id": "chatcmpl-7Bd0kR3nQyLpVs", "object": "chat.completion.chunk", "created": 1774000000, "model": "deepseek-r1", "choices": [ { "index": 0, "delta": { "reasoning_content": "2 plus 2", "reasoning_details": [ { "type": "reasoning.text", "index": 0, "id": "reasoning-text-0", "text": "2 plus 2" } ] }, "finish_reason": null, "logprobs": null } ] } }, "tool-call": { "summary": "A frame opening a tool call; arguments arrive in later frames", "value": { "id": "chatcmpl-5Nf2wXcH8tZrKm", "object": "chat.completion.chunk", "created": 1774000000, "model": "gpt-4o", "choices": [ { "index": 0, "delta": { "tool_calls": [ { "index": 0, "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "" } } ] }, "finish_reason": null, "logprobs": null } ] } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "404": { "description": "The upstream provider reports that the addressed resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/chat/completions \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-4o-mini\",\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Say hello in one word.\"\n }\n ]\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Say hello in one word.\"\n }\n ],\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.chat.completions.create({\n model: \"gpt-4o-mini\",\n messages: [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Say hello in one word.\"\n }\n ],\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_chat_completion", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/embeddings": { "post": { "tags": [ "Embeddings" ], "summary": "Create embeddings", "description": "Creates an embedding vector for the input and charges the account for the tokens it counted. Requires an API key.", "operationId": "create_embedding", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/embeddings", "description": "The OpenAI reference for this route." }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Embeddings" }, "examples": { "basic": { "summary": "Embed one string", "value": { "model": "text-embedding-3-small", "input": "The quick brown fox jumps over the lazy dog" } } } } }, "required": true }, "responses": { "200": { "description": "The vectors. `data` carries one row per input, each with its index; `usage` carries the token count behind the charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingsResponse" }, "examples": { "basic": { "summary": "One vector, floats by default", "value": { "object": "list", "model": "text-embedding-3-small", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0023124, -0.0091187, 0.0157021 ] } ], "usage": { "prompt_tokens": 9, "total_tokens": 9 } } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/embeddings \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"text-embedding-3-small\",\n \"input\": \"The quick brown fox jumps over the lazy dog\"\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.embeddings.create(\n model=\"text-embedding-3-small\",\n input=\"The quick brown fox jumps over the lazy dog\",\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.embeddings.create({\n model: \"text-embedding-3-small\",\n input: \"The quick brown fox jumps over the lazy dog\",\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_embedding", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/images/edits": { "post": { "tags": [ "Images" ], "summary": "Edit an image", "description": "Edits uploaded images against a text prompt and charges the account for what it counted. Requires an API key. `/v1/images/generations` draws from a prompt alone.", "operationId": "create_image_edit", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/images", "description": "The OpenAI reference for these routes." }, "requestBody": { "description": "The images to edit, one per part named `image`, beside the prompt to edit them against and the fields `POST /v1/images/generations` takes in JSON.", "content": { "multipart/form-data": { "schema": { "type": "object", "description": "The `multipart/form-data` body of `POST /v1/images/edits` — the images to edit, the prompt to edit them against, and the fields `POST /v1/images/generations` takes in JSON.", "required": [ "model", "prompt", "image" ], "properties": { "model": { "type": "string", "description": "The model to edit with, named by its id or alias." }, "prompt": { "type": "string", "description": "What to change, in words. One to 32000 characters." }, "image": { "type": "array", "items": { "type": "string", "description": "One uploaded image, as the bytes of the file itself.", "contentMediaType": "application/octet-stream" }, "description": "The images to edit, one per part named `image`; `image[]` merges into the same list." }, "background": { "type": [ "string", "null" ], "description": "The provider's background knob, passed through unchecked. A provider without one drops it." }, "mask": { "type": [ "string", "null" ], "description": "A single image whose transparent area marks what the model may repaint.", "contentMediaType": "application/octet-stream" }, "n": { "type": [ "integer", "null" ], "format": "int64", "description": "How many images to ask for. Absent means one; a value above what the model declares draws a refusal." }, "quality": { "type": [ "string", "null" ], "description": "The provider's quality knob, passed through unchecked. A provider without one drops it." }, "response_format": { "allOf": [ { "$ref": "#/components/schemas/ImageResponseFormat" } ], "description": "Whether each image comes back as a link (`url`) or as inline base64 (`b64_json`).", "default": "url" }, "size": { "type": [ "string", "null" ], "description": "The requested image size, written `{width}x{height}`; any other shape draws a refusal." } } }, "examples": { "basic": { "summary": "Edit one uploaded image", "value": { "model": "gpt-image-1", "prompt": "Put a red scarf on the fox", "image": [ "fox.png" ] } } } } }, "required": true }, "responses": { "200": { "description": "The edited images, in the same body `POST /v1/images/generations` answers with.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" }, "examples": { "basic": { "summary": "The edited image, as a link", "value": { "created": 1774000000, "data": [ { "url": "https://cdn.naga.ac/images/1d7e8b02.png" } ], "usage": { "input_tokens": 274, "output_tokens": 1024, "total_tokens": 1298 } } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/images/edits \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -F 'model=gpt-image-1' \\\n -F 'prompt=Put a red scarf on the fox' \\\n -F 'image=@fox.png'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.images.edit(\n model=\"gpt-image-1\",\n prompt=\"Put a red scarf on the fox\",\n image=[open(\"fox.png\", \"rb\")],\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import fs from \"node:fs\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.images.edit({\n model: \"gpt-image-1\",\n prompt: \"Put a red scarf on the fox\",\n image: [fs.createReadStream(\"fox.png\")],\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_image_edit", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "summary": "Create an image", "description": "Creates images from a text prompt and charges the account for what it counted. Requires an API key. `/v1/images/edits` changes images that were uploaded instead.", "operationId": "create_image", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/images", "description": "The OpenAI reference for these routes." }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesGenerationsRequest" }, "examples": { "basic": { "summary": "One image from a prompt", "value": { "model": "gpt-image-1", "prompt": "A watercolour fox in a snowy forest", "size": "1024x1024", "n": 1 } } } } }, "required": true }, "responses": { "200": { "description": "The produced images. Each entry of `data` carries either a link the gateway hosts or the bytes inline, whichever `response_format` asked for. `usage` carries the count the charge was computed from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" }, "examples": { "basic": { "summary": "One rendered image, as a link", "value": { "created": 1774000000, "data": [ { "url": "https://cdn.naga.ac/images/9f2c4a1b.png" } ], "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 } } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/images/generations \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-image-1\",\n \"prompt\": \"A watercolour fox in a snowy forest\",\n \"size\": \"1024x1024\",\n \"n\": 1\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.images.generate(\n model=\"gpt-image-1\",\n prompt=\"A watercolour fox in a snowy forest\",\n size=\"1024x1024\",\n n=1,\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.images.generate({\n model: \"gpt-image-1\",\n prompt: \"A watercolour fox in a snowy forest\",\n size: \"1024x1024\",\n n: 1,\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_image", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/messages": { "post": { "tags": [ "Messages" ], "summary": "Create a message", "description": "Creates a model response in the Anthropic Messages dialect and charges the account for the tokens it used. Requires an API key. `/v1/chat/completions` and `/v1/responses` serve the same models in the other two dialects.", "operationId": "create_message", "externalDocs": { "url": "https://docs.anthropic.com/en/api/messages", "description": "The Anthropic reference for this dialect." }, "parameters": [ { "name": "x-naga-routing-strategy", "in": "header", "description": "The routing strategy when the body names none. An unknown name is ignored. A NagaAI extension.", "required": false, "schema": { "$ref": "#/components/schemas/RoutingStrategyWire" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" }, "examples": { "basic": { "summary": "A plain message", "value": { "model": "claude-sonnet-4.5", "max_tokens": 256, "messages": [ { "role": "user", "content": "Say hi." } ] } }, "reasoning": { "summary": "Give the model a thinking budget", "value": { "model": "claude-opus-4-7", "max_tokens": 8192, "messages": [ { "role": "user", "content": "Plan a 3-step refactor." } ], "thinking": { "type": "enabled", "budget_tokens": 4096 } } }, "streaming": { "summary": "Stream the answer as content blocks", "value": { "model": "claude-sonnet-4.5", "max_tokens": 256, "messages": [ { "role": "user", "content": "Say hi." } ], "stream": true } }, "tool-call": { "summary": "Offer the model a tool to use", "value": { "model": "claude-sonnet-4.5", "max_tokens": 512, "messages": [ { "role": "user", "content": "What's the weather in Paris?" } ], "tools": [ { "name": "get_weather", "description": "Look up live weather for a city.", "input_schema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } ], "tool_choice": { "type": "auto" } } } } } }, "required": true }, "responses": { "200": { "description": "The message. `application/json` carries one `message` object; `text/event-stream` carries the event-typed frames of the stream.", "headers": { "x-naga-routing-strategy": { "schema": { "type": "string" }, "description": "The routing strategy NagaAI applied to this request." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MessagesMessage" }, { "$ref": "#/components/schemas/AnthropicMessageResponse" } ], "description": "The message. The gateway answers a request it does not forward with the second shape, which omits `container` and `stop_details` and adds `created`." }, "examples": { "basic": { "summary": "One `message` object", "value": { "id": "msg_01UvWq7Kt3xZbN9", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "Hi!", "citations": null } ], "model": "claude-sonnet-4.5", "stop_reason": "end_turn", "stop_sequence": null, "stop_details": null, "container": null, "usage": { "input_tokens": 5, "output_tokens": 4, "cache_creation": null, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "server_tool_use": null, "service_tier": null, "inference_geo": null, "output_tokens_details": null } } }, "reasoning": { "summary": "A thinking block, then the answer", "value": { "id": "msg_01Rq4Zt8Nb2xVk1", "type": "message", "role": "assistant", "content": [ { "type": "thinking", "thinking": "plan: identify hot files; split by responsibility; ", "signature": "sig_alpha" }, { "type": "text", "text": "Here is the plan.", "citations": null } ], "model": "claude-opus-4-7", "stop_reason": "end_turn", "stop_sequence": null, "stop_details": null, "container": null, "usage": { "input_tokens": 12, "output_tokens": 80, "cache_creation": null, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "server_tool_use": null, "service_tier": null, "inference_geo": null, "output_tokens_details": null } } }, "tool-call": { "summary": "The turn stopped to use a tool", "value": { "id": "msg_01Hn6Yc2Wp5tQz8", "type": "message", "role": "assistant", "content": [ { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": { "city": "Paris" }, "caller": { "type": "assistant" } } ], "model": "claude-sonnet-4.5", "stop_reason": "tool_use", "stop_sequence": null, "stop_details": null, "container": null, "usage": { "input_tokens": 5, "output_tokens": 4, "cache_creation": null, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "server_tool_use": null, "service_tier": null, "inference_geo": null, "output_tokens_details": null } } } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessagesStreamFrame" }, "examples": { "basic": { "summary": "A text delta of a streamed answer", "value": { "type": "content_block_delta", "index": 0, "delta": { "type": "text_delta", "text": "Hi!" } } }, "reasoning": { "summary": "A thinking delta, before any text block opens", "value": { "type": "content_block_delta", "index": 0, "delta": { "type": "thinking_delta", "thinking": "plan: identify hot files; " } } }, "tool-call": { "summary": "The tool input arrives as partial JSON", "value": { "type": "content_block_delta", "index": 0, "delta": { "type": "input_json_delta", "partial_json": "{\"city\":" } } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "type": "error", "error": { "type": "authentication_error", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "type": "error", "error": { "type": "billing_error", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "404": { "description": "The upstream provider reports that the addressed resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "type": "error", "error": { "type": "rate_limit_error", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/messages \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"claude-sonnet-4.5\",\n \"max_tokens\": 256,\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Say hi.\"\n }\n ]\n}'" }, { "lang": "python", "label": "anthropic-python", "source": "import os\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac\",\n)\n\nresult = client.messages.create(\n model=\"claude-sonnet-4.5\",\n max_tokens=256,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"Say hi.\"\n }\n ],\n)\nprint(result)\n" } ], "x-mcp": { "name": "naga_create_message", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List models", "description": "Returns the models NagaAI serves, whole and unpaged. Requires no key; presenting one narrows the catalog to what the account's balance can reach.", "operationId": "list_models", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/models", "description": "The OpenAI reference for this route." }, "parameters": [ { "name": "x-naga-supported-endpoint", "in": "header", "description": "Which endpoint every listed model must serve, such as `chat.completions`. A name no model serves returns an empty list. A NagaAI extension.", "required": false, "schema": { "type": "string" }, "example": "chat.completions" } ], "responses": { "200": { "description": "The catalog the caller may reach, whole and in one answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "examples": { "basic": { "summary": "One catalog entry", "value": { "object": "list", "data": [ { "id": "gpt-4o-mini", "object": "model", "created": 1721260800, "owned_by": "openai", "display_name": "GPT-4o mini", "context_window": 128000, "supported_endpoints": [ "chat.completions" ], "pricing": { "per_input_token": 1.5e-7, "per_output_token": 6e-7 }, "architecture": { "input_modalities": [ "text", "image" ], "output_modalities": [ "text" ] }, "supported_parameters": [ "tools", "response_format" ] } ] } } } } }, "x-retry-safe": false }, "401": { "description": "An API key was presented and it is not one this gateway serves. Omitting the credential reads the catalog anonymously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "A store the gateway needs to answer this did not respond. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ {}, { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/models \\\n -H \"Authorization: Bearer $NAGA_API_KEY\"" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.models.list()\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.models.list();\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_list_models", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } } }, "/v1/moderations": { "post": { "tags": [ "Moderations" ], "summary": "Classify content", "description": "Classifies text and images against a moderation model's categories and charges the account for the tokens it counted. Requires an API key.", "operationId": "create_moderation", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/moderations", "description": "The OpenAI reference for this route." }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Moderation" }, "examples": { "basic": { "summary": "Classify one string", "value": { "model": "omni-moderation-latest", "input": "I want to hurt them." } } } } }, "required": true }, "responses": { "200": { "description": "The verdict. `results` carries one entry per input, each with the flag, the per-category verdicts and the scores behind them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerationsResponse" }, "examples": { "basic": { "summary": "One result, flagged", "value": { "id": "mdr-4tKq7Zc1Nb9Wx2Ry8Vd3Ms6Ph0Q", "model": "omni-moderation-latest", "results": [ { "flagged": true, "categories": { "violence": true, "harassment": false }, "category_scores": { "violence": 0.9124, "harassment": 0.0217 } } ] } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/moderations \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"omni-moderation-latest\",\n \"input\": \"I want to hurt them.\"\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.moderations.create(\n model=\"omni-moderation-latest\",\n input=\"I want to hurt them.\",\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.moderations.create({\n model: \"omni-moderation-latest\",\n input: \"I want to hurt them.\",\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_moderation", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/responses": { "post": { "tags": [ "Responses" ], "summary": "Create a response", "description": "Creates a model response in the OpenAI Responses dialect and charges the account for the tokens it used. Requires an API key. `/v1/chat/completions` and `/v1/messages` serve the same models in the other two dialects.", "operationId": "create_response", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/responses", "description": "The OpenAI reference for this dialect." }, "parameters": [ { "name": "x-naga-routing-strategy", "in": "header", "description": "The routing strategy when the body names none. An unknown name is ignored. A NagaAI extension.", "required": false, "schema": { "$ref": "#/components/schemas/RoutingStrategyWire" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" }, "examples": { "basic": { "summary": "A plain turn", "value": { "model": "gpt-5", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "say hi" } ] } ] } }, "reasoning": { "summary": "Ask for a reasoning summary", "value": { "model": "gpt-5.4", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Plan a 3-step refactor." } ] } ], "reasoning": { "effort": "medium", "summary": "auto" } } }, "streaming": { "summary": "Stream the output items as they open and close", "value": { "model": "gpt-5", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "say hi" } ] } ], "stream": true } }, "tool-call": { "summary": "Two functions called in parallel", "value": { "model": "gpt-5", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "weather in NYC and SF" } ] } ], "parallel_tool_calls": true, "tools": [ { "type": "function", "name": "get_weather", "parameters": { "type": "object", "properties": { "city": { "type": "string" } } } } ] } } } } }, "required": true }, "responses": { "200": { "description": "The response. `application/json` carries one `response` object; `text/event-stream` carries the event-typed lifecycle frames.", "headers": { "x-naga-routing-strategy": { "schema": { "type": "string" }, "description": "The routing strategy NagaAI applied to this request." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" }, "examples": { "basic": { "summary": "One completed `response` object", "value": { "id": "resp_01H8Zt4Qk9", "object": "response", "created_at": 1774000000, "status": "completed", "model": "gpt-5", "output": [ { "type": "message", "id": "msg_1", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "hello world" } ] } ], "error": null, "incomplete_details": null, "usage": { "input_tokens": 3, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 2, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 5 }, "instructions": null, "tools": [], "tool_choice": "auto", "temperature": 1.0, "top_p": 1.0, "parallel_tool_calls": true, "metadata": null, "text": { "format": { "type": "text" } }, "truncation": "disabled", "max_output_tokens": null } }, "reasoning": { "summary": "A reasoning item precedes the message", "value": { "id": "resp_01K2Rw8Nc4", "object": "response", "created_at": 1774000000, "status": "completed", "model": "gpt-5.4", "output": [ { "type": "reasoning", "id": "rs_1", "summary": [ { "type": "summary_text", "text": "first part" } ], "content": [] }, { "type": "message", "id": "msg_1", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "Here is the plan." } ] } ], "error": null, "incomplete_details": null, "usage": { "input_tokens": 12, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 80, "output_tokens_details": { "reasoning_tokens": 64 }, "total_tokens": 92 }, "instructions": null, "tools": [], "tool_choice": "auto", "temperature": 1.0, "top_p": 1.0, "parallel_tool_calls": true, "metadata": null, "text": { "format": { "type": "text" } }, "truncation": "disabled", "max_output_tokens": null } }, "tool-call": { "summary": "Two function calls, no message", "value": { "id": "resp_01M5Pd7Vb2", "object": "response", "created_at": 1774000000, "status": "completed", "model": "gpt-5", "output": [ { "type": "function_call", "id": "fc_1", "call_id": "call_a", "name": "get_weather", "arguments": "{\"city\":\"NYC\"}", "status": "completed" }, { "type": "function_call", "id": "fc_2", "call_id": "call_b", "name": "get_weather", "arguments": "{\"city\":\"SF\"}", "status": "completed" } ], "error": null, "incomplete_details": null, "usage": { "input_tokens": 12, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 18, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 30 }, "instructions": null, "tools": [], "tool_choice": "auto", "temperature": 1.0, "top_p": 1.0, "parallel_tool_calls": true, "metadata": null, "text": { "format": { "type": "text" } }, "truncation": "disabled", "max_output_tokens": null } } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponsesStreamFrame" }, "examples": { "basic": { "summary": "A text delta of a streamed turn", "value": { "type": "response.output_text.delta", "item_id": "msg_1", "output_index": 0, "content_index": 0, "delta": "hello", "logprobs": [], "sequence_number": 3 } }, "reasoning": { "summary": "A delta of the reasoning summary", "value": { "type": "response.reasoning_summary_text.delta", "item_id": "rs_1", "output_index": 0, "summary_index": 0, "delta": "first part", "sequence_number": 4 } }, "tool-call": { "summary": "The function arguments arrive as a delta", "value": { "type": "response.function_call_arguments.delta", "item_id": "fc_1", "output_index": 0, "delta": "{\"city\":\"NYC\"}", "sequence_number": 5 } } } } }, "x-retry-safe": false }, "400": { "description": "The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "401": { "description": "The API key is missing, malformed, disabled, or does not belong to an account that may call this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalid-api-key": { "summary": "401 — the key is not one this gateway serves", "value": { "error": { "type": "invalid_api_key", "message": "The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again." } } } } } }, "x-retry-safe": false }, "402": { "description": "The account has run out of credits. Top up the balance and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "insufficient-credits": { "summary": "402 — the account has no credits left", "value": { "error": { "type": "insufficient_quota", "message": "More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits." } } } } } }, "x-retry-safe": false }, "403": { "description": "The account may not use this model, or the content was blocked by the moderation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "404": { "description": "The upstream provider reports that the addressed resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "408": { "description": "The request body did not finish arriving within 15 minutes, or stalled for 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "410": { "description": "The model is deprecated and no longer served. Pick a current one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "413": { "description": "The request body is larger than the 32 MiB this gateway accepts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "422": { "description": "The request was understood but its usage could not be metered, so it was not served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": false }, "429": { "description": "The account exceeded its rate limit. `Retry-After` carries the wait in seconds.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate-limited": { "summary": "429 — too many requests; `Retry-After` carries the wait", "value": { "error": { "type": "rate_limit_exceeded", "message": "Rate limit reached. Please try again in 3s." } } } } } }, "x-retry-safe": true }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true }, "503": { "description": "No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "How long to wait before retrying, in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "security": [ { "bearerAuth": [] }, { "xApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/responses \\\n -H \"Authorization: Bearer $NAGA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-5\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"say hi\"\n }\n ]\n }\n ]\n}'" }, { "lang": "python", "label": "openai-python", "source": "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"NAGA_API_KEY\"],\n base_url=\"https://api.naga.ac/v1\",\n)\n\nresult = client.responses.create(\n model=\"gpt-5\",\n input=[\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"say hi\"\n }\n ]\n }\n ],\n)\nprint(result)\n" }, { "lang": "javascript", "label": "openai-node", "source": "import OpenAI from \"openai\";\n\nconst client = new OpenAI({\n apiKey: process.env.NAGA_API_KEY,\n baseURL: \"https://api.naga.ac/v1\",\n});\n\nconst result = await client.responses.create({\n model: \"gpt-5\",\n input: [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"say hi\"\n }\n ]\n }\n ],\n});\nconsole.log(result);\n" } ], "x-mcp": { "name": "naga_create_response", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } } } }, "/v1/startups": { "get": { "tags": [ "Startups" ], "summary": "List startups", "description": "Returns the organizations whose models NagaAI serves. Requires no key, and presenting one changes nothing.", "operationId": "list_startups", "responses": { "200": { "description": "Every organization whose models the gateway serves, one entry each.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartupList" }, "examples": { "basic": { "summary": "One organization", "value": { "object": "list", "data": [ { "id": "openai", "object": "startup", "display_name": "OpenAI", "icon_url": "https://cdn.naga.ac/startups/openai.png", "website_url": "https://openai.com", "created": 1677610602 } ] } } } } }, "x-retry-safe": false }, "500": { "description": "The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "x-retry-safe": true } }, "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl https://api.naga.ac/v1/startups \\\n -H \"Authorization: Bearer $NAGA_API_KEY\"" } ], "x-mcp": { "name": "naga_list_startups", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } } } }, "components": { "schemas": { "ActivityQuery": { "type": "object", "description": "The query string of `GET /v1/account/activity`.", "properties": { "days": { "type": "integer", "format": "int32", "description": "How many days back the report reaches, from 1 to 30; anything else draws a 400.", "default": 30, "minimum": 0 } } }, "ActivityResponse": { "type": "object", "description": "What the account used, cut four ways. The answer is cached for five minutes.", "required": [ "period_days", "total_stats", "daily_stats", "top_models", "api_key_usage" ], "properties": { "period_days": { "type": "integer", "format": "int32", "description": "The window these numbers cover, in days back plus today.", "minimum": 0 }, "total_stats": { "allOf": [ { "$ref": "#/components/schemas/TotalStats" } ], "description": "The whole window in one row." }, "daily_stats": { "type": "array", "items": { "$ref": "#/components/schemas/DailyStats" }, "description": "One row per day that saw traffic, newest first." }, "top_models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelUsage" }, "description": "The ten most-used models of the window, by request count." }, "api_key_usage": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyUsage" }, "description": "One row per key that saw traffic, most-used first, uncapped." } } }, "AdditionalToolsItem": { "type": "object", "description": "Extra tool declarations carried inside `input`, merged into `tools`.", "required": [ "tools" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The item id, which the gateway does not read." }, "role": { "type": [ "string", "null" ], "description": "The role the declarations are attributed to, which the gateway does not read." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseTool" }, "description": "The declarations, in the shape of `tools[]` entries." } } }, "AllowedEntryType": { "type": "string", "description": "What an entry of an allowed set names when it is not a function.", "enum": [ "web_search", "web_search_preview", "web_search_preview_2025_03_11", "custom", "file_search", "computer", "computer_use_preview", "computer_use", "image_generation", "code_interpreter", "mcp", "apply_patch", "shell" ] }, "AllowedToolsMode": { "type": "string", "description": "How tightly an allowed set binds the model.", "enum": [ "auto", "required" ] }, "AllowedToolsType": { "type": "string", "description": "The tag of an allowed-set choice. `allowed_tools` is the only value this menu holds.", "enum": [ "allowed_tools" ] }, "AnthropicContentBlockResponse": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AnthropicTextBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/AnthropicThinkingBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `thinking`.", "enum": [ "thinking" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/AnthropicImageBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image`.", "enum": [ "image" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/AnthropicSearchResultBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `search_result`.", "enum": [ "search_result" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/AnthropicToolUseBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_use`.", "enum": [ "tool_use" ] } } } ] } ], "description": "One block of the answer's content, tagged by `type`." }, "AnthropicImageBlockResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "source" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/AnthropicImageSourceResponse" } ], "description": "Where to read the image." } } } ], "description": "An image the model generated. A NagaAI extension." }, "AnthropicImageSourceResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/AnthropicImageSourceResponseType" } ], "description": "Which form the source takes. Always `url`." }, "url": { "type": "string", "description": "Where the image is served from." } } } ], "description": "Where an image block's bytes live." }, "AnthropicImageSourceResponseType": { "type": "string", "description": "Which form an image block's source takes. Always `url` on this body.", "enum": [ "url" ] }, "AnthropicMessageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "id", "model", "content", "stop_sequence", "created" ], "properties": { "id": { "type": "string", "description": "This answer's identifier: `msg_` followed by 28 random alphanumerics." }, "type": { "allOf": [ { "$ref": "#/components/schemas/AnthropicMessageResponseType" } ], "description": "What kind of object this is. Always `message`." }, "role": { "allOf": [ { "$ref": "#/components/schemas/AnthropicMessageResponseRole" } ], "description": "Who wrote it. Always `assistant`." }, "model": { "type": "string", "description": "The model that answered, after alias resolution." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlockResponse" }, "description": "The answer itself, block by block." }, "stop_reason": { "type": [ "string", "null" ], "description": "Why the model stopped, left out when nothing set it." }, "stop_sequence": { "type": [ "string", "null" ], "description": "Always `null` on this body, and the key is always present." }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AnthropicUsageResponse" } ], "description": "What the request cost in tokens, every counter zero on this body." }, { "type": "null" } ] }, "created": { "type": "integer", "format": "int64", "description": "When the answer was made, in seconds since the Unix epoch. A NagaAI extension." } } } ], "description": "The body `POST /v1/messages` returns when the gateway answers without calling a provider." }, "AnthropicMessageResponseRole": { "type": "string", "description": "Who wrote the answer. Always `assistant`.", "enum": [ "assistant" ] }, "AnthropicMessageResponseType": { "type": "string", "description": "What kind of object the answer is. Always `message`.", "enum": [ "message" ] }, "AnthropicSearchResultBlockResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "The document's title. Left out when it carried none." }, "source": { "type": [ "string", "null" ], "description": "Where the document came from. Left out when nothing recorded it." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicTextBlockResponsePart" }, "description": "The document's text, piece by piece." } } } ], "description": "A document the model worked from, replayed in the answer. A NagaAI extension." }, "AnthropicTextBlockResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text itself." } } } ], "description": "A block of text the model wrote." }, "AnthropicTextBlockResponsePart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AnthropicTextBlockResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ] } ], "description": "A piece of text inside a search-result block." }, "AnthropicThinkingBlockResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "thinking" ], "properties": { "thinking": { "type": "string", "description": "The reasoning, as text meant to be read." }, "signature": { "type": [ "string", "null" ], "description": "An opaque token vouching for the reasoning it accompanies, replayed unchanged." } } } ], "description": "Reasoning the model is willing to show, with the signature replaying it." }, "AnthropicToolUseBlockResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The call's id, repeated as `tool_use_id` on the block carrying the result." }, "name": { "type": [ "string", "null" ], "description": "Which of your tools to call, by the name you declared it under." }, "input": { "allOf": [ { "$ref": "#/components/schemas/AnthropicToolUseBlockResponseInput" } ], "description": "The arguments to call it with, never checked against the tool's schema." } } } ], "description": "A tool call for you to run; the model is waiting for the result." }, "AnthropicToolUseBlockResponseInput": { "oneOf": [ { "type": "object" }, { "type": "string", "title": "Raw JSON string" } ], "description": "The arguments of a tool call: an object, or the raw JSON string." }, "AnthropicUsageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the prompt read fresh, cache reads excluded." }, "output_tokens": { "type": "integer", "format": "int64", "description": "Tokens the model generated, its reasoning included." }, "cache_read_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens served to this request out of the prompt cache." } } } ], "description": "What the provider counted this request at. The bill counts separately." }, "ApiKeyCreate": { "type": "object", "description": "The body of `POST /v1/account/keys`.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "A label for the key, between 1 and 255 characters." }, "credit_limit": { "type": [ "number", "null" ], "format": "double", "description": "How many credits this key may spend before the gateway turns it away. Absent means no limit of its own." }, "expires_at": { "type": [ "string", "null" ], "description": "When the key should stop working; a past instant draws a refusal. Both grammars count." }, "default_routing_strategy": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingStrategyWire" } ], "description": "The routing strategy for requests that name none. Absent lets NagaAI choose. An unknown name draws a 400." }, { "type": "null" } ] } } }, "ApiKeyCreateResponse": { "type": "object", "description": "The created key, and the only copy of its secret you will be given.", "required": [ "id", "name", "key", "created_at", "expires_at", "is_enabled", "credit_limit", "default_routing_strategy", "message" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "The created key's id, which is the `{key_id}` the per-key routes take." }, "name": { "type": "string", "description": "The label the request asked for." }, "key": { "type": "string", "description": "The secret itself, in full, and the one answer carrying it." }, "created_at": { "type": "string", "description": "When the key was created: UTC to the second, without an offset." }, "expires_at": { "type": [ "string", "null" ], "description": "When the key stops working, or `null` when the request asked for none." }, "is_enabled": { "type": "boolean", "description": "Whether the key works at all. Creation inserts it enabled." }, "credit_limit": { "type": [ "number", "null" ], "format": "double", "description": "The limit the request asked for, or `null` when it asked for none." }, "default_routing_strategy": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingStrategyWire" } ], "description": "The default routing strategy the request asked for, or `null` when NagaAI chooses." }, { "type": "null" } ] }, "message": { "type": "string", "description": "A fixed reminder that `key` above is shown once." } } }, "ApiKeyListResponse": { "type": "object", "description": "The body of `GET /v1/account/keys`.", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponse" }, "description": "Every key on the account, newest first, disabled and expired ones included." } } }, "ApiKeyResponse": { "type": "object", "description": "One API key of the account, without its secret.", "required": [ "id", "name", "created_at", "expires_at", "is_enabled", "credit_limit", "default_routing_strategy" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "The key's id, which is the `{key_id}` the per-key routes take." }, "name": { "type": "string", "description": "The label the key carries." }, "created_at": { "type": "string", "description": "When the key was created: UTC to the second, without an offset." }, "expires_at": { "type": [ "string", "null" ], "description": "When the key stops working, or `null` for one that never expires." }, "is_enabled": { "type": "boolean", "description": "Whether the key works at all." }, "credit_limit": { "type": [ "number", "null" ], "format": "double", "description": "The key's own spending limit in credits, or `null` for none." }, "default_routing_strategy": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingStrategyWire" } ], "description": "The key's default routing strategy, or `null` when NagaAI chooses." }, { "type": "null" } ] } } }, "ApiKeyUpdate": { "type": "object", "description": "The body of `PATCH /v1/account/keys/{key_id}`; an absent field stays.", "properties": { "default_routing_strategy": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingStrategyWire" } ], "description": "A new default routing strategy, or `null` to let NagaAI choose. An unknown name draws a 400." }, { "type": "null" } ] }, "name": { "type": "string", "description": "A replacement label, between 1 and 255 characters. An explicit `null` draws a 400." }, "is_enabled": { "type": "boolean", "description": "Whether the key works at all. A disabled key draws a 401 `disabled_api_key`." }, "credit_limit": { "type": [ "number", "null" ], "format": "double", "description": "A replacement spending limit in credits, or `null` to clear it." }, "expires_at": { "type": [ "string", "null" ], "description": "A later expiry, or `null` to clear it." } } }, "ApiKeyUsage": { "type": "object", "description": "One API key's share of the window.", "required": [ "api_key_id", "api_key_name", "request_count", "total_cost", "total_input_tokens", "total_output_tokens" ], "properties": { "api_key_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Which key made these requests, by the id `/v1/account/keys` reports." }, "api_key_name": { "type": [ "string", "null" ], "description": "The name that key carried over the counted window." }, "request_count": { "type": "integer", "format": "int64", "description": "How many requests this key made, failed ones included." }, "total_cost": { "type": "string", "description": "What they cost in credits, as a decimal string." }, "total_input_tokens": { "type": "integer", "format": "int64", "description": "Input tokens summed over those requests." }, "total_output_tokens": { "type": "integer", "format": "int64", "description": "Output tokens summed over those requests." } } }, "ApplyPatchTool": { "type": "object", "description": "A hosted tool the gateway takes and drops." }, "AspectRatio": { "type": "string", "description": "Requested shape of an image output, written `width:height`.", "enum": [ "1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9" ] }, "AudioContent": { "type": "object", "description": "An audio content part, sent on a request alone.", "required": [ "input_audio" ], "properties": { "input_audio": { "allOf": [ { "$ref": "#/components/schemas/InputAudio" } ], "description": "The audio payload and its format." } } }, "AudioTextResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "What the model heard in the uploaded audio, and the whole body." } } } ], "description": "The answer both audio-to-text routes give: the recognized text." }, "BalanceResponse": { "type": "object", "description": "What the account has left to spend, as a decimal string.", "required": [ "balance" ], "properties": { "balance": { "type": "string", "description": "The credits left, one credit being one US dollar." } } }, "Base64ImageSourceParam": { "type": "object", "description": "An image supplied inline: the bytes as base64, plus their media type.", "required": [ "media_type", "data" ], "properties": { "media_type": { "allOf": [ { "$ref": "#/components/schemas/ImageMediaType" } ], "description": "The format of the bytes in `data`. Required, with no default." }, "data": { "type": "string", "description": "The image bytes as bare base64, under 20 MiB." } } }, "Base64PdfSourceParam": { "type": "object", "description": "A PDF supplied inline, as base64 bytes.", "required": [ "data" ], "properties": { "media_type": { "allOf": [ { "$ref": "#/components/schemas/PdfMediaType" } ], "description": "The document's media type. Absent means `application/pdf`." }, "data": { "type": "string", "description": "The PDF bytes as bare base64, under 20 MiB." } } }, "CatalogArchitecture": { "type": "object", "description": "Which modalities the model reads and which it writes.", "properties": { "input_modalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "What the model accepts, or `null` when the catalog has none." }, "output_modalities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "What the model produces, or `null` when the catalog has none." } }, "additionalProperties": false }, "CatalogModel": { "type": "object", "description": "One model the gateway serves. An unrecorded key is omitted rather than `null`.", "required": [ "id", "object", "created", "architecture" ], "properties": { "id": { "type": "string", "description": "The name to send as `model`." }, "object": { "type": "string", "description": "Always `model`." }, "created": { "type": "integer", "format": "int64", "description": "When the model entered the catalog, in Unix seconds." }, "owned_by": { "type": [ "string", "null" ], "description": "The startup publishing it, or `null` when the catalog has none." }, "architecture": { "allOf": [ { "$ref": "#/components/schemas/CatalogArchitecture" } ], "description": "Which modalities go in and which come out." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people." }, "description": { "type": [ "string", "null" ], "description": "What the publisher says the model does." }, "context_window": { "type": [ "integer", "null" ], "format": "int64", "description": "How many tokens one request may carry." }, "max_output_images": { "type": [ "integer", "null" ], "format": "int64", "description": "How many images one request may ask for." }, "supported_endpoints": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The endpoint names a configured provider serves it on." }, "pricing": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CatalogPricing" } ], "description": "What one token costs, in credits." }, { "type": "null" } ] }, "aliases": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Other names accepted as `model` for it." }, "deprecates_at": { "type": [ "integer", "null" ], "format": "int64", "description": "When it stops answering, in Unix seconds." }, "supported_parameters": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Extra request fields the providers behind it accept." } }, "additionalProperties": false }, "CatalogPricing": { "type": "object", "description": "Unit prices in credits. Each key names its own unit. A `per_input_token` of `0.00000015` costs 0.15 credits per million prompt tokens. A `per_input_audio_hour` of `0.36` costs 0.36 credits per hour of audio.", "properties": { "per_input_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one prompt token costs." }, "per_cached_input_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one prompt token read from cache costs." }, "per_output_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one generated token costs." }, "per_output_image_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one generated image token costs." }, "per_input_text_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one text prompt token costs." }, "per_input_image_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one image prompt token costs." }, "per_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one token costs in either direction." }, "per_input_audio_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one audio prompt token costs." }, "per_output_audio_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one generated audio token costs." }, "per_input_audio_hour": { "type": [ "number", "null" ], "format": "double", "description": "The credits one hour of prompt audio costs." }, "per_output_audio_hour": { "type": [ "number", "null" ], "format": "double", "description": "The credits one hour of generated audio costs." }, "per_output_text_token": { "type": [ "number", "null" ], "format": "double", "description": "The credits one generated text token costs." }, "per_input_text_character": { "type": [ "number", "null" ], "format": "double", "description": "The credits one character of prompt text costs." }, "per_output_text_character": { "type": [ "number", "null" ], "format": "double", "description": "The credits one character of generated text costs." } }, "additionalProperties": false }, "CatalogStartup": { "type": "object", "description": "One organization whose models the catalog carries.", "required": [ "id", "object" ], "properties": { "id": { "type": "string", "description": "The name a model reports as `owned_by`." }, "object": { "type": "string", "description": "Always `startup`." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people." }, "icon_url": { "type": [ "string", "null" ], "description": "Where the logo is served from." }, "website_url": { "type": [ "string", "null" ], "description": "Where the organization publishes about itself." }, "created": { "type": [ "integer", "null" ], "format": "int64", "description": "When the organization entered the catalog, in Unix seconds." } }, "additionalProperties": false }, "ChatChoice": { "type": "object", "description": "One answer the model produced for the request.", "required": [ "index", "message", "finish_reason", "logprobs" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "This answer's position in `choices[]`. Always `0`." }, "message": { "allOf": [ { "$ref": "#/components/schemas/ChatResponseMessage" } ], "description": "The message the model produced." }, "finish_reason": { "type": "string", "description": "Why the model stopped, in one of four values.", "example": "stop" }, "logprobs": { "description": "Always `null`. The gateway returns no token log probabilities." } } }, "ChatChunk": { "type": "object", "description": "One frame of a streamed answer.", "required": [ "id", "object", "created", "model", "choices" ], "properties": { "id": { "type": "string", "description": "The answer's identifier, repeated on every frame of it." }, "object": { "type": "string", "description": "What kind of object this is. Always `chat.completion.chunk`.", "example": "chat.completion.chunk" }, "created": { "type": "integer", "format": "int64", "description": "When the answer was created, in seconds since the Unix epoch, repeated on every frame of it." }, "model": { "type": "string", "description": "The model producing the answer, repeated on every frame of it." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChunkChoice" }, "description": "What this frame adds — one entry, or none at all on the usage trailer." }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatUsage" } ], "description": "What the request cost in tokens. Present on the usage trailer only, and only when it was asked for." }, { "type": "null" } ] } } }, "ChatChunkChoice": { "type": "object", "description": "One answer's share of a streamed frame.", "required": [ "index", "delta", "finish_reason", "logprobs" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "Which answer the frame belongs to. Always `0`, as in a non-streaming body." }, "delta": { "allOf": [ { "$ref": "#/components/schemas/ChatDelta" } ], "description": "What this frame adds to the answer." }, "finish_reason": { "type": [ "string", "null" ], "description": "Why the model stopped, carried by the last frame alone.", "example": "stop" }, "logprobs": { "description": "Always `null`, as on a non-streaming choice." } } }, "ChatChunkFunction": { "type": "object", "description": "The function part of a streamed tool call.", "required": [ "arguments" ], "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the function to call, sent once on the announce frame." }, "arguments": { "type": "string", "description": "The next slice of the argument JSON; no slice is valid JSON alone." } } }, "ChatChunkToolCall": { "type": "object", "description": "One tool call as a stream reports it, accumulated by `index`.", "required": [ "index", "function" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "Which tool call of this turn the frame is about, and the key to accumulate on." }, "id": { "type": [ "string", "null" ], "description": "The call's id, sent once on the frame that announces the call." }, "type": { "type": [ "string", "null" ], "description": "What kind of call this is. Always `function`.", "example": "function" }, "function": { "allOf": [ { "$ref": "#/components/schemas/ChatChunkFunction" } ], "description": "The part of the call this frame carries: a name, or an argument slice." } } }, "ChatCompletionChoiceResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "message" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "This answer's position in `choices`. Always `0`." }, "message": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageResponse" } ], "description": "The message the model produced." }, "finish_reason": { "type": [ "string", "null" ], "description": "Why the model stopped, in one of four values." }, "logprobs": { "description": "Not sent. The gateway returns no token log probabilities." } } } ], "description": "One choice of a non-streaming chat completion." }, "ChatCompletionChunkModel": { "type": "object", "description": "One frame of a streamed answer from `POST /v1/chat/completions`.", "required": [ "id", "created", "model", "choices", "usage" ], "properties": { "id": { "type": "string", "description": "The identifier of the answer these frames belong to, repeated on every frame." }, "created": { "type": "integer", "format": "int64", "description": "When the answer was created, in seconds since the Unix epoch." }, "model": { "type": "string", "description": "The model the answer is attributed to, after alias resolution." }, "choices": { "type": [ "array", "null" ], "items": {}, "description": "What this frame adds — one element, matching the answer's single choice." }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionUsageResponse" } ], "description": "What the answer cost in tokens, `null` on every frame but the trailer." }, { "type": "null" } ] }, "object": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionChunkModelObject" } ], "description": "What kind of object this is. Always `chat.completion.chunk`." } } }, "ChatCompletionChunkModelObject": { "type": "string", "description": "What kind of object the frame is. Always `chat.completion.chunk`.", "enum": [ "chat.completion.chunk" ] }, "ChatCompletionFunctionCallResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the function to call, as declared in `tools[]`." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as JSON in a string. Valid JSON is not guaranteed." } } } ], "description": "The function a tool call names, and its arguments." }, "ChatCompletionMessageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "Who wrote the message. `assistant` on an answer." }, "content": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageResponseContent" } ], "description": "The text the model returned, absent when the turn produced none." }, { "type": "null" } ] }, "refusal": { "type": [ "string", "null" ], "description": "The reason the model gave for declining, absent when it did not." }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionToolCallResponse" }, "description": "The tool calls the model made. Absent when it made none." }, "annotations": { "type": [ "array", "null" ], "items": {}, "description": "Where the dialect puts citations. No answer from this gateway carries them." }, "reasoning_content": { "type": [ "string", "null" ], "description": "The model's reasoning as plain text. A NagaAI extension mirroring the first reasoning item only." }, "reasoning_details": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatReasoningDetailResponse" }, "description": "The turn's reasoning as structured entries, in the order the model produced them. A NagaAI extension." }, "images": { "type": [ "array", "null" ], "items": {}, "description": "The images the model generated, beside `content`. A NagaAI extension." }, "name": { "type": [ "string", "null" ], "description": "The participant name a request may carry. This gateway never sends it." }, "tool_call_id": { "type": [ "string", "null" ], "description": "The id of the call a `tool` message answers. This gateway never sends it." } } } ], "description": "The assistant message of a non-streaming chat completion." }, "ChatCompletionMessageResponseContent": { "oneOf": [ { "type": "string", "title": "Plain text", "description": "The whole message as a single string." }, { "type": "array", "title": "List of content parts", "items": {}, "description": "The message as a list of content parts, each taken as any JSON value." } ], "description": "The message's content: one run of text, or content parts." }, "ChatCompletionModel": { "type": "object", "description": "The body of a non-streaming answer from `POST /v1/chat/completions`.", "required": [ "id", "created", "model", "choices", "usage" ], "properties": { "id": { "type": "string", "description": "This answer's identifier, opaque end to end." }, "created": { "type": "integer", "format": "int64", "description": "When the answer was created, in whole seconds since the Unix epoch." }, "model": { "type": "string", "description": "The model the answer is attributed to, after alias resolution." }, "choices": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionChoiceResponse" }, "description": "The one answer to the request; the key is on every body." }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionUsageResponse" } ], "description": "What the request cost in tokens, `null` when the gateway metered nothing." }, { "type": "null" } ] }, "object": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionModelObject" } ], "description": "What kind of object this is. Always `chat.completion`." } } }, "ChatCompletionModelObject": { "type": "string", "description": "What kind of object the body is. Always `chat.completion`.", "enum": [ "chat.completion" ] }, "ChatCompletionResponse": { "type": "object", "description": "The body of a non-streaming answer.", "required": [ "id", "object", "created", "model", "choices" ], "properties": { "id": { "type": "string", "description": "This answer's identifier, repeated on every frame of a stream." }, "object": { "type": "string", "description": "What kind of object this is. Always `chat.completion`.", "example": "chat.completion" }, "created": { "type": "integer", "format": "int64", "description": "When the answer was created, in seconds since the Unix epoch." }, "model": { "type": "string", "description": "The model that answered, by its id in the NagaAI catalog." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoice" }, "description": "The answers the model produced — one entry, see `index`." }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatUsage" } ], "description": "What the request cost in tokens, absent when the provider reported none." }, { "type": "null" } ] } } }, "ChatCompletionTokensDetails": { "type": "object", "description": "Breakdown of the completion-side token count.", "required": [ "reasoning_tokens" ], "properties": { "reasoning_tokens": { "type": "integer", "format": "int64", "description": "How many generated tokens the model spent reasoning. `0` when the provider reported none." }, "image_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many generated tokens were image output. A NagaAI extension." } } }, "ChatCompletionTokensDetailsResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "image_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many generated tokens were image output. A NagaAI extension." } } } ], "description": "The split of the completion-side token count." }, "ChatCompletionToolCallResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "function" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The call's id, repeated as `tool_call_id` on the answering message." }, "type": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionToolCallResponseType" } ], "description": "What kind of call this is. Always `function`." }, "function": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionFunctionCallResponse" } ], "description": "Which function to call, and with what arguments." } } } ], "description": "One tool call the model made." }, "ChatCompletionToolCallResponseType": { "type": "string", "description": "What kind of tool call this is. Always `function`.", "enum": [ "function" ] }, "ChatCompletionUsageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the prompt, cached ones included." }, "completion_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the answer, reasoning and image tokens included." }, "total_tokens": { "type": "integer", "format": "int64", "description": "The provider's own total for the request, never recomputed here." }, "prompt_tokens_details": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatPromptTokensDetailsResponse" } ], "description": "The split of `prompt_tokens`. Absent when the answer reports none." }, { "type": "null" } ] }, "completion_tokens_details": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionTokensDetailsResponse" } ], "description": "The split of `completion_tokens`. Absent when the answer reports none." }, { "type": "null" } ] } } } ], "description": "What the provider counted this request at. The bill counts separately." }, "ChatCompletions": { "type": "object", "description": "The OpenAI-compatible Chat Completions request. The gateway takes an unrecognized key and drops it.", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "The model to run, named by an id or alias from NagaAI's catalog. An entry without the `chat.completions` capability draws a refusal." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "The conversation so far, oldest first; one entry at least.", "minItems": 1 }, "routing": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingPreferences" } ], "description": "How NagaAI orders the providers for this request. It reorders them and never removes one. A NagaAI extension." }, { "type": "null" } ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatTool" }, "description": "The tools the model is allowed to call." }, "functions": { "type": [ "array", "null" ], "items": {}, "description": "The pre-`tools` function-calling surface. A request carrying it draws a refusal." }, "tool_choice": { "allOf": [ { "$ref": "#/components/schemas/ChatToolChoice" } ], "description": "Which tool, if any, the model calls. An explicit `null` draws a refusal." }, "response_format": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponseFormat" } ], "description": "The shape the model's output must take." }, { "type": "null" } ] }, "temperature": { "type": [ "number", "null" ], "format": "double", "description": "How much randomness goes into the reply, between 0 and 2, and an alternative to `top_p`.", "maximum": 2, "minimum": 0 }, "top_p": { "type": [ "number", "null" ], "format": "double", "description": "The sampling cut-off, between 0 and 1, and an alternative to `temperature`.", "maximum": 1, "minimum": 0 }, "stream": { "type": [ "boolean", "null" ], "description": "Whether the reply arrives incrementally as the model writes it." }, "stream_options": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/StreamOptions" } ], "description": "Extra streaming behavior. `include_usage` adds one trailing chunk carrying the totals." }, { "type": "null" } ] }, "stop": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatStop" } ], "description": "Strings that end generation the moment the model produces one." }, { "type": "null" } ] }, "max_completion_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "The ceiling on generated tokens, reasoning included. At least 1.", "minimum": 1 }, "max_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "An alias of `max_completion_tokens`, read only when that key is absent.", "minimum": 1 }, "reasoning_effort": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningEffort" } ], "description": "How much reasoning to spend before answering, from `none` to `max`. A model without the level runs the nearest one it has." }, { "type": "null" } ] }, "presence_penalty": { "type": [ "number", "null" ], "format": "double", "description": "How hard a token is penalized for having appeared, from -2 to 2.", "maximum": 2, "minimum": -2 }, "frequency_penalty": { "type": [ "number", "null" ], "format": "double", "description": "How hard repetition is penalized, scaled by how often, from -2 to 2.", "maximum": 2, "minimum": -2 }, "logit_bias": { "type": [ "object", "null" ], "description": "A map from token id to sampling bias. The gateway drops it.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Whether the model may return several tool calls in one turn." }, "prediction": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Prediction" } ], "description": "Content the reply is expected to reproduce, which the gateway drops." }, { "type": "null" } ] }, "web_search_options": { "type": [ "object", "null" ], "description": "Settings for the hosted web-search tool. The gateway drops them.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "image_config": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageConfig" } ], "description": "An aspect ratio and a size for image output. A NagaAI extension the gateway drops." }, { "type": "null" } ] } } }, "ChatContentPart": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextContent" } ], "description": "A run of plain text." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "A run of plain text." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageContent" } ], "description": "An image handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image_url`.", "enum": [ "image_url" ] } } } ], "description": "An image handed to the model as input." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/FileContent" } ], "description": "A file handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `file`.", "enum": [ "file" ] } } } ], "description": "A file handed to the model as input." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/AudioContent" } ], "description": "Audio handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_audio`.", "enum": [ "input_audio" ] } } } ], "description": "Audio handed to the model as input." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/RefusalContent" } ], "description": "A refusal the model produced, replayed on an assistant message." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `refusal`.", "enum": [ "refusal" ] } } } ], "description": "A refusal the model produced, replayed on an assistant message." } ], "description": "One entry of a message's `content`. The role decides which kinds it admits." }, "ChatDelta": { "type": "object", "description": "What one frame adds to the answer, merged into what came before.", "properties": { "role": { "type": [ "string", "null" ], "description": "Who is writing. `assistant`, sent once on the first frame." }, "content": { "type": [ "string", "null" ], "description": "The next slice of the answer text, which can be a fragment of a word." }, "reasoning_content": { "type": [ "string", "null" ], "description": "The next slice of the plain-text reasoning summary. A NagaAI extension." }, "reasoning_details": { "type": [ "array", "null" ], "items": {}, "description": "Structured reasoning entries for what the model just produced. A NagaAI extension." }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatChunkToolCall" }, "description": "Tool-call frames: an announcement, or the next argument slice." }, "images": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatImageEntry" }, "description": "A generated image, sent whole on one frame. A NagaAI extension." } } }, "ChatError": { "type": "object", "description": "What went wrong once a stream had started.", "required": [ "type", "message", "code", "param" ], "properties": { "type": { "type": "string", "description": "The class of failure, in the OpenAI error vocabulary — `api_error` for a failure with no more precise class." }, "message": { "type": "string", "description": "What went wrong, in prose meant to be read." }, "code": { "type": [ "string", "null" ], "description": "A machine-readable code for the failure, or `null` when the provider gave none. The key is always present." }, "param": { "type": [ "string", "null" ], "description": "The request field the failure is about, or `null` when it is about none. The key is always present." } } }, "ChatErrorEnvelope": { "type": "object", "description": "The frame replacing a chunk when a stream fails midway.", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/ChatError" } ], "description": "What went wrong." } } }, "ChatImageDetail": { "type": "string", "description": "How much detail the model spends on the image.", "enum": [ "low", "high", "auto" ] }, "ChatImageEntry": { "type": "object", "description": "One image the model generated. A NagaAI extension beside `content`.", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "description": "What kind of entry this is. Always `image_url`.", "example": "image_url" }, "image_url": { "allOf": [ { "$ref": "#/components/schemas/ChatImageUrl" } ], "description": "Where to read the image." }, "signature": { "type": [ "string", "null" ], "description": "The token that continues this image on a later turn." }, "format": { "type": [ "string", "null" ], "description": "Which vocabulary the token is written in." } } }, "ChatImageSize": { "type": "string", "description": "Requested resolution tier of an image output.", "enum": [ "1K", "2K", "4K" ] }, "ChatImageUrl": { "type": "object", "description": "Where to read a generated image.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Where the image lives: a `data:` URI when the provider returned bytes, its own URL when it returned a link." } } }, "ChatMessage": { "type": "object", "description": "One message of the conversation.", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "Who the message is from." }, "content": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatMessageContent" } ], "description": "The contents of the message. Optional only on an `assistant` message." }, { "type": "null" } ] }, "images": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ImageContentPart" }, "description": "Image references carried beside `content`. A NagaAI extension." }, "reasoning_details": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ReasoningDetailUnion" }, "description": "Reasoning items of an earlier assistant turn, echoed back. A NagaAI extension that wins over `reasoning_content`." }, "reasoning_content": { "type": [ "string", "null" ], "description": "The plain-text reasoning of an earlier assistant turn. A NagaAI extension." }, "reasoning": { "type": [ "string", "null" ], "description": "An alias of `reasoning_content`, read last of the three." }, "name": { "type": [ "string", "null" ], "description": "A name for the participant. The gateway drops it." }, "tool_call_id": { "type": [ "string", "null" ], "description": "On a `tool` message, the id of the call it answers. Required there." }, "tool_calls": { "type": [ "array", "null" ], "items": {}, "description": "The tool calls an assistant made, echoed back so results can follow." }, "function_call": { "type": [ "object", "null" ], "description": "The singular call that preceded `tool_calls`. An assistant message carrying it draws a refusal.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "ChatMessageContent": { "oneOf": [ { "type": "array", "title": "List of content parts", "items": { "$ref": "#/components/schemas/ChatContentPart" }, "description": "An array of content parts. The admitted kinds follow the role: `user` and `tool` messages take text, image, file and audio parts. `system` and `developer` messages take text only, and `assistant` messages take text and refusal." }, { "type": "string", "title": "Plain text", "description": "The whole message as a single string." } ], "description": "The contents of a message: a string, or typed parts." }, "ChatPromptTokensDetails": { "type": "object", "description": "Breakdown of the prompt-side token count.", "required": [ "cached_tokens" ], "properties": { "cached_tokens": { "type": "integer", "format": "int64", "description": "How many prompt tokens the provider served from its own cache. `0` when it reported none." }, "audio_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many prompt tokens were audio, present only when the provider split them out." } } }, "ChatPromptTokensDetailsResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "cached_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many prompt tokens the provider served from its own cache." } } } ], "description": "The split of the prompt-side token count." }, "ChatReasoningDetailResponse": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningSummaryResponse" } ], "title": "Reasoning summary", "description": "A summary of the reasoning, as the model wrote it." }, { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningEncryptedResponse" } ], "title": "Encrypted reasoning", "description": "An opaque continuation token standing in for reasoning that is not returned in the clear." }, { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningTextResponse" } ], "title": "Reasoning text", "description": "The reasoning text itself, with its signature when the provider signed it." } ], "description": "One entry of `reasoning_details`, told apart by its `type`." }, "ChatReasoningEncryptedResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "type", "data" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The `tool_calls[].id` this token belongs to, when the token came with a call." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning format this token follows, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Absent on a stream." }, "type": { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningEncryptedResponseType" } ], "description": "What kind of entry this is. Always `reasoning.encrypted` here." }, "data": { "type": "string", "description": "The continuation token itself, opaque and replayed unchanged." } } } ], "description": "One `reasoning_details` entry carrying an opaque continuation token." }, "ChatReasoningEncryptedResponseType": { "type": "string", "description": "What kind of reasoning entry this is. Always `reasoning.encrypted`.", "enum": [ "reasoning.encrypted" ] }, "ChatReasoningSummary": { "type": "object", "description": "A short recap of one step of the model's reasoning. A NagaAI extension.", "required": [ "summary" ], "properties": { "id": { "type": [ "string", "null" ], "description": "An identifier travelling with the entry, never routed onto a tool call." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning dialect produced the entry, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Answers only." }, "summary": { "type": "string", "description": "The recap text." } } }, "ChatReasoningSummaryResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "type", "summary" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Absent on a summary entry; one sent back routes the entry nowhere." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning format the entry follows, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Absent on a stream." }, "type": { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningSummaryResponseType" } ], "description": "What kind of entry this is. Always `reasoning.summary` here." }, "summary": { "type": "string", "description": "The model's summary of its own reasoning, sliced across frames on a stream." } } } ], "description": "One `reasoning_details` entry carrying a readable summary of the reasoning." }, "ChatReasoningSummaryResponseType": { "type": "string", "description": "What kind of reasoning entry this is. Always `reasoning.summary`.", "enum": [ "reasoning.summary" ] }, "ChatReasoningTextResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "type" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Absent on a text entry; one sent back routes a `signature` onto the matching call." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning format the entry follows, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Absent on a stream." }, "type": { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningTextResponseType" } ], "description": "What kind of entry this is. Always `reasoning.text` here." }, "text": { "type": [ "string", "null" ], "description": "The model's reasoning as text, sliced across frames on a stream." }, "signature": { "type": [ "string", "null" ], "description": "The opaque continuation token for this reasoning, replayed unchanged." } } } ], "description": "One `reasoning_details` entry: reasoning text, a signature, or both." }, "ChatReasoningTextResponseType": { "type": "string", "description": "What kind of reasoning entry this is. Always `reasoning.text`.", "enum": [ "reasoning.text" ] }, "ChatResponseMessage": { "type": "object", "description": "The assistant message of a non-streaming answer, with the three keys NagaAI adds.", "required": [ "role", "content", "refusal" ], "properties": { "role": { "type": "string", "description": "Who wrote the message. Always `assistant`.", "example": "assistant" }, "content": { "type": [ "string", "null" ], "description": "The text the model returned, or `null` when the turn produced none." }, "refusal": { "type": [ "string", "null" ], "description": "The reason the model gave for declining, or `null`." }, "reasoning_content": { "type": [ "string", "null" ], "description": "The model's reasoning as plain text. A NagaAI extension mirroring the first reasoning item only." }, "reasoning_details": { "type": [ "array", "null" ], "items": {}, "description": "The turn's reasoning as structured entries, in the order the model produced them. A NagaAI extension." }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatToolCall" }, "description": "The tool calls the model made, absent when it made none." }, "images": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatImageEntry" }, "description": "The images the model generated. A NagaAI extension." } } }, "ChatStop": { "oneOf": [ { "type": "array", "title": "List of stop strings", "items": { "type": "string" } }, { "type": "string", "title": "Plain text" } ], "description": "Sequences that end generation, as one string or an array." }, "ChatTool": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/Tool" } ], "description": "A function the model may call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `function`.", "enum": [ "function" ] } } } ], "description": "A function the model may call." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/CustomToolStub" } ], "description": "A custom tool. Accepted for OpenAI-client compatibility and dropped before the request reaches the provider." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `custom`.", "enum": [ "custom" ] } } } ], "description": "A custom tool. Accepted for OpenAI-client compatibility and dropped before the request reaches the provider." } ], "description": "One entry of `tools[]`, told apart by `type`." }, "ChatToolCall": { "type": "object", "description": "One tool call the model made, with every key present at once.", "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string", "description": "The call's id, repeated as `tool_call_id` on the answering message." }, "type": { "type": "string", "description": "What kind of call this is. Always `function`.", "example": "function" }, "function": { "allOf": [ { "$ref": "#/components/schemas/ChatToolCallFunction" } ], "description": "Which function to call, and with what arguments." } } }, "ChatToolCallFunction": { "type": "object", "description": "The function a tool call names, and its arguments.", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "description": "The name of the function to call, as declared in `tools[]`." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as JSON in a string. Valid JSON is not guaranteed." } } }, "ChatToolChoice": { "oneOf": [ { "type": "object", "description": "`{\"type\": \"function\", \"function\": {\"name\": \"…\"}}` to force one named function, or `{\"type\": \"allowed_tools\", \"allowed_tools\": {\"mode\": \"…\", \"tools\": [...]}}` to confine the model to a named subset of `tools[]`.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, { "type": "string", "title": "Plain text", "description": "One of `none`, `auto` or `required`; any other string draws a refusal." } ], "description": "Which tool, if any, the model calls. A `custom` choice reads as if the key were absent." }, "ChatUsage": { "type": "object", "description": "What the provider counted this request at. The bill counts separately.", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "prompt_tokens_details", "completion_tokens_details" ], "properties": { "prompt_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the prompt, cached ones included." }, "completion_tokens": { "type": "integer", "format": "int64", "description": "Tokens the model generated, reasoning and image tokens included." }, "total_tokens": { "type": "integer", "format": "int64", "description": "The provider's own total for the request, reported as received." }, "prompt_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/ChatPromptTokensDetails" } ], "description": "The split of `prompt_tokens` the provider reported." }, "completion_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionTokensDetails" } ], "description": "The split of `completion_tokens` the provider reported." } } }, "CodeInterpreterTool": { "type": "object", "description": "A hosted tool the gateway takes and drops. `container` is still required.", "required": [ "container" ], "properties": { "container": { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterToolContainer" } ], "description": "Which sandbox the code would run in." } } }, "CodeInterpreterToolContainer": { "oneOf": [ { "type": "object", "description": "A sandbox described inline. The gateway reads nothing inside it.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, { "type": "string", "title": "Plain text", "description": "The id of an existing sandbox, which the gateway never looks up." } ], "description": "Where the code would run: a sandbox to make, or the id of one." }, "ComputerEnvironment": { "type": "string", "description": "Which kind of machine a computer-use tool would drive.", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ] }, "ComputerUseTool": { "type": "object", "description": "A hosted tool the gateway takes and drops. All three keys are still required.", "required": [ "display_height", "display_width", "environment" ], "properties": { "display_height": { "type": "number", "format": "double", "description": "How tall the virtual display would be." }, "display_width": { "type": "number", "format": "double", "description": "How wide the virtual display would be." }, "environment": { "allOf": [ { "$ref": "#/components/schemas/ComputerEnvironment" } ], "description": "Which kind of machine would be driven." } } }, "ContentBlockParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextBlockParam" } ], "description": "A run of plain text. Accepted on both roles." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "A run of plain text. Accepted on both roles." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageBlockParam" } ], "description": "An image. Input for the model in a `user` message; an echo of a generated image in an `assistant` message." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image`.", "enum": [ "image" ] } } } ], "description": "An image. Input for the model in a `user` message; an echo of a generated image in an `assistant` message." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/DocumentBlockParam" } ], "description": "A document handed to the model as input. `user` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `document`.", "enum": [ "document" ] } } } ], "description": "A document handed to the model as input. `user` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/SearchResultBlockParam" } ], "description": "A search result handed to the model as input, with its own source and title. `user` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `search_result`.", "enum": [ "search_result" ] } } } ], "description": "A search result handed to the model as input, with its own source and title. `user` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ThinkingBlockParam" } ], "description": "The model's reasoning, replayed. `assistant` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `thinking`.", "enum": [ "thinking" ] } } } ], "description": "The model's reasoning, replayed. `assistant` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/RedactedThinkingBlockParam" } ], "description": "Redacted reasoning, replayed; what it signs depends on where it sits. `assistant` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `redacted_thinking`.", "enum": [ "redacted_thinking" ] } } } ], "description": "Redacted reasoning, replayed; what it signs depends on where it sits. `assistant` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolUseBlockParam" } ], "description": "A client tool call the model made, replayed. `assistant` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_use`.", "enum": [ "tool_use" ] } } } ], "description": "A client tool call the model made, replayed. `assistant` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolResultBlockParam" } ], "description": "The answer to one earlier `tool_use`. `user` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_result`.", "enum": [ "tool_result" ] } } } ], "description": "The answer to one earlier `tool_use`. `user` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ServerToolUseBlockParam" } ], "description": "A server-side tool call the model made, replayed. Acted on only when it names `web_search`. `assistant` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `server_tool_use`.", "enum": [ "server_tool_use" ] } } } ], "description": "A server-side tool call the model made, replayed. Acted on only when it names `web_search`. `assistant` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolResultBlockParam" } ], "description": "What a replayed `web_search` call returned. `assistant` messages only." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_tool_result`.", "enum": [ "web_search_tool_result" ] } } } ], "description": "What a replayed `web_search` call returned. `assistant` messages only." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A replayed hosted web-fetch result. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_fetch_tool_result`.", "enum": [ "web_fetch_tool_result" ] } } } ], "description": "A replayed hosted web-fetch result. Accepted on either role and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A replayed hosted code-execution result. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `code_execution_tool_result`.", "enum": [ "code_execution_tool_result" ] } } } ], "description": "A replayed hosted code-execution result. Accepted on either role and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A replayed hosted bash code-execution result. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `bash_code_execution_tool_result`.", "enum": [ "bash_code_execution_tool_result" ] } } } ], "description": "A replayed hosted bash code-execution result. Accepted on either role and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A replayed hosted text-editor code-execution result. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text_editor_code_execution_tool_result`.", "enum": [ "text_editor_code_execution_tool_result" ] } } } ], "description": "A replayed hosted text-editor code-execution result. Accepted on either role and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A replayed hosted tool-search result. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_search_tool_result`.", "enum": [ "tool_search_tool_result" ] } } } ], "description": "A replayed hosted tool-search result. Accepted on either role and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A file offered to a hosted execution container. Accepted on either role and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `container_upload`.", "enum": [ "container_upload" ] } } } ], "description": "A file offered to a hosted execution container. Accepted on either role and dropped." } ], "description": "One entry of a message's `content`. The role decides which tags it admits." }, "ContentBlockSourceParam": { "type": "object", "description": "A document assembled inline out of content blocks, checked and then dropped.", "required": [ "content" ], "properties": { "content": { "allOf": [ { "$ref": "#/components/schemas/ContentBlockSourceParamContent" } ], "description": "The document body, as one string or a list of blocks." } } }, "ContentBlockSourceParamContent": { "oneOf": [ { "type": "array", "title": "List of content blocks", "items": { "$ref": "#/components/schemas/DocumentContentBlockParam" }, "description": "The document as a list of text and image blocks, in reading order." }, { "type": "string", "title": "Plain text", "description": "The whole document as a single string, bounded in UTF-8 bytes by 20 MiB." } ], "description": "The body of a `content` document source: one string, or a list of blocks." }, "CustomTool": { "type": "object", "description": "A tool the model calls with one free-form string, carried as a function with an `input` string.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name the model would call the tool by." }, "description": { "type": [ "string", "null" ], "description": "What the tool is for, written for the model." }, "format": { "type": [ "object", "null" ], "description": "The grammar the model's input must obey.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "CustomToolStub": { "type": "object", "description": "OpenAI's free-form-text tool, which the gateway takes and drops." }, "DailyStats": { "type": "object", "description": "One day of the account's usage.", "required": [ "date", "total_requests", "total_cost", "total_input_tokens", "total_output_tokens" ], "properties": { "date": { "type": "string", "description": "The day these totals are for, as `YYYY-MM-DD`." }, "total_requests": { "type": "integer", "format": "int64", "description": "How many requests the account made that day, failed ones included." }, "total_cost": { "type": "string", "description": "What those requests cost in credits, as a decimal string." }, "total_input_tokens": { "type": "integer", "format": "int64", "description": "Input tokens summed over those requests." }, "total_output_tokens": { "type": "integer", "format": "int64", "description": "Output tokens summed over those requests." } } }, "DocumentBlockParam": { "type": "object", "description": "A document handed to the model, and user-side only.", "required": [ "source" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/DocumentSourceParam" } ], "description": "Where the document comes from." }, "title": { "type": [ "string", "null" ], "description": "A name for the document, passed on as its filename." } } }, "DocumentContentBlockParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/DocumentContentTextBlockParam" } ], "description": "`type: \"text\"` — a run of the document's text." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "`type: \"text\"` — a run of the document's text." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageBlockParam" } ], "description": "`type: \"image\"` — a page or figure of the document, given as an image. The full image block shape, so both source forms are available and both are bounded exactly as they are elsewhere." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image`.", "enum": [ "image" ] } } } ], "description": "`type: \"image\"` — a page or figure of the document, given as an image. The full image block shape, so both source forms are available and both are bounded exactly as they are elsewhere." } ], "description": "One entry of a document assembled from content blocks." }, "DocumentContentTextBlockParam": { "type": "object", "description": "A run of text inside a block-assembled document.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text of this block, under 20 MiB in UTF-8." } } }, "DocumentSourceParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/Base64PdfSourceParam" } ], "description": "`type: \"base64\"` — a PDF carried inline, forwarded as a `data:` URI." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `base64`.", "enum": [ "base64" ] } } } ], "description": "`type: \"base64\"` — a PDF carried inline, forwarded as a `data:` URI." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/UrlPdfSourceParam" } ], "description": "`type: \"url\"` — a PDF named by a URL, forwarded as that URL." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `url`.", "enum": [ "url" ] } } } ], "description": "`type: \"url\"` — a PDF named by a URL, forwarded as that URL." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/PlainTextSourceParam" } ], "description": "`type: \"text\"` — plain text, which the gateway base64-encodes into a `data:text/plain` URI before forwarding." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "`type: \"text\"` — plain text, which the gateway base64-encodes into a `data:text/plain` URI before forwarding." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ContentBlockSourceParam" } ], "description": "`type: \"content\"` — an inline assembly of blocks, accepted, validated and then dropped along with its `document` block." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `content`.", "enum": [ "content" ] } } } ], "description": "`type: \"content\"` — an inline assembly of blocks, accepted, validated and then dropped along with its `document` block." } ], "description": "Where a `document` block's content comes from. Three of the four forms travel on." }, "DroppedChoiceType": { "type": "string", "description": "The tool families a choice may name that the gateway does not run.", "enum": [ "custom", "file_search", "computer", "computer_use_preview", "computer_use", "image_generation", "code_interpreter", "mcp", "apply_patch", "shell" ] }, "EmbeddingDataResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "index", "embedding" ], "properties": { "object": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingDataResponseObject" } ], "description": "Always `embedding`." }, "index": { "type": "integer", "format": "int64", "description": "Which of the request's inputs this vector belongs to, counted from zero." }, "embedding": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingDataResponseEmbedding" } ], "description": "The vector: an array of numbers, or base64 when the request asked for it." } } } ], "description": "One embedded input: its place, and the vector it produced." }, "EmbeddingDataResponseEmbedding": { "oneOf": [ { "type": "array", "title": "Float vector", "items": { "type": "number", "format": "double" } }, { "type": "string", "title": "Base64 string" } ], "description": "A vector, in the form `encoding_format` asked for." }, "EmbeddingDataResponseObject": { "type": "string", "description": "What kind of row this entry is. Always `embedding`.", "enum": [ "embedding" ] }, "EmbeddingUsageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "prompt_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "format": "int64", "description": "The tokens of the input, and what the request bills on." }, "total_tokens": { "type": "integer", "format": "int64", "description": "The same number as `prompt_tokens`; embeddings produce no output tokens." } } } ], "description": "What the gateway metered; embeddings produce no output." }, "Embeddings": { "type": "object", "description": "The request body of `POST /v1/embeddings`.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The model to embed with, named by its id or alias. An entry without the `embeddings` capability draws a refusal." }, "input": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingsInput" } ], "description": "What to embed: strings, token ids, or arrays of either." }, "dimensions": { "type": [ "integer", "null" ], "format": "int64", "description": "The vector length to ask for. The gateway bounds nothing and drops the key where the provider has no such parameter." }, "encoding_format": { "allOf": [ { "$ref": "#/components/schemas/EncodingFormat" } ], "description": "How the vectors come back. `base64` costs precision, since the gateway holds them as 64-bit.", "default": "float" } } }, "EmbeddingsInput": { "oneOf": [ { "type": "string", "title": "Plain text" }, { "type": "array", "title": "List of texts", "items": { "type": "string" } }, { "type": "array", "title": "List of token ids", "items": { "type": "integer", "format": "int64" } }, { "type": "array", "title": "List of token-id sequences", "items": { "type": "array", "items": { "type": "integer", "format": "int64" } } } ], "description": "What to embed, in one of four shapes. An empty array fails validation here, though the route takes it." }, "EmbeddingsResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "model", "data", "usage" ], "properties": { "object": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingsResponseObject" } ], "description": "Always `list`." }, "model": { "type": "string", "description": "The catalog id of the model that answered, after alias resolution." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingDataResponse" }, "description": "The vectors, one entry per embedded input, each carrying its own `index`." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/EmbeddingUsageResponse" } ], "description": "The token count this request bills on." } } } ], "description": "The answer to `POST /v1/embeddings`: one vector per input." }, "EmbeddingsResponseObject": { "type": "string", "description": "What kind of envelope the embeddings response is. Always `list`.", "enum": [ "list" ] }, "EncodingFormat": { "type": "string", "description": "How an embedding vector arrives in the answer.", "enum": [ "float", "base64" ] }, "ErrorBody": { "type": "object", "description": "The `error` member: what went wrong, in the caller's terms.", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "description": "The class of the failure; a provider's own class can reach you unchanged.", "examples": [ "invalid_request_error", "authentication_required", "invalid_api_key", "invalid_provisioning_key", "invalid_session_token", "disabled_api_key", "disabled_provisioning_key", "expired_api_key", "credit_limit_exceeded", "rate_limit_exceeded", "model_deprecated", "inappropriate_content", "billing_metering_incomplete", "billing_request_id_invalid", "billing_writer_missing", "server_error" ] }, "message": { "type": "string", "description": "The human-readable sentence shown to the caller." }, "code": { "type": [ "string", "null" ], "description": "The finer-grained code, when the failure has one." }, "param": { "type": [ "string", "null" ], "description": "The request field the failure is about, when it is about one." } } }, "ErrorEnvelope": { "type": "object", "description": "`{\"error\": {…}}` — the body of every non-2xx answer outside `/v1/messages`.", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" } ], "description": "The failure itself, and the envelope's only member." } } }, "File": { "type": "object", "description": "A file handed to the model. One of `file_id`, `file_data` and `file_url` must be there.", "properties": { "filename": { "type": [ "string", "null" ], "description": "The name the file is presented under when it reaches the model." }, "file_data": { "type": [ "string", "null" ], "description": "The file inline as a `data:` URI, or an `http(s)` URL, under 20 MiB." }, "file_url": { "type": [ "string", "null" ], "description": "An `http(s)` URL naming the file. A NagaAI extension, dropped where a provider takes no URL." }, "file_id": { "type": [ "string", "null" ], "description": "The id of a file uploaded earlier." } } }, "FileContent": { "type": "object", "description": "A file content part: a document handed to the model.", "required": [ "file" ], "properties": { "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file and the reference that names it." } } }, "FileSearchTool": { "type": "object", "description": "A hosted tool the gateway takes and drops. `vector_store_ids` is still required.", "required": [ "vector_store_ids" ], "properties": { "vector_store_ids": { "type": "array", "items": { "type": "string" }, "description": "Which stores would be searched, named by id. Required." }, "filters": { "description": "A condition results would satisfy." }, "max_num_results": { "type": [ "integer", "null" ], "format": "int64", "description": "How many passages the search would return at most." }, "ranking_options": { "type": [ "object", "null" ], "description": "How results would be ranked.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "FunctionCallOutputContentPart": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputTextPart" } ], "description": "A run of plain text the tool returned." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_text`.", "enum": [ "input_text" ] } } } ], "description": "A run of plain text the tool returned." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputImagePart" } ], "description": "An image the tool returned, handed on to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_image`.", "enum": [ "input_image" ] } } } ], "description": "An image the tool returned, handed on to the model." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputFilePart" } ], "description": "A file the tool returned, handed on to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_file`.", "enum": [ "input_file" ] } } } ], "description": "A file the tool returned, handed on to the model." } ], "description": "One entry of a function call output, narrower than a message's content." }, "FunctionCallOutputOutput": { "oneOf": [ { "type": "array", "title": "List of output parts", "items": { "$ref": "#/components/schemas/FunctionCallOutputContentPart" }, "description": "An array of result parts: `input_text`, `input_image` and `input_file`." }, { "type": "string", "title": "Plain text", "description": "The whole result as one string. A function that returns JSON sends it this way, as text." } ], "description": "What a function returned: a string, or content parts." }, "FunctionDefinition": { "type": "object", "description": "A function the model may call, carried in the provider's own tool shape.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name the model calls the function by, never empty." }, "description": { "type": [ "string", "null" ], "description": "What the function does, written for the model to choose by." }, "parameters": { "type": [ "object", "null" ], "description": "The arguments the function accepts, as a JSON Schema, compiled at intake.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model follows `parameters` exactly when filling the arguments." } } }, "FunctionTool": { "type": "object", "description": "A function the caller implements. Its four keys may be flat or nested, and each flat key wins.", "properties": { "name": { "type": [ "string", "null" ], "description": "What the model calls the function by." }, "description": { "type": [ "string", "null" ], "description": "What the function does, written for the model. Falls back to `function.description`." }, "parameters": { "type": [ "object", "null" ], "description": "The arguments the function accepts, as a JSON Schema, compiled at intake.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model follows `parameters` exactly." }, "function": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/NestedFunctionTool" } ], "description": "The same declaration written the chat-style way; the flat keys win." }, { "type": "null" } ] } } }, "HostedBlockParam": { "type": "object", "description": "The body of a hosted server-tool block, and deliberately empty." }, "HostedInputItemStub": { "type": "object", "description": "The empty shape behind the input items the gateway accepts without acting on." }, "HostedToolParam": { "type": "object", "description": "Any `tools[]` entry this dialect gives no shape of its own. `type` alone decides its fate.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag deciding which of the three outcomes this entry meets. Required." }, "name": { "type": [ "string", "null" ], "description": "The name of the tool. Required for `\"type\": \"custom\"`." } }, "additionalProperties": { "description": "Every other key of the entry, kept as it arrived." } }, "HostedToolStub": { "type": "object", "description": "The empty body shared by four hosted tools the gateway takes but does not serve." }, "HostedWebSearchChoiceType": { "type": "string", "description": "Which spelling of the hosted web search a choice names.", "enum": [ "web_search", "web_search_preview", "web_search_preview_2025_03_11" ] }, "ImageBackground": { "type": "string", "description": "What lies behind the subject of a generated image.", "enum": [ "transparent", "opaque", "auto" ] }, "ImageBlockParam": { "type": "object", "description": "One image handed to the model, or one it produced on an `assistant` turn.", "required": [ "source" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/ImageSourceParam" } ], "description": "Where the picture comes from." } } }, "ImageConfig": { "type": "object", "description": "Sizing knobs for image output. A NagaAI extension the gateway drops.", "properties": { "aspect_ratio": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AspectRatio" } ], "description": "Requested width-to-height ratio. Accepted and dropped; it reaches no provider." }, { "type": "null" } ] }, "image_size": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatImageSize" } ], "description": "Requested resolution tier. Accepted and dropped; it reaches no provider." }, { "type": "null" } ] } } }, "ImageContent": { "type": "object", "description": "An image content part: one image handed to the model.", "required": [ "image_url" ], "properties": { "image_url": { "allOf": [ { "$ref": "#/components/schemas/ImageUrl" } ], "description": "The image reference and its detail level." } } }, "ImageContentPart": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageEchoContent" } ], "description": "The image reference itself." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image_url`.", "enum": [ "image_url" ] } } } ], "description": "The image reference itself." } ], "description": "One entry of a message's `images`. A NagaAI extension carrying images beside `content`." }, "ImageDataResponse": { "allOf": [ { "type": "object" }, { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "description": "A link to the image, hosted by NagaAI rather than by the provider. No expiry is set." }, "b64_json": { "type": [ "string", "null" ], "description": "The image bytes themselves, standard base64. This branch stores nothing." } } } ], "description": "One produced image; exactly one of the two fields is filled." }, "ImageDetail": { "type": "string", "description": "How much detail the model spends on an image.", "enum": [ "auto", "low", "high" ] }, "ImageEchoContent": { "type": "object", "description": "An image echoed back with the signature that continues it.", "required": [ "image_url" ], "properties": { "image_url": { "allOf": [ { "$ref": "#/components/schemas/ImageUrl" } ], "description": "The image reference and its detail level." }, "signature": { "type": [ "string", "null" ], "description": "The token that continues this image on a later turn." }, "format": { "type": [ "string", "null" ], "description": "Which vocabulary the token is written in." } } }, "ImageGenerationModel": { "type": "string", "description": "Which image model the hosted tool would run. Only two spellings parse.", "enum": [ "gpt-image-1", "gpt-image-1-mini" ] }, "ImageGenerationSize": { "type": "string", "description": "The pixel dimensions a generated image would carry. Only four spellings parse.", "enum": [ "1024x1024", "1024x1536", "1536x1024", "auto" ] }, "ImageGenerationTool": { "type": "object", "description": "A hosted tool the gateway takes and drops. A misspelled setting still draws a 400.", "properties": { "background": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageBackground" } ], "description": "Whether the background is see-through, filled, or the model's choice." }, { "type": "null" } ] }, "input_fidelity": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputFidelity" } ], "description": "How closely the result follows the supplied images." }, { "type": "null" } ] }, "input_image_mask": { "type": [ "object", "null" ], "description": "A mask marking the region to repaint.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "model": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationModel" } ], "description": "Which image model would do the drawing." }, { "type": "null" } ] }, "moderation": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageModeration" } ], "description": "How strictly what is drawn would be filtered." }, { "type": "null" } ] }, "output_compression": { "type": [ "number", "null" ], "format": "double", "description": "How hard the produced file would be compressed." }, "output_format": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageOutputFormat" } ], "description": "The file format the produced image would be encoded in." }, { "type": "null" } ] }, "partial_images": { "type": [ "number", "null" ], "format": "double", "description": "How many half-finished frames would be streamed." }, "quality": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageQuality" } ], "description": "How much rendering effort would go into the picture." }, { "type": "null" } ] }, "size": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationSize" } ], "description": "The pixel dimensions the picture would have." }, { "type": "null" } ] } } }, "ImageMediaType": { "type": "string", "description": "The format of an image sent inline. Four formats are the whole menu.", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ] }, "ImageModeration": { "type": "string", "description": "How strictly the hosted tool would filter what it draws.", "enum": [ "auto", "low" ] }, "ImageOutputFormat": { "type": "string", "description": "The file format a generated image would carry.", "enum": [ "png", "webp", "jpeg" ] }, "ImageQuality": { "type": "string", "description": "How much rendering effort the hosted tool would spend.", "enum": [ "low", "medium", "high", "auto" ] }, "ImageResponseFormat": { "type": "string", "description": "How the produced images are handed back.", "enum": [ "url", "b64_json" ] }, "ImageSourceParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/Base64ImageSourceParam" } ], "description": "`type: \"base64\"` — the image bytes travel inside the request." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `base64`.", "enum": [ "base64" ] } } } ], "description": "`type: \"base64\"` — the image bytes travel inside the request." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/UrlImageSourceParam" } ], "description": "`type: \"url\"` — the image is named, and fetched by whoever renders it." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `url`.", "enum": [ "url" ] } } } ], "description": "`type: \"url\"` — the image is named, and fetched by whoever renders it." } ], "description": "Where an `image` block's picture comes from." }, "ImageUrl": { "type": "object", "description": "The image an `image_url` part points at.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Where the image lives: an `http(s)` URL, or a `data:` URI under 20 MiB." }, "detail": { "allOf": [ { "$ref": "#/components/schemas/ChatImageDetail" } ], "description": "How much detail to spend on this image.", "default": "auto" } } }, "ImageUrlInput": { "type": "object", "description": "An image part of a typed-parts `input` array.", "required": [ "type", "image_url" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/ImageUrlTag" } ], "description": "Always the literal `image_url`, and what selects this part shape." }, "image_url": { "allOf": [ { "$ref": "#/components/schemas/ModerationImageUrl" } ], "description": "The image to moderate." } } }, "ImageUrlTag": { "type": "string", "description": "The tag of an image part.", "enum": [ "image_url" ] }, "ImageUsageResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "output_tokens", "total_tokens" ], "properties": { "input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Input tokens charged for. Zero on a model that prices no input text token." }, "output_tokens": { "type": "integer", "format": "int64", "description": "Output tokens charged for the produced images, 2048 apiece where the provider counted none." }, "total_tokens": { "type": "integer", "format": "int64", "description": "The sum of `input_tokens` and `output_tokens`." } } } ], "description": "What the gateway metered, in its own numbers." }, "ImagesGenerationsRequest": { "type": "object", "description": "The request body of `POST /v1/images/generations`.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "The model to generate with, named by its id or alias." }, "prompt": { "type": "string", "description": "What to generate, in words. One to 8192 characters, and moderation screens it first." }, "quality": { "type": [ "string", "null" ], "description": "The provider's quality knob, passed through unchecked. A provider without one drops it." }, "size": { "type": [ "string", "null" ], "description": "The requested image size, written `{width}x{height}`; any other shape draws a refusal." }, "n": { "type": [ "integer", "null" ], "format": "int64", "description": "How many images to ask for. Absent means one; a value above what the model declares draws a refusal." }, "response_format": { "allOf": [ { "$ref": "#/components/schemas/ImageResponseFormat" } ], "description": "Whether each image comes back as a link (`url`) or as inline base64 (`b64_json`).", "default": "url" } } }, "ImagesResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "created", "data", "usage" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "When the gateway rendered this body, in seconds since the Unix epoch." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageDataResponse" }, "description": "The produced images, in the order the provider returned them." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/ImageUsageResponse" } ], "description": "What the gateway metered, filling in where the provider reported nothing." } } } ], "description": "The body both image routes answer with." }, "InputAudio": { "type": "object", "description": "Audio handed to the model: the bytes, and their encoding.", "required": [ "data", "format" ], "properties": { "data": { "type": "string", "description": "The audio as bare base64, under 20 MiB." }, "format": { "allOf": [ { "$ref": "#/components/schemas/InputAudioFormat" } ], "description": "The encoding of the base64 payload." } } }, "InputAudioFormat": { "type": "string", "description": "The encoding of an inline audio part. Seven of the nine are a NagaAI extension.", "enum": [ "wav", "mp3", "aiff", "aac", "ogg", "flac", "m4a", "pcm16", "pcm24" ] }, "InputAudioPart": { "type": "object", "description": "Audio handed to the model on a `user` turn.", "required": [ "input_audio" ], "properties": { "input_audio": { "type": "object", "description": "The audio and its encoding; nine encodings count, seven a NagaAI extension.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "InputCustomToolCall": { "type": "object", "description": "A replayed call to a `custom` tool: the model's free-form string input.", "required": [ "call_id", "name" ], "properties": { "call_id": { "type": "string", "description": "The identifier a matching `custom_tool_call_output` repeats." }, "name": { "type": "string", "description": "The name of the custom tool the model called." }, "input": { "type": "string", "description": "The string the model wrote for the tool." }, "namespace": { "type": [ "string", "null" ], "description": "The `namespace` tool the custom tool belongs to, when it came from one." }, "id": { "type": [ "string", "null" ], "description": "An identifier for the call item, distinct from `call_id`." } } }, "InputCustomToolCallOutput": { "type": "object", "description": "The result of a replayed `custom` tool call.", "required": [ "call_id", "output" ], "properties": { "call_id": { "type": "string", "description": "The `call_id` of the call this answers." }, "output": { "allOf": [ { "$ref": "#/components/schemas/FunctionCallOutputOutput" } ], "description": "What the tool returned: a string or content parts." } } }, "InputFidelity": { "type": "string", "description": "How closely a generated image follows the supplied ones.", "enum": [ "high", "low" ] }, "InputFilePart": { "type": "object", "description": "A file handed to the model. One of `file_id`, `file_data` and `file_url` must be there.", "properties": { "filename": { "type": [ "string", "null" ], "description": "The name the file reaches the model under." }, "file_data": { "type": [ "string", "null" ], "description": "The file inline under 20 MiB, or an `http(s)` URL." }, "file_url": { "type": [ "string", "null" ], "description": "An `http(s)` URL naming the file; this slot takes no `data:` URI." }, "file_id": { "type": [ "string", "null" ], "description": "The id of a file uploaded earlier." }, "input_file": { "type": [ "object", "null" ], "description": "The same four file keys nested in one object. A NagaAI extension.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "InputFunctionCall": { "type": "object", "description": "A function call the model made earlier, replayed as history.", "required": [ "call_id", "name" ], "properties": { "call_id": { "type": "string", "description": "The identifier a matching `function_call_output` repeats. The gateway refuses an empty string." }, "name": { "type": "string", "description": "The name of the function the model asked to run." }, "arguments": { "type": "string", "description": "The arguments the model produced, as a JSON string. Absent means `\"\"`." }, "id": { "type": [ "string", "null" ], "description": "An identifier for the call item, distinct from `call_id`." }, "status": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "The lifecycle state this call carried. The gateway never acts on it." }, { "type": "null" } ] }, "namespace": { "type": [ "string", "null" ], "description": "The `namespace` tool the function belongs to, when it came from one." } } }, "InputFunctionCallOutput": { "type": "object", "description": "The result of a function call, attached by `call_id`.", "required": [ "call_id" ], "properties": { "call_id": { "type": "string", "description": "The `call_id` of the `function_call` this answers." }, "output": { "allOf": [ { "$ref": "#/components/schemas/FunctionCallOutputOutput" } ], "description": "What the function returned. Absent means the empty string." }, "id": { "type": [ "string", "null" ], "description": "An identifier for the output item, distinct from `call_id`." }, "status": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "The lifecycle state this result carried. The gateway never acts on it." }, { "type": "null" } ] } } }, "InputImageGenerationCall": { "type": "object", "description": "An image the model generated earlier. Exactly one of `result` and `url` must be set.", "properties": { "id": { "type": [ "string", "null" ], "description": "An identifier for this item, matched by a sibling `reasoning` item's `id`." }, "status": { "type": [ "string", "null" ], "description": "The state the generation carried, taken as given." }, "result": { "type": [ "string", "null" ], "description": "The image as bare base64, under 20 MiB, and an alternative to `url`." }, "created_by": { "type": [ "string", "null" ], "description": "What created the item. The gateway drops it." }, "url": { "type": [ "string", "null" ], "description": "Where the image lives when the request carried no bytes." }, "mime_type": { "type": [ "string", "null" ], "description": "The media type of the bytes in `result`. A NagaAI extension." } } }, "InputImagePart": { "type": "object", "description": "An image handed to the model. One of `image_url` and `file_id` must be there.", "properties": { "image_url": { "type": [ "string", "null" ], "description": "Where the image lives, inline under 20 MiB or by URL." }, "file_id": { "type": [ "string", "null" ], "description": "The id of a file uploaded earlier." }, "detail": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageDetail" } ], "description": "How much detail the model spends on this image." }, { "type": "null" } ] } } }, "InputMessage": { "type": "object", "description": "One conversational turn in the input list. A turn with no content draws a refusal.", "required": [ "role" ], "properties": { "role": { "allOf": [ { "$ref": "#/components/schemas/InputMessageRole" } ], "description": "Whose turn this is, and what it may carry." }, "content": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputMessageContent" } ], "description": "What the turn says. The gateway refuses a message without it." }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ], "description": "A name for the speaker. The gateway drops it." }, "id": { "type": [ "string", "null" ], "description": "An identifier for this item. The gateway looks nothing up by it." }, "status": { "type": [ "string", "null" ], "description": "The lifecycle state a replayed item carried, never acted on." }, "phase": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessagePhase" } ], "description": "Whether an assistant turn is commentary or the final answer." }, { "type": "null" } ] } } }, "InputMessageContent": { "oneOf": [ { "type": "array", "title": "List of content parts", "items": { "$ref": "#/components/schemas/ResponseContentPart" }, "description": "An array of content parts, in the order given. The role decides which parts it admits." }, { "type": "string", "title": "Plain text", "description": "The whole message as one string. This is the short form of a single text part, and it covers a turn whose content is entirely text." } ], "description": "What a message says: a run of text, or parts." }, "InputMessageRole": { "type": "string", "description": "Which voice a turn speaks in.", "enum": [ "user", "assistant", "system", "developer" ] }, "InputReasoningItem": { "type": "object", "description": "A block of the model's own reasoning from an earlier turn. Its continuation token means nothing to another model family.", "properties": { "id": { "type": [ "string", "null" ], "description": "An identifier for this reasoning block, matched against a sibling call." }, "content": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "The reasoning text, as `reasoning_text` entries. Absent means an empty array." }, "summary": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "The reasoning summary, as `summary_text` entries. Its absence draws a refusal." }, "encrypted_content": { "type": [ "string", "null" ], "description": "The opaque continuation token, sent back unchanged and never decoded here." }, "status": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "The lifecycle state this block carried. The gateway never acts on it." }, { "type": "null" } ] }, "format": { "type": [ "string", "null" ], "description": "Which model family issued these continuation tokens. A NagaAI extension." }, "signature": { "type": [ "string", "null" ], "description": "A second slot for the same continuation token. A NagaAI extension." } } }, "InputTextPart": { "type": "object", "description": "A run of plain text handed to the model.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text of this part." } } }, "InputToolSearchCall": { "type": "object", "description": "A replayed client-side tool search the model asked for.", "required": [ "call_id" ], "properties": { "call_id": { "type": "string", "description": "The identifier a matching `tool_search_output` repeats." }, "arguments": { "description": "The search the model asked for, as an object." } } }, "InputToolSearchOutput": { "type": "object", "description": "The tools a client-side tool search loaded, offered from this point on.", "required": [ "call_id" ], "properties": { "call_id": { "type": "string", "description": "The `call_id` of the search this answers." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseTool" }, "description": "The loaded tools, in the shape of `tools[]` entries." } } }, "ItemReference": { "type": "object", "description": "A pointer to a stored item. The gateway stores none and refuses it.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The id of the item being pointed at, never resolved." } } }, "ItemStatus": { "type": "string", "description": "The lifecycle state of an item replayed as history.", "enum": [ "in_progress", "completed", "incomplete" ] }, "JsonObjectResponseFormat": { "type": "object", "description": "The older JSON mode: valid JSON, no schema behind it." }, "JsonSchemaConfig": { "type": "object", "description": "The JSON Schema a reply must satisfy, with its name and strictness.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of this response format, never empty." }, "description": { "type": [ "string", "null" ], "description": "What the format is for, written for the model." }, "schema": { "type": [ "object", "null" ], "description": "The JSON Schema the reply must conform to. A keyword the provider's dialect refuses travels no further.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model is held to the schema exactly." } } }, "JsonSchemaResponseFormat": { "type": "object", "description": "Structured Outputs: JSON built to the schema in `json_schema`.", "required": [ "json_schema" ], "properties": { "json_schema": { "allOf": [ { "$ref": "#/components/schemas/JsonSchemaConfig" } ], "description": "The schema the reply is built to, with its name and strictness." } } }, "LocalShellTool": { "type": "object", "description": "A hosted tool the gateway takes and drops." }, "McpTool": { "type": "object", "description": "A hosted tool the gateway takes and drops, `authorization` included.", "required": [ "server_label" ], "properties": { "server_label": { "type": "string", "description": "A short name for the server. Required." }, "allowed_tools": { "description": "Which of the server's tools the model could call." }, "authorization": { "type": [ "string", "null" ], "description": "An OAuth access token for the server." }, "connector_id": { "type": [ "string", "null" ], "description": "Which first-party connector to use instead of a URL." }, "headers": { "type": [ "object", "null" ], "description": "Extra HTTP headers that would reach the server.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "require_approval": { "description": "Which of the server's tools would need approval." }, "server_description": { "type": [ "string", "null" ], "description": "Free text about the server, meant for the model." }, "server_url": { "type": [ "string", "null" ], "description": "Where the server lives." } } }, "MessageParam": { "type": "object", "description": "One turn of the conversation: who was speaking, and what they said.", "required": [ "role", "content" ], "properties": { "role": { "allOf": [ { "$ref": "#/components/schemas/MessageRole" } ], "description": "Whose turn this is, and what blocks it may carry." }, "content": { "allOf": [ { "$ref": "#/components/schemas/MessageParamContent" } ], "description": "What was said — one string, or at least one content block." } } }, "MessageParamContent": { "oneOf": [ { "type": "array", "title": "List of content blocks", "items": { "$ref": "#/components/schemas/ContentBlockParam" }, "description": "The turn as an ordered list of content blocks, one entry at least." }, { "type": "string", "title": "Plain text", "description": "The turn as one run of plain text, equivalent to a list holding a single `text` block." } ], "description": "What a message says: one string, or an ordered list of content blocks." }, "MessagePhase": { "type": "string", "description": "Which pass of a two-pass answer the turn is.", "enum": [ "commentary", "final_answer" ] }, "MessageRole": { "type": "string", "description": "Which side of the conversation a message comes from.", "enum": [ "user", "assistant", "system" ] }, "MessagesBlockDelta": { "oneOf": [ { "type": "object", "description": "The next slice of a `thinking` block's reasoning text.", "required": [ "thinking", "type" ], "properties": { "thinking": { "type": "string", "description": "The text to append." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `thinking_delta`.", "enum": [ "thinking_delta" ] } } }, { "type": "object", "description": "The signature of a `thinking` block, which arrives once, whole, when the block closes.", "required": [ "signature", "type" ], "properties": { "signature": { "type": "string", "description": "The signature. Not a slice: it replaces nothing and is appended to nothing." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `signature_delta`.", "enum": [ "signature_delta" ] } } }, { "type": "object", "description": "The next slice of a `tool_use` block's arguments.", "required": [ "partial_json", "type" ], "properties": { "partial_json": { "type": "string", "description": "The next piece of the argument JSON; no piece is valid JSON alone." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_json_delta`.", "enum": [ "input_json_delta" ] } } }, { "type": "object", "description": "The next slice of a `text` block.", "required": [ "text", "type" ], "properties": { "text": { "type": "string", "description": "The text to append. It can be a fragment of a word." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text_delta`.", "enum": [ "text_delta" ] } } } ], "description": "What a `content_block_delta` frame appends to the block it names." }, "MessagesCaller": { "type": "object", "description": "Who invoked a tool. Always the model of this turn.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "How the call was reached. Always `direct`." } } }, "MessagesContentBlock": { "oneOf": [ { "type": "object", "description": "Reasoning the model is willing to show, together with the signature that lets it be replayed.", "required": [ "thinking", "signature", "type" ], "properties": { "thinking": { "type": "string", "description": "The reasoning, as text meant to be read." }, "signature": { "type": "string", "description": "An opaque token vouching for the reasoning it accompanies, replayed unchanged." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `thinking`.", "enum": [ "thinking" ] } } }, { "type": "object", "description": "Reasoning kept from view — the model reasoned, and what it reasoned is available only as an opaque blob.", "required": [ "data", "type" ], "properties": { "data": { "type": "string", "description": "The reasoning in opaque form, replayed unchanged on a later turn." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `redacted_thinking`.", "enum": [ "redacted_thinking" ] } } }, { "type": "object", "description": "A piece of the answer's prose.", "required": [ "text", "citations", "type" ], "properties": { "text": { "type": "string", "description": "The text itself." }, "citations": { "type": "null", "description": "Always `null`. Citations are not attached to text on this gateway, and the key stays because the Anthropic block carries it." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } }, { "type": "object", "description": "A tool call for you to run: the model has stopped and is waiting for the result.", "required": [ "id", "name", "input", "caller", "type" ], "properties": { "id": { "type": "string", "description": "The call's id, repeated as `tool_use_id` on the block carrying the result." }, "name": { "type": "string", "description": "Which of your tools to call, by the name you declared it under." }, "input": { "description": "The arguments to call it with, as an object. They are never checked against the tool's own schema, so a model can produce arguments the schema does not declare." }, "caller": { "allOf": [ { "$ref": "#/components/schemas/MessagesCaller" } ], "description": "Who made the call." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_use`.", "enum": [ "tool_use" ] } } }, { "type": "object", "description": "A tool call the provider ran itself. Nothing is asked of you: the result arrives in a later block of the same turn.", "required": [ "id", "name", "input", "caller", "type" ], "properties": { "id": { "type": "string", "description": "The call's id, which the matching result block quotes." }, "name": { "type": "string", "description": "Which server-side tool ran. Always `web_search` — it is the only one this gateway serves." }, "input": { "allOf": [ { "$ref": "#/components/schemas/MessagesWebSearchInput" } ], "description": "What the tool was called with." }, "caller": { "allOf": [ { "$ref": "#/components/schemas/MessagesCaller" } ], "description": "Who made the call." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `server_tool_use`.", "enum": [ "server_tool_use" ] } } }, { "type": "object", "description": "What a server-side search found.", "required": [ "tool_use_id", "content", "caller", "type" ], "properties": { "tool_use_id": { "type": "string", "description": "The id of the `server_tool_use` block this answers." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesWebSearchResult" }, "description": "The pages the search returned." }, "caller": { "allOf": [ { "$ref": "#/components/schemas/MessagesCaller" } ], "description": "Who made the call being answered." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_tool_result`.", "enum": [ "web_search_tool_result" ] } } }, { "type": "object", "description": "An image the model generated.", "required": [ "source", "type" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/MessagesImageSource" } ], "description": "Where to read the image." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image`.", "enum": [ "image" ] } } }, { "type": "object", "description": "A document the model was given to work from, replayed back in the answer. A NagaAI extension, and one that appears on a streamed answer only — the non-streaming body has no path that produces it.", "required": [ "source", "title", "content", "citations", "type" ], "properties": { "source": { "type": "string", "description": "Where the document came from." }, "title": { "type": "string", "description": "The document's title." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesSearchResultText" }, "description": "The document's text." }, "citations": { "description": "The citation settings that came with the document, or `null` when it carried none." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `search_result`.", "enum": [ "search_result" ] } } } ], "description": "One block of the answer's content, in the order the model produced it." }, "MessagesDeltaUsage": { "type": "object", "description": "What the request cost in tokens, as reported at the end of a stream.", "required": [ "output_tokens", "input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "server_tool_use", "output_tokens_details" ], "properties": { "output_tokens": { "type": "integer", "format": "int64", "description": "Tokens the model generated over the whole turn." }, "input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens of the prompt read fresh, cache reads excluded, or `null`." }, "cache_creation_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens written into the prompt cache, or `null`." }, "cache_read_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens served out of the prompt cache, or `null`." }, "server_tool_use": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessagesServerToolUsage" } ], "description": "How many times server-side tools ran, or `null` when none did." }, { "type": "null" } ] }, "output_tokens_details": { "type": "null", "description": "Always `null`. The breakdown of `output_tokens` into thinking tokens and the rest is not surfaced. `output_tokens` is the total that counts." } } }, "MessagesErrorBody": { "type": "object", "description": "What went wrong.", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "description": "The class of the failure; anything the gateway cannot place is `api_error`.", "examples": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "rate_limit_error", "request_too_large", "overloaded_error", "billing_error", "timeout_error", "api_error" ] }, "message": { "type": "string", "description": "What went wrong, in prose meant to be read." } } }, "MessagesErrorEnvelope": { "type": "object", "description": "A failure, in the Anthropic envelope, carrying no `code` and no `param`.", "required": [ "type", "error" ], "properties": { "type": { "type": "string", "description": "What kind of object this is. Always `error`." }, "error": { "allOf": [ { "$ref": "#/components/schemas/MessagesErrorBody" } ], "description": "What went wrong." } } }, "MessagesImageSource": { "oneOf": [ { "type": "object", "description": "The image itself, inline.", "required": [ "media_type", "data", "type" ], "properties": { "media_type": { "type": "string", "description": "The image's media type, `image/png` when the provider named none." }, "data": { "type": "string", "description": "The image's bytes, base64-encoded." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `base64`.", "enum": [ "base64" ] } } }, { "type": "object", "description": "A hosted image, by address.", "required": [ "url", "type" ], "properties": { "url": { "type": "string", "description": "Where the image is served from." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `url`.", "enum": [ "url" ] } } } ], "description": "Where to read an image the model generated." }, "MessagesMessage": { "type": "object", "description": "The answer to a `/v1/messages` request, and the skeleton a stream opens with.", "required": [ "id", "type", "role", "content", "model", "stop_reason", "stop_sequence", "stop_details", "container", "usage" ], "properties": { "id": { "type": "string", "description": "This answer's identifier." }, "type": { "type": "string", "description": "What kind of object this is. Always `message`." }, "role": { "type": "string", "description": "Who wrote it. Always `assistant`." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessagesContentBlock" }, "description": "The answer itself, block by block." }, "model": { "type": "string", "description": "The model that answered, by its id in the NagaAI catalog." }, "stop_reason": { "type": [ "string", "null" ], "description": "Why the model stopped, in one of four values." }, "stop_sequence": { "type": "null", "description": "Always `null`. Stop sequences are not reported back, which is why `stop_reason` is never `stop_sequence` either." }, "stop_details": { "type": "null", "description": "Always `null`. `stop_reason` carries the whole of what is known about why the turn ended." }, "container": { "type": "null", "description": "Always `null`. Code-execution containers are not served." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/MessagesUsage" } ], "description": "What the request cost in tokens." } } }, "MessagesMessageDelta": { "type": "object", "description": "What the `message_delta` frame reports about the finished turn.", "required": [ "stop_reason", "stop_sequence", "stop_details", "container" ], "properties": { "stop_reason": { "type": "string", "description": "Why the model stopped, and never `null` on this frame." }, "stop_sequence": { "type": "null", "description": "Always `null`. Stop sequences are not reported back, which is why `stop_reason` is never `stop_sequence` either." }, "stop_details": { "type": "null", "description": "Always `null`. `stop_reason` carries the whole of what is known about why the turn ended." }, "container": { "type": "null", "description": "Always `null`. Code-execution containers are not served." } } }, "MessagesRequest": { "type": "object", "description": "The Anthropic-compatible Messages request. The gateway takes an unrecognized key and drops it.", "required": [ "model", "max_tokens", "messages" ], "properties": { "model": { "type": "string", "description": "The model to run, named by an id or alias from NagaAI's catalog. An entry without the `chat.completions` capability draws a refusal." }, "max_tokens": { "type": "integer", "format": "int64", "description": "The ceiling on generated tokens. Required, at least 1, and the gateway raises it where the reasoning budget would not fit.", "minimum": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageParam" }, "description": "The conversation so far, oldest first: one to 100000 entries. A block sent under the wrong role draws a refusal.", "maxItems": 100000, "minItems": 1 }, "routing": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingPreferences" } ], "description": "How NagaAI orders the providers for this request. It reorders them and never removes one. A NagaAI extension." }, { "type": "null" } ] }, "system": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessagesSystem" } ], "description": "The system prompt, as one string or as `text` blocks joined in order." }, { "type": "null" } ] }, "stream": { "type": "boolean", "description": "Whether the reply arrives incrementally as the model writes it. An explicit `null` draws a refusal.", "default": false }, "temperature": { "type": [ "number", "null" ], "format": "double", "description": "How much randomness goes into the reply, between 0 and 2. A provider may still refuse a value this range allows.", "maximum": 2, "minimum": 0 }, "top_p": { "type": [ "number", "null" ], "format": "double", "description": "The sampling cut-off, between 0 and 1, and an alternative to `temperature`.", "maximum": 1, "minimum": 0 }, "top_k": { "type": [ "integer", "null" ], "format": "int64", "description": "How many top candidates each token is drawn from. It reaches only some providers." }, "stop_sequences": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Strings that end generation the moment the model produces one. The reply never names which matched." }, "metadata": { "type": [ "object", "null" ], "description": "An object describing the request. Only `user_id` counts, and it reaches only some providers.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ToolUnionParam" }, "description": "The tools the model may call. Two dated web-search stamps are the only hosted ones the gateway serves; the other eight families travel no further." }, "tool_choice": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceParam" } ], "description": "Which tool, if any, the model is to call." }, { "type": "null" } ] }, "thinking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ThinkingConfigParam" } ], "description": "How much reasoning the model does before answering. The budget becomes a tier: under 1024 draws a refusal, and `output_config.effort` wins over it." }, { "type": "null" } ] }, "output_config": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutputConfigParam" } ], "description": "Configuration for the output: the reasoning tier, and a schema the reply must satisfy." }, { "type": "null" } ] } } }, "MessagesSearchResultText": { "type": "object", "description": "A piece of text inside a search-result block.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "description": "What kind of piece this is. Always `text`." }, "text": { "type": "string", "description": "The text itself." } } }, "MessagesServerToolUsage": { "type": "object", "description": "How many times the model used a server-side tool during the turn.", "required": [ "web_search_requests", "web_fetch_requests" ], "properties": { "web_search_requests": { "type": "integer", "format": "int64", "description": "How many web searches the model ran." }, "web_fetch_requests": { "type": "integer", "format": "int64", "description": "Always `0`. The gateway serves no web fetch." } } }, "MessagesStreamFrame": { "oneOf": [ { "type": "object", "description": "The answer opens: everything about it except its content and its usage.", "required": [ "message", "type" ], "properties": { "message": { "allOf": [ { "$ref": "#/components/schemas/MessagesMessage" } ], "description": "The skeleton — `content` empty, `usage` zeroed, `stop_reason` null." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `message_start`.", "enum": [ "message_start" ] } } }, { "type": "object", "description": "A block opens.", "required": [ "index", "content_block", "type" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "Which block of the answer this is, counted from `0` in the order the blocks open. Every later frame about this block quotes the number." }, "content_block": { "allOf": [ { "$ref": "#/components/schemas/MessagesContentBlock" } ], "description": "The block as it opens, empty for one that streams." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `content_block_start`.", "enum": [ "content_block_start" ] } } }, { "type": "object", "description": "A block grows.", "required": [ "index", "delta", "type" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "Which block this adds to." }, "delta": { "allOf": [ { "$ref": "#/components/schemas/MessagesBlockDelta" } ], "description": "What to append to it." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `content_block_delta`.", "enum": [ "content_block_delta" ] } } }, { "type": "object", "description": "A block is finished. Nothing further arrives for this `index`.", "required": [ "index", "type" ], "properties": { "index": { "type": "integer", "format": "int64", "description": "Which block finished." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `content_block_stop`.", "enum": [ "content_block_stop" ] } } }, { "type": "object", "description": "The turn is finished: why it stopped, and what it cost.", "required": [ "delta", "usage", "type" ], "properties": { "delta": { "allOf": [ { "$ref": "#/components/schemas/MessagesMessageDelta" } ], "description": "Why the model stopped." }, "usage": { "allOf": [ { "$ref": "#/components/schemas/MessagesDeltaUsage" } ], "description": "What the whole turn cost in tokens — the authoritative figures, which the zeroed usage on `message_start` was not." }, "type": { "type": "string", "description": "The tag that selects this branch: `type` is `message_delta`.", "enum": [ "message_delta" ] } } }, { "type": "object", "description": "The last frame. The stream ends after it.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `message_stop`.", "enum": [ "message_stop" ] } } } ], "description": "One frame of a streamed answer. There is no `[DONE]` sentinel and no keep-alive ping." }, "MessagesSystem": { "oneOf": [ { "type": "array", "title": "List of text blocks", "items": { "$ref": "#/components/schemas/TextBlockParamPart" }, "description": "The instruction split across `text` blocks, joined in order. An empty array draws a refusal." }, { "type": "string", "title": "Plain text", "description": "The instruction as a single string, which is the shorthand for an array holding one `text` block." } ], "description": "The system prompt, as one string or as an array of `text` blocks." }, "MessagesUsage": { "type": "object", "description": "What the provider counted this request at. The bill counts separately.", "required": [ "input_tokens", "output_tokens", "cache_creation", "cache_creation_input_tokens", "cache_read_input_tokens", "server_tool_use", "service_tier", "inference_geo", "output_tokens_details" ], "properties": { "input_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the prompt read fresh, cache reads excluded." }, "output_tokens": { "type": "integer", "format": "int64", "description": "Tokens the model generated, its reasoning included." }, "cache_creation": { "type": "null", "description": "Always `null`. The per-duration breakdown of cache writes is not reported; `cache_creation_input_tokens` carries the total." }, "cache_creation_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens written into the prompt cache by this request, or `null`." }, "cache_read_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens served to this request out of the prompt cache, or `null`." }, "server_tool_use": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessagesServerToolUsage" } ], "description": "How many times server-side tools ran, or `null` when none did." }, { "type": "null" } ] }, "service_tier": { "type": "null", "description": "Always `null`. This gateway routes by its own catalog, so the Anthropic service tier does not apply to an answer served through it." }, "inference_geo": { "type": "null", "description": "Always `null`. Where the inference ran is not reported." }, "output_tokens_details": { "type": "null", "description": "Always `null`. The breakdown of `output_tokens` into thinking tokens and the rest is not surfaced. `output_tokens` is the total that counts." } } }, "MessagesWebSearchInput": { "type": "object", "description": "What a server-side tool was called with.", "properties": { "query": { "type": [ "string", "null" ], "description": "What the model searched for." } } }, "MessagesWebSearchResult": { "type": "object", "description": "One page the model's web search returned.", "required": [ "type", "url", "title", "encrypted_content", "page_age" ], "properties": { "type": { "type": "string", "description": "What kind of result this is. Always `web_search_result`." }, "url": { "type": "string", "description": "The page's address." }, "title": { "type": [ "string", "null" ], "description": "The page's title, or `null` when the search backend gave none." }, "encrypted_content": { "type": [ "string", "null" ], "description": "The page's contents in opaque form, replayed unchanged rather than read." }, "page_age": { "type": [ "string", "null" ], "description": "How old the page is, in the search backend's own words." } } }, "ModelList": { "type": "object", "description": "Every model the gateway serves, whole and unpaged.", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" }, "description": "The models, newest first by `created`." } }, "additionalProperties": false }, "ModelUsage": { "type": "object", "description": "One model's share of the window.", "required": [ "model_name", "request_count", "total_cost", "total_input_tokens", "total_output_tokens" ], "properties": { "model_name": { "type": "string", "description": "The model these requests named, or `Unknown` when the log had none." }, "request_count": { "type": "integer", "format": "int64", "description": "How many requests named this model, failed ones included." }, "total_cost": { "type": "string", "description": "What they cost in credits, as a decimal string." }, "total_input_tokens": { "type": "integer", "format": "int64", "description": "Input tokens summed over those requests." }, "total_output_tokens": { "type": "integer", "format": "int64", "description": "Output tokens summed over those requests." } } }, "Moderation": { "type": "object", "description": "The request body of `POST /v1/moderations`.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The moderation model, named by its id or alias." }, "input": { "allOf": [ { "$ref": "#/components/schemas/ModerationInput" } ], "description": "What to moderate. Each `image_url` part costs a flat 250 input tokens." } } }, "ModerationImageUrl": { "type": "object", "description": "Where an `image_url` part's image comes from.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The image itself: an `http(s)` URL, or a `data:` URI under 20 MiB." } } }, "ModerationInput": { "oneOf": [ { "type": "string", "title": "Plain text" }, { "type": "array", "title": "List of texts", "items": { "type": "string" } }, { "type": "array", "title": "List of typed parts", "items": { "$ref": "#/components/schemas/ModerationPart" } } ], "description": "What to moderate: one string, an array of strings, or typed parts." }, "ModerationPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextInput" } ], "title": "Text part" }, { "allOf": [ { "$ref": "#/components/schemas/ImageUrlInput" } ], "title": "Image URL part" } ], "description": "One element of the typed-parts arm, told apart by its own `type`." }, "ModerationResultResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "flagged", "categories", "category_scores" ], "properties": { "flagged": { "type": "boolean", "description": "Whether this input tripped any category." }, "categories": { "type": "object", "description": "The per-category booleans the model reported, in its own key set.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } }, "category_scores": { "type": "object", "description": "The per-category scores the model reported, keyed like `categories`.", "additionalProperties": { "type": "number", "format": "double" }, "propertyNames": { "type": "string" } }, "category_applied_input_types": { "type": [ "object", "null" ], "description": "Which kinds of input each category was applied to.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } } } } ], "description": "One verdict — the moderation of a single input item." }, "ModerationsResponse": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "id", "model", "results" ], "properties": { "id": { "type": "string", "description": "The identifier of this moderation, minted by the gateway." }, "model": { "type": "string", "description": "The model that moderated, as the catalog id the request resolved to." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ModerationResultResponse" }, "description": "The verdicts, in the order the model returned them." } } } ], "description": "The body of a successful `POST /v1/moderations`, without `usage`." }, "NamespaceTool": { "type": "object", "description": "A group of tools under one shared name, each offered to the model.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The group's name; a member is offered as `__`." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, which the gateway does not forward." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseTool" }, "description": "The members: `function` and `custom` tools." } } }, "NestedFunctionTool": { "type": "object", "description": "The chat-style spelling of a function declaration; the flat keys win over it.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "What the model calls the function by. Required, and non-empty.", "minLength": 1 }, "description": { "type": [ "string", "null" ], "description": "What the function does, written for the model to choose by." }, "parameters": { "type": [ "object", "null" ], "description": "The arguments the function accepts, as a JSON Schema.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model follows the parameter schema exactly." } } }, "OutputConfigParam": { "type": "object", "description": "Two settings on the answer: the effort tier, and a JSON shape to satisfy.", "properties": { "effort": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutputEffort" } ], "description": "The effort tier to ask the provider for. It overrides whatever `thinking` asked for." }, { "type": "null" } ] }, "format": { "type": [ "object", "null" ], "description": "The JSON shape the answer must satisfy. Only `json_schema` passes, and its `schema` may be `null`.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "OutputEffort": { "type": "string", "description": "How thoroughly the model works on the answer.", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "OutputTextPart": { "type": "object", "description": "A run of text the model produced earlier, replayed back.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text the model produced." }, "annotations": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "The citations attached to this text; three tags count." }, "logprobs": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "The token probabilities of the original reply. The gateway drops them." } } }, "PdfMediaType": { "type": "string", "description": "The media type of a PDF document source.", "enum": [ "application/pdf" ] }, "PlainTextMediaType": { "type": "string", "description": "The media type of a plain-text document source.", "enum": [ "text/plain" ] }, "PlainTextSourceParam": { "type": "object", "description": "A document supplied as readable text, not as a file.", "required": [ "data" ], "properties": { "media_type": { "allOf": [ { "$ref": "#/components/schemas/PlainTextMediaType" } ], "description": "The document's media type. Absent means `text/plain`." }, "data": { "type": "string", "description": "The document text itself, under 20 MiB in UTF-8." } } }, "Prediction": { "type": "object", "description": "Content the reply is expected to reproduce, which the gateway drops.", "properties": { "static_content": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/StaticContent" } ], "description": "The predicted content. Dropped along with the rest of `prediction`." }, { "type": "null" } ] } } }, "ReasoningConfig": { "type": "object", "description": "Settings for the reasoning a model does before it answers.", "properties": { "effort": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningEffort" } ], "description": "How much reasoning to spend before answering. The gateway maps the step onto whatever scale the provider offers, and drops it where there is none." }, { "type": "null" } ] }, "summary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummary" } ], "description": "Which summary of its own reasoning to ask the model for. Absent, `generate_summary` stands in for it." }, { "type": "null" } ] }, "generate_summary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummary" } ], "description": "The older spelling of `summary`, read only when `summary` is absent." }, { "type": "null" } ] } } }, "ReasoningDetailUnion": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatReasoningSummary" } ], "description": "A plain-text recap of one reasoning step." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `reasoning.summary`.", "enum": [ "reasoning.summary" ] } } } ], "description": "A plain-text recap of one reasoning step." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningEncrypted" } ], "description": "An opaque sealed reasoning block." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `reasoning.encrypted`.", "enum": [ "reasoning.encrypted" ] } } } ], "description": "An opaque sealed reasoning block." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningText" } ], "description": "Reasoning text, the continuation signature for it, or both." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `reasoning.text`.", "enum": [ "reasoning.text" ] } } } ], "description": "Reasoning text, the continuation signature for it, or both." } ], "description": "One entry of a message's `reasoning_details`. A NagaAI extension." }, "ReasoningEffort": { "type": "string", "description": "How much reasoning the model spends before it answers, from `none` to `max`. A model without the level runs the nearest one it has.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "ReasoningEncrypted": { "type": "object", "description": "Reasoning the provider keeps sealed, carried as an opaque blob. A NagaAI extension.", "required": [ "data" ], "properties": { "id": { "type": [ "string", "null" ], "description": "An `id` matching one of `tool_calls[].id` binds `data` to that call." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning dialect produced the entry, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Answers only." }, "data": { "type": "string", "description": "The sealed continuation token the provider issued for this reasoning." } } }, "ReasoningSummary": { "type": "string", "description": "How much of its own reasoning the model summarizes back. Some providers drop the request.", "enum": [ "concise", "detailed", "auto" ] }, "ReasoningText": { "type": "object", "description": "The model's reasoning in plain text, its signature, or both. A NagaAI extension.", "properties": { "id": { "type": [ "string", "null" ], "description": "An `id` matching one of `tool_calls[].id` binds `signature` to that call." }, "format": { "type": [ "string", "null" ], "description": "Which model family's reasoning dialect produced the entry, as an open string." }, "index": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the entry sits among the turn's reasoning entries. Answers only." }, "text": { "type": [ "string", "null" ], "description": "The reasoning text, absent on a signature-only entry." }, "signature": { "type": [ "string", "null" ], "description": "The continuation token for this reasoning, replayed unchanged." } } }, "RedactedThinkingBlockParam": { "type": "object", "description": "Reasoning the model redacted, replayed from an earlier assistant turn.", "required": [ "data" ], "properties": { "data": { "type": "string", "description": "The opaque redacted payload, replayed unchanged." } } }, "RefusalContent": { "type": "object", "description": "A refusal the model returned instead of an answer.", "required": [ "refusal" ], "properties": { "refusal": { "type": "string", "description": "The refusal text the model produced." } } }, "ResponseContentPart": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputTextPart" } ], "description": "A run of plain text handed to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_text`.", "enum": [ "input_text" ] } } } ], "description": "A run of plain text handed to the model." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutputTextPart" } ], "description": "Text the model produced earlier, replayed on an `assistant` message." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `output_text`.", "enum": [ "output_text" ] } } } ], "description": "Text the model produced earlier, replayed on an `assistant` message." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputImagePart" } ], "description": "An image handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_image`.", "enum": [ "input_image" ] } } } ], "description": "An image handed to the model as input." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputAudioPart" } ], "description": "Audio handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_audio`.", "enum": [ "input_audio" ] } } } ], "description": "Audio handed to the model as input." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputFilePart" } ], "description": "A file handed to the model as input." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `input_file`.", "enum": [ "input_file" ] } } } ], "description": "A file handed to the model as input." } ], "description": "One entry of a message's `content`. The role decides which types it admits." }, "ResponseFormat": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/JsonObjectResponseFormat" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `json_object`.", "enum": [ "json_object" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/JsonSchemaResponseFormat" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `json_schema`.", "enum": [ "json_schema" ] } } } ] } ], "description": "The shape the reply must take, selected by `type`." }, "ResponseInputItem": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputMessage" } ], "description": "A conversational turn — the caller's own words, standing instructions, or a reply being replayed as history." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `message`.", "enum": [ "message" ] } } } ], "description": "A conversational turn — the caller's own words, standing instructions, or a reply being replayed as history." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputFunctionCall" } ], "description": "A function call the model asked for on an earlier turn." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `function_call`.", "enum": [ "function_call" ] } } } ], "description": "A function call the model asked for on an earlier turn." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputFunctionCallOutput" } ], "description": "The result of a function call, tied to it by a shared `call_id`." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `function_call_output`.", "enum": [ "function_call_output" ] } } } ], "description": "The result of a function call, tied to it by a shared `call_id`." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputReasoningItem" } ], "description": "A block of the model's own earlier reasoning, with the opaque token that lets the thinking be continued." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `reasoning`.", "enum": [ "reasoning" ] } } } ], "description": "A block of the model's own earlier reasoning, with the opaque token that lets the thinking be continued." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputImageGenerationCall" } ], "description": "An image the model generated on an earlier turn, sent back as history." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image_generation_call`.", "enum": [ "image_generation_call" ] } } } ], "description": "An image the model generated on an earlier turn, sent back as history." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemReference" } ], "description": "A pointer to a stored item. Refused with a 400: this gateway keeps no conversation to resolve it against, so send the item itself." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `item_reference`.", "enum": [ "item_reference" ] } } } ], "description": "A pointer to a stored item. Refused with a 400: this gateway keeps no conversation to resolve it against, so send the item itself." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchCallItem" } ], "description": "A web search the model ran on an earlier turn, kept as part of the conversation." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_call`.", "enum": [ "web_search_call" ] } } } ], "description": "A web search the model ran on an earlier turn, kept as part of the conversation." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed search over hosted files. Accepted and dropped: this gateway offers no file-search tool." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `file_search_call`.", "enum": [ "file_search_call" ] } } } ], "description": "A replayed search over hosted files. Accepted and dropped: this gateway offers no file-search tool." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed computer-use action. Accepted and dropped: this gateway offers no computer-use tool." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `computer_call`.", "enum": [ "computer_call" ] } } } ], "description": "A replayed computer-use action. Accepted and dropped: this gateway offers no computer-use tool." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "The result of a replayed computer-use action. Accepted and dropped alongside the call it belongs to." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `computer_call_output`.", "enum": [ "computer_call_output" ] } } } ], "description": "The result of a replayed computer-use action. Accepted and dropped alongside the call it belongs to." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed run of hosted code. Accepted and dropped: this gateway runs no code interpreter." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `code_interpreter_call`.", "enum": [ "code_interpreter_call" ] } } } ], "description": "A replayed run of hosted code. Accepted and dropped: this gateway runs no code interpreter." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed shell command. Accepted and dropped: this gateway runs no shell." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `local_shell_call`.", "enum": [ "local_shell_call" ] } } } ], "description": "A replayed shell command. Accepted and dropped: this gateway runs no shell." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "The output of a replayed shell command. Accepted and dropped alongside the call it belongs to." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `local_shell_call_output`.", "enum": [ "local_shell_call_output" ] } } } ], "description": "The output of a replayed shell command. Accepted and dropped alongside the call it belongs to." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed shell command in the dated spelling, which the gateway drops." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `shell_call`.", "enum": [ "shell_call" ] } } } ], "description": "A replayed shell command in the dated spelling, which the gateway drops." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "The output of a replayed shell command, which the gateway drops." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `shell_call_output`.", "enum": [ "shell_call_output" ] } } } ], "description": "The output of a replayed shell command, which the gateway drops." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed patch the model asked to apply. Accepted and dropped: this gateway applies no patches." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `apply_patch_call`.", "enum": [ "apply_patch_call" ] } } } ], "description": "A replayed patch the model asked to apply. Accepted and dropped: this gateway applies no patches." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "The result of a replayed patch. Accepted and dropped alongside the call it belongs to." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `apply_patch_call_output`.", "enum": [ "apply_patch_call_output" ] } } } ], "description": "The result of a replayed patch. Accepted and dropped alongside the call it belongs to." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed listing of the tools an MCP server offers. Accepted and dropped: this gateway connects to no MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `mcp_list_tools`.", "enum": [ "mcp_list_tools" ] } } } ], "description": "A replayed listing of the tools an MCP server offers. Accepted and dropped: this gateway connects to no MCP server." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed request to approve an MCP tool call. Accepted and dropped with the rest of the MCP family." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `mcp_approval_request`.", "enum": [ "mcp_approval_request" ] } } } ], "description": "A replayed request to approve an MCP tool call. Accepted and dropped with the rest of the MCP family." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed answer to an MCP approval request. Accepted and dropped with the rest of the MCP family." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `mcp_approval_response`.", "enum": [ "mcp_approval_response" ] } } } ], "description": "A replayed answer to an MCP approval request. Accepted and dropped with the rest of the MCP family." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A replayed call to a tool on an MCP server. Accepted and dropped with the rest of the MCP family." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `mcp_call`.", "enum": [ "mcp_call" ] } } } ], "description": "A replayed call to a tool on an MCP server. Accepted and dropped with the rest of the MCP family." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputToolSearchCall" } ], "description": "A replayed client-side tool search, carried as a call to the `tool_search` tool." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_search_call`.", "enum": [ "tool_search_call" ] } } } ], "description": "A replayed client-side tool search, carried as a call to the `tool_search` tool." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputToolSearchOutput" } ], "description": "The tools a client-side search loaded: offered to the model from here on, and carried as the search's result." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_search_output`.", "enum": [ "tool_search_output" ] } } } ], "description": "The tools a client-side search loaded: offered to the model from here on, and carried as the search's result." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/AdditionalToolsItem" } ], "description": "Tool declarations carried inside `input`; merged into `tools`." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `additional_tools`.", "enum": [ "additional_tools" ] } } } ], "description": "Tool declarations carried inside `input`; merged into `tools`." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedInputItemStub" } ], "description": "A summary standing in for a stretch of conversation a stateful server compacted away. Accepted and dropped: this gateway does no server-side compaction, and sends the history it is handed." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `compaction`.", "enum": [ "compaction" ] } } } ], "description": "A summary standing in for a stretch of conversation a stateful server compacted away. Accepted and dropped: this gateway does no server-side compaction, and sends the history it is handed." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputCustomToolCall" } ], "description": "A replayed call to a `custom` tool, carried as a function call with one `input` string." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `custom_tool_call`.", "enum": [ "custom_tool_call" ] } } } ], "description": "A replayed call to a `custom` tool, carried as a function call with one `input` string." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputCustomToolCallOutput" } ], "description": "The result of a replayed custom-tool call, carried as a function result." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `custom_tool_call_output`.", "enum": [ "custom_tool_call_output" ] } } } ], "description": "The result of a replayed custom-tool call, carried as a function result." } ], "description": "One entry of the input list, chosen by its `type`. Six of twenty-six tags do something." }, "ResponseTextConfig": { "type": "object", "description": "The controls over the reply's text: shape and length.", "properties": { "format": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponseTextFormat" } ], "description": "The shape the reply must take." }, { "type": "null" } ] }, "verbosity": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Verbosity" } ], "description": "How long the reply should run." }, { "type": "null" } ] } } }, "ResponseTextFormat": { "type": "object", "description": "The shape the reply must take. The keys beside `type` count only under `json_schema`.", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/ResponseTextFormatType" } ], "description": "Which of the three formats the reply takes." }, "name": { "type": [ "string", "null" ], "description": "A short name for the schema. Required if `type` is `json_schema`." }, "description": { "type": [ "string", "null" ], "description": "What the schema is for, written for the model." }, "schema": { "type": [ "object", "null" ], "description": "The JSON Schema the reply is built to. Required if `type` is `json_schema`.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model is held to the schema exactly." } } }, "ResponseTextFormatType": { "type": "string", "description": "Which shape the reply must take.", "enum": [ "text", "json_object", "json_schema" ] }, "ResponseTool": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionTool" } ], "description": "A tool your own code implements. The model answers with a call naming it, and you feed the result back." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `function`.", "enum": [ "function" ] } } } ], "description": "A tool your own code implements. The model answers with a call naming it, and you feed the result back." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool" } ], "description": "The built-in web search, kept rather than dropped. A provider without one does not gain it." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search`.", "enum": [ "web_search" ] } } } ], "description": "The built-in web search, kept rather than dropped. A provider without one does not gain it." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool" } ], "description": "The same built-in web search under its dated stamp; the two spellings behave alike." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_2025_08_26`.", "enum": [ "web_search_2025_08_26" ] } } } ], "description": "The same built-in web search under its dated stamp; the two spellings behave alike." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchPreviewTool" } ], "description": "The preview flavour of the built-in web search, kept for clients written against it; it takes a smaller set of settings than `web_search` does. Kept rather than dropped by this gateway, and subject to the same last step: a provider without a web search of its own drops it." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_preview`.", "enum": [ "web_search_preview" ] } } } ], "description": "The preview flavour of the built-in web search, kept for clients written against it; it takes a smaller set of settings than `web_search` does. Kept rather than dropped by this gateway, and subject to the same last step: a provider without a web search of its own drops it." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchPreviewTool" } ], "description": "`web_search_preview` under its dated stamp; the two spellings behave alike." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_search_preview_2025_03_11`.", "enum": [ "web_search_preview_2025_03_11" ] } } } ], "description": "`web_search_preview` under its dated stamp; the two spellings behave alike." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/FileSearchTool" } ], "description": "Search across vector stores you have uploaded. The gateway keeps none and drops the entry, though `vector_store_ids` stays required." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `file_search`.", "enum": [ "file_search" ] } } } ], "description": "Search across vector stores you have uploaded. The gateway keeps none and drops the entry, though `vector_store_ids` stays required." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ComputerUseTool" } ], "description": "Lets a model operate a virtual screen. The gateway runs none and drops the entry, though its keys stay required." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `computer_use_preview`.", "enum": [ "computer_use_preview" ] } } } ], "description": "Lets a model operate a virtual screen. The gateway runs none and drops the entry, though its keys stay required." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterTool" } ], "description": "Runs code in a sandboxed container. The gateway runs none and drops the entry, though `container` stays required." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `code_interpreter`.", "enum": [ "code_interpreter" ] } } } ], "description": "Runs code in a sandboxed container. The gateway runs none and drops the entry, though `container` stays required." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/McpTool" } ], "description": "Points the model at a remote MCP server. The gateway contacts none and drops the entry, `authorization` included." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `mcp`.", "enum": [ "mcp" ] } } } ], "description": "Points the model at a remote MCP server. The gateway contacts none and drops the entry, `authorization` included." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationTool" } ], "description": "The hosted image-generation tool, which the gateway drops after parsing its settings. For pictures, ask for a model that produces them." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image_generation`.", "enum": [ "image_generation" ] } } } ], "description": "The hosted image-generation tool, which the gateway drops after parsing its settings. For pictures, ask for a model that produces them." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/LocalShellTool" } ], "description": "The local-shell tool, by which a model proposes commands for your own machine to run. Accepted and dropped before the request reaches the provider, and no shell call will come back." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `local_shell`.", "enum": [ "local_shell" ] } } } ], "description": "The local-shell tool, by which a model proposes commands for your own machine to run. Accepted and dropped before the request reaches the provider, and no shell call will come back." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ShellTool" } ], "description": "The shell tool, by which a model runs commands in an environment the provider hosts. Accepted and dropped before the request reaches the provider, and no shell call will come back." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `shell`.", "enum": [ "shell" ] } } } ], "description": "The shell tool, by which a model runs commands in an environment the provider hosts. Accepted and dropped before the request reaches the provider, and no shell call will come back." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchTool" } ], "description": "The apply-patch tool, by which a model edits files through unified diffs. Accepted and dropped before the request reaches the provider, and no patch call will come back." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `apply_patch`.", "enum": [ "apply_patch" ] } } } ], "description": "The apply-patch tool, by which a model edits files through unified diffs. Accepted and dropped before the request reaches the provider, and no patch call will come back." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/CustomTool" } ], "description": "A tool of your own that the model calls with a plain string shaped by a grammar. Offered as a function with one `input` string; the call comes back as `custom_tool_call`." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `custom`.", "enum": [ "custom" ] } } } ], "description": "A tool of your own that the model calls with a plain string shaped by a grammar. Offered as a function with one `input` string; the call comes back as `custom_tool_call`." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedToolStub" } ], "description": "The computer-use tool under its undated name, which the gateway drops unread." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `computer`.", "enum": [ "computer" ] } } } ], "description": "The computer-use tool under its undated name, which the gateway drops unread." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolSearchTool" } ], "description": "A tool search your own code runs (`execution: \"client\"`). Offered as a function; the call comes back as `tool_search_call`. A server-run search is dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_search`.", "enum": [ "tool_search" ] } } } ], "description": "A tool search your own code runs (`execution: \"client\"`). Offered as a function; the call comes back as `tool_search_call`. A server-run search is dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/NamespaceTool" } ], "description": "Groups tools under one shared name. Each member is offered as `__`; its call comes back with `namespace` set." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `namespace`.", "enum": [ "namespace" ] } } } ], "description": "Groups tools under one shared name. Each member is offered as `__`; its call comes back with `namespace` set." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedToolStub" } ], "description": "Loads prepared bundles of instructions and tools for the model to draw on. Accepted and dropped before the request reaches the provider, with nothing inside it read, so no bundle is ever loaded." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `skills`.", "enum": [ "skills" ] } } } ], "description": "Loads prepared bundles of instructions and tools for the model to draw on. Accepted and dropped before the request reaches the provider, with nothing inside it read, so no bundle is ever loaded." } ], "description": "One entry of `tools[]`, chosen by its `type`. Five of the eighteen types reach the model; the gateway drops the other thirteen." }, "ResponsesAnnotationFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this annotates." }, { "type": "object", "required": [ "annotation_index", "annotation", "type", "sequence_number" ], "properties": { "annotation_index": { "type": "integer", "format": "int64", "description": "The annotation's position within that part's annotations, counted from `0`." }, "annotation": { "description": "The annotation: what is cited and where it applies." }, "type": { "type": "string", "description": "Which move this is. Always `response.output_text.annotation.added`.", "enum": [ "response.output_text.annotation.added" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A citation attached to a piece of the text." }, "ResponsesArgumentsDeltaFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesItemRef" } ], "description": "Which item this adds to." }, { "type": "object", "required": [ "delta", "type", "sequence_number" ], "properties": { "delta": { "type": "string", "description": "The next piece of the argument JSON; no piece is valid JSON alone." }, "type": { "type": "string", "description": "Which move this is. Always `response.function_call_arguments.delta`.", "enum": [ "response.function_call_arguments.delta" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "The next slice of a tool call's arguments." }, "ResponsesArgumentsDoneFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesItemRef" } ], "description": "Which item this closes." }, { "type": "object", "required": [ "name", "arguments", "type", "sequence_number" ], "properties": { "name": { "type": "string", "description": "Which of your tools is being called." }, "arguments": { "type": "string", "description": "The whole argument JSON — every slice already sent, joined." }, "type": { "type": "string", "description": "Which move this is. Always `response.function_call_arguments.done`.", "enum": [ "response.function_call_arguments.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A tool call's arguments, finished and whole." }, "ResponsesContentDeltaFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this adds to." }, { "type": "object", "required": [ "delta", "type", "sequence_number" ], "properties": { "delta": { "type": "string", "description": "The text to append." }, "type": { "type": "string", "description": "Which of the two this is — a slice of a refusal, or a slice of reasoning text.", "enum": [ "response.refusal.delta", "response.reasoning_text.delta" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "The next slice of a refusal, or of the model's reasoning text." }, "ResponsesContentPartFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this is about." }, { "type": "object", "required": [ "part", "type", "sequence_number" ], "properties": { "part": { "description": "The part. Empty of text on `added`, complete on `done`." }, "type": { "type": "string", "description": "Whether the part is opening or finished.", "enum": [ "response.content_part.added", "response.content_part.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A content part of a message opened or closed." }, "ResponsesContentRef": { "type": "object", "description": "Which piece of which item a frame is about.", "required": [ "item_id", "output_index", "content_index" ], "properties": { "item_id": { "type": "string", "description": "The `id` of the output item." }, "output_index": { "type": "integer", "format": "int64", "description": "That item's position in `output[]`, counted from `0`." }, "content_index": { "type": "integer", "format": "int64", "description": "The piece's position within the item's content, counted from `0`." } } }, "ResponsesError": { "type": "object", "description": "What went wrong once a response had been created.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A machine-readable code for the failure, never empty." }, "message": { "type": "string", "description": "What went wrong, in prose meant to be read." } } }, "ResponsesErrorFrame": { "type": "object", "description": "A failure, sent in place of a frame once the `200` headers have gone out.", "required": [ "code", "message", "param", "type", "sequence_number" ], "properties": { "code": { "type": "string", "description": "A machine-readable code for the failure. Falls back to the failure's class when the provider gave no code of its own." }, "message": { "type": "string", "description": "What went wrong, in prose meant to be read." }, "param": { "type": [ "string", "null" ], "description": "The request field the failure is about, or `null` when it is about none. The key is always present." }, "type": { "type": "string", "description": "Which move this is. Always `error` — the one frame of this dialect whose name is not `response.*`.", "enum": [ "error" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } }, "ResponsesIncompleteDetails": { "type": "object", "description": "Why a response stopped short of finishing.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "What cut the turn short.", "enum": [ "max_output_tokens", "content_filter", "tool_use_required", "upstream_timeout", "upstream_disconnect", "gateway_cancelled", "other" ] } } }, "ResponsesInput": { "oneOf": [ { "type": "array", "title": "List of input items", "items": { "$ref": "#/components/schemas/ResponseInputItem" }, "description": "The conversation as typed items, oldest first. Six kinds travel on; the gateway drops the rest." }, { "type": "string", "title": "Plain text", "description": "The whole prompt as one string, read as a single user message." } ], "description": "The prompt for one turn: one string, or the conversation as typed items." }, "ResponsesInputTokensDetails": { "type": "object", "description": "Breakdown of the prompt-side token count.", "required": [ "cached_tokens" ], "properties": { "cached_tokens": { "type": "integer", "format": "int64", "description": "How many prompt tokens the provider served from its own cache. `0` when it reported none." }, "audio_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many prompt tokens were audio. A NagaAI extension, present only when the provider split them out." } } }, "ResponsesItemRef": { "type": "object", "description": "Which item a frame is about.", "required": [ "item_id", "output_index" ], "properties": { "item_id": { "type": "string", "description": "The `id` of the output item." }, "output_index": { "type": "integer", "format": "int64", "description": "That item's position in `output[]`, counted from `0`." } } }, "ResponsesLifecycleFrame": { "type": "object", "description": "The turn as a whole moved, and the frame carries the full snapshot.", "required": [ "response", "type", "sequence_number" ], "properties": { "response": { "allOf": [ { "$ref": "#/components/schemas/ResponsesResponse" } ], "description": "The response as it stands at this point of the stream." }, "type": { "type": "string", "description": "Which move this is. The last three end the stream.", "enum": [ "response.created", "response.queued", "response.in_progress", "response.completed", "response.failed", "response.incomplete" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } }, "ResponsesOutputItem": { "oneOf": [ { "type": "object", "title": "Message item", "description": "Prose the model wrote, or its refusal to write any.", "required": [ "type", "id", "status", "role", "content" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `message`.", "enum": [ "message" ] }, "id": { "type": "string", "description": "The item's identifier, quoted by every stream frame about it." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "Whether the item is still unfinished." }, "role": { "type": "string", "description": "Who the message is from. `assistant` on anything the model produced.", "enum": [ "user", "assistant", "system", "developer", "tool" ] }, "content": { "type": "array", "items": { "type": "object" }, "description": "The message itself: `output_text` parts, or a `refusal` part." }, "phase": { "allOf": [ { "$ref": "#/components/schemas/MessagePhase" } ], "description": "Which pass of a two-pass answer this message is." } } }, { "type": "object", "title": "Reasoning item", "description": "The model's reasoning about the turn.", "required": [ "type", "id", "summary", "content" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `reasoning` — carried both by the model's own reasoning and by the item that carries another item's signature.", "enum": [ "reasoning" ] }, "id": { "type": "string", "description": "The item's identifier, quoted by every stream frame about it." }, "summary": { "type": "array", "items": { "type": "object" }, "description": "The reasoning as the model summarized it, `summary_text` part by part. Empty when the model reasoned without summarising." }, "content": { "type": "array", "items": { "type": "object" }, "description": "The reasoning as the model wrote it out, `reasoning_text` part by part. Empty for a model that returns only a summary." }, "encrypted_content": { "type": [ "string", "null" ], "description": "The reasoning in opaque form, replayed on a later turn." }, "format": { "type": [ "string", "null" ], "description": "Which provider's encoding `encrypted_content` is in. Absent when the provider named none." } } }, { "type": "object", "title": "Synthesized reasoning item", "description": "A carrier for reasoning that belongs to another item, replayed beside it.", "required": [ "type", "id", "encrypted_content", "summary" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `reasoning` — carried both by the model's own reasoning and by the item that carries another item's signature.", "enum": [ "reasoning" ] }, "id": { "type": "string", "description": "The item's identifier." }, "encrypted_content": { "type": "string", "description": "The signature this frame carries, in opaque form." }, "summary": { "type": "array", "items": { "type": "object" }, "description": "Always empty: a carrier has nothing to summarize." }, "format": { "type": [ "string", "null" ], "description": "Which provider's encoding `encrypted_content` is in, learned from the reasoning of the same turn. Absent when no reasoning item of the turn named one." } } }, { "type": "object", "title": "Function call item", "description": "A tool call for you to run: the model has stopped and is waiting for the result.", "required": [ "type", "id", "call_id", "name", "arguments", "status" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `function_call`.", "enum": [ "function_call" ] }, "id": { "type": "string", "description": "The item's identifier, quoted by every stream frame about it." }, "call_id": { "type": "string", "description": "The call's own identifier, repeated as `call_id` on the item carrying the result." }, "name": { "type": "string", "description": "Which of your tools to call, by the name you declared it under." }, "arguments": { "type": "string", "description": "The arguments to call it with, as JSON in a string. Valid JSON is not guaranteed." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "Whether the call is fully written out." } } }, { "type": "object", "title": "Function call output item", "description": "The result of a tool call, echoed back as part of the turn.", "required": [ "type", "id", "call_id", "output", "status" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `function_call_output`.", "enum": [ "function_call_output" ] }, "id": { "type": "string", "description": "The item's identifier." }, "call_id": { "type": "string", "description": "The `call_id` of the call this answers." }, "output": { "description": "The result itself: a string, or a list of content parts." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ItemStatus" } ], "description": "Whether the result is complete." } } }, { "type": "object", "title": "Web search call item", "description": "A web search the provider ran itself. Nothing is asked of you.", "required": [ "type", "id", "status" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `web_search_call`.", "enum": [ "web_search_call" ] }, "id": { "type": "string", "description": "The item's identifier, quoted by every stream frame about it." }, "status": { "type": "string", "description": "How the search is going.", "enum": [ "in_progress", "completed", "incomplete", "searching", "failed" ] }, "action": { "type": "object", "description": "What the search did: a query, a page opened, a page searched within." }, "results": { "type": "array", "items": { "type": "object" }, "description": "The pages the search returned, absent when the provider returned none. Published as bare objects, for the same reason as `action`." } } }, { "type": "object", "title": "Image generation call item", "description": "An image the model generated.", "required": [ "type", "id", "status" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `image_generation_call` — carried both by a finished image and by the frame announcing one.", "enum": [ "image_generation_call" ] }, "id": { "type": "string", "description": "The item's identifier, quoted by every stream frame about it." }, "status": { "type": "string", "description": "How the generation is going. Always `completed`: an image reaches you whole or not at all.", "enum": [ "completed" ] }, "result": { "type": [ "string", "null" ], "description": "The image's bytes, base64-encoded. Absent when the provider returned a hosted image instead — then `url` carries it." }, "url": { "type": [ "string", "null" ], "description": "Where a hosted image is served from. Absent when the provider returned the bytes inline." }, "mime_type": { "type": [ "string", "null" ], "description": "The image's media type. Absent when the provider named none." } } }, { "type": "object", "title": "Image generation call, added view", "description": "An image announced on a stream, its bytes held for the done frame.", "required": [ "type", "id", "status", "result" ], "properties": { "type": { "type": "string", "description": "What kind of item this is. Always `image_generation_call` — carried both by a finished image and by the frame announcing one.", "enum": [ "image_generation_call" ] }, "id": { "type": "string", "description": "The item's identifier, which the frame reporting it done repeats." }, "status": { "type": "string", "description": "Always `in_progress`, which is what tells this announcement apart from the finished item.", "enum": [ "in_progress" ] }, "result": { "type": "null", "description": "Always `null` here. The image's bytes arrive on the frame that reports the item done, so they travel exactly once per stream." }, "mime_type": { "type": [ "string", "null" ], "description": "The image's media type, when the provider named one this early." } } } ], "description": "One item the model produced, addressed by `output_index`." }, "ResponsesOutputItemFrame": { "type": "object", "description": "An output item opened or closed.", "required": [ "output_index", "item", "type", "sequence_number" ], "properties": { "output_index": { "type": "integer", "format": "int64", "description": "The item's position in `output[]`, counted from `0`." }, "item": { "allOf": [ { "$ref": "#/components/schemas/ResponsesOutputItem" } ], "description": "The item: a skeleton on `added`, the finished one on `done`." }, "type": { "type": "string", "description": "Whether the item is opening or finished.", "enum": [ "response.output_item.added", "response.output_item.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } }, "ResponsesOutputTextDeltaFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this adds to." }, { "type": "object", "required": [ "delta", "logprobs", "type", "sequence_number" ], "properties": { "delta": { "type": "string", "description": "The text to append. It can be a fragment of a word." }, "logprobs": { "type": "array", "items": {}, "description": "Always empty. The gateway returns no token log probabilities." }, "type": { "type": "string", "description": "Which move this is. Always `response.output_text.delta`.", "enum": [ "response.output_text.delta" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "The next slice of a message's text." }, "ResponsesOutputTextDoneFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this closes." }, { "type": "object", "required": [ "text", "logprobs", "type", "sequence_number" ], "properties": { "text": { "type": "string", "description": "The whole text — every slice already sent, joined." }, "logprobs": { "type": "array", "items": {}, "description": "Always empty, as on the delta frame." }, "type": { "type": "string", "description": "Which move this is. Always `response.output_text.done`.", "enum": [ "response.output_text.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A message's text is finished, and here it is whole." }, "ResponsesOutputTokensDetails": { "type": "object", "description": "Breakdown of the generated-token count.", "required": [ "reasoning_tokens" ], "properties": { "reasoning_tokens": { "type": "integer", "format": "int64", "description": "How many generated tokens the model spent reasoning. `0` when the provider reported none." }, "image_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many generated tokens were image output. A NagaAI extension." } } }, "ResponsesReasoningTextDoneFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this closes." }, { "type": "object", "required": [ "text", "type", "sequence_number" ], "properties": { "text": { "type": "string", "description": "The whole reasoning text — every slice already sent, joined." }, "type": { "type": "string", "description": "Which move this is. Always `response.reasoning_text.done`.", "enum": [ "response.reasoning_text.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "The model's reasoning text, finished and whole." }, "ResponsesRefusalDoneFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentRef" } ], "description": "Which part of which item this closes." }, { "type": "object", "required": [ "refusal", "type", "sequence_number" ], "properties": { "refusal": { "type": "string", "description": "The whole refusal — every slice already sent, joined." }, "type": { "type": "string", "description": "Which move this is. Always `response.refusal.done`.", "enum": [ "response.refusal.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A refusal is finished, and here it is whole." }, "ResponsesRequest": { "type": "object", "description": "The OpenAI-compatible Responses request. The gateway takes an unrecognized key and drops it, and keeps nothing between requests.", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "The model to run, named by an id or alias from NagaAI's catalog. An entry without the `chat.completions` capability draws a refusal." }, "input": { "allOf": [ { "$ref": "#/components/schemas/ResponsesInput" } ], "description": "The prompt: one string, or the conversation as typed items, oldest first. Required." }, "routing": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RoutingPreferences" } ], "description": "How NagaAI orders the providers for this request. It reorders them and never removes one. A NagaAI extension." }, { "type": "null" } ] }, "instructions": { "type": [ "string", "null" ], "description": "A system instruction put ahead of the conversation." }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "The ceiling on generated tokens, reasoning included. At least 1, and the gateway raises it where the reasoning budget would not fit.", "minimum": 1 }, "temperature": { "type": [ "number", "null" ], "format": "double", "description": "How much randomness goes into the reply, between 0 and 2. A provider may still refuse a value this range allows.", "maximum": 2, "minimum": 0 }, "top_p": { "type": [ "number", "null" ], "format": "double", "description": "The sampling cut-off, between 0 and 1, and an alternative to `temperature`.", "maximum": 1, "minimum": 0 }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponseTool" }, "description": "The tools the model may call. `web_search` and `web_search_preview` are the only hosted ones the gateway runs; other types travel no further." }, "tool_choice": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesToolChoice" } ], "description": "Which tool, if any, the model is to call. Naming a tool the gateway does not run reads as if the key were absent." }, { "type": "null" } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Whether the model may return several tool calls in one turn. It reaches only some providers." }, "truncation": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Truncation" } ], "description": "What to do when the conversation outgrows the context window. It reaches only some providers." }, { "type": "null" } ] }, "reasoning": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningConfig" } ], "description": "How much reasoning to do, and what summary of it comes back." }, { "type": "null" } ] }, "text": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponseTextConfig" } ], "description": "The shape of the reply, and how long it should run." }, { "type": "null" } ] }, "stream": { "type": "boolean", "description": "Whether the reply arrives incrementally as the model writes it. An explicit `null` draws a refusal." } } }, "ResponsesRequestEcho": { "type": "object", "description": "The request as the gateway accepted it, with dropped keys gone and defaults filled in.", "required": [ "instructions", "tools", "tool_choice", "temperature", "top_p", "parallel_tool_calls", "metadata", "text", "truncation", "max_output_tokens" ], "properties": { "instructions": { "type": [ "string", "null" ], "description": "The system instructions the turn ran with, or `null`." }, "tools": { "type": "array", "items": {}, "description": "The tools the model was offered, in the shape the gateway took them." }, "tool_choice": { "description": "How the model was told to choose among them." }, "temperature": { "description": "The sampling temperature the turn ran with; `1` when the request set none." }, "top_p": { "description": "The sampling cut-off the turn ran with; `1` when the request set none." }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model could call several tools at once." }, "metadata": { "description": "The metadata the request sent, echoed back unchanged. The gateway drops it upstream." }, "text": { "description": "The output-format settings the turn ran with." }, "truncation": { "description": "What was to happen if the conversation outgrew the context window." }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "The ceiling on generated tokens the turn ran with, or `null`." }, "reasoning": { "description": "The reasoning settings the turn ran with." } } }, "ResponsesResponse": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesRequestEcho" } ], "description": "The request as the gateway accepted it." }, { "type": "object", "required": [ "id", "object", "created_at", "status", "output", "error", "incomplete_details", "usage", "model" ], "properties": { "id": { "type": "string", "description": "This response's identifier, repeated on every frame. No handle to resume from." }, "object": { "type": "string", "description": "What kind of object this is. Always `response`.", "enum": [ "response" ] }, "created_at": { "type": "integer", "format": "int64", "description": "When the response was created, in seconds since the Unix epoch." }, "status": { "type": "string", "description": "Where the turn stands, as the provider named it." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesOutputItem" }, "description": "What the model produced, item by item, in order." }, "error": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesError" } ], "description": "What went wrong, or `null` when nothing did." }, { "type": "null" } ] }, "incomplete_details": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesIncompleteDetails" } ], "description": "Why the turn stopped short, or `null`." }, { "type": "null" } ] }, "usage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesUsage" } ], "description": "What the request cost in tokens, or `null` while the turn runs." }, { "type": "null" } ] }, "model": { "type": [ "string", "null" ], "description": "The model that answered, by its id in the NagaAI catalog." } } } ], "description": "A response: the non-streaming body, and the snapshot every lifecycle frame carries." }, "ResponsesStreamFrame": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesLifecycleFrame" } ], "title": "Lifecycle frame", "description": "The turn as a whole moved." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesOutputItemFrame" } ], "title": "Output item frame", "description": "An output item opened or closed." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentPartFrame" } ], "title": "Content part frame", "description": "A content part opened or closed." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesOutputTextDeltaFrame" } ], "title": "Output text delta frame", "description": "The next slice of a message's text." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesOutputTextDoneFrame" } ], "title": "Output text done frame", "description": "A message's text, whole." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesAnnotationFrame" } ], "title": "Annotation frame", "description": "A citation on a piece of the text." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesContentDeltaFrame" } ], "title": "Content delta frame", "description": "The next slice of a refusal or of reasoning text." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesReasoningTextDoneFrame" } ], "title": "Reasoning text done frame", "description": "Reasoning text, whole." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesRefusalDoneFrame" } ], "title": "Refusal done frame", "description": "A refusal, whole." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryDeltaFrame" } ], "title": "Summary text delta frame", "description": "The next slice of a reasoning summary." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryTextFrame" } ], "title": "Summary text done frame", "description": "A reasoning summary part, whole." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryPartFrame" } ], "title": "Summary part frame", "description": "A reasoning summary part opened or closed." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesWebSearchCallFrame" } ], "title": "Web search call frame", "description": "A provider-run web search moved." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesArgumentsDeltaFrame" } ], "title": "Function call arguments delta frame", "description": "The next slice of a tool call's arguments." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesArgumentsDoneFrame" } ], "title": "Function call arguments done frame", "description": "A tool call's arguments, whole." }, { "allOf": [ { "$ref": "#/components/schemas/ResponsesErrorFrame" } ], "title": "Error frame", "description": "A failure, sent in place of a frame." } ], "description": "One frame of a streamed answer. There is no `[DONE]` sentinel; the stream ends after the terminal frame." }, "ResponsesSummaryDeltaFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryRef" } ], "description": "Which summary part of which item this adds to." }, { "type": "object", "required": [ "delta", "type", "sequence_number" ], "properties": { "delta": { "type": "string", "description": "The text to append." }, "type": { "type": "string", "description": "Which move this is. Always `response.reasoning_summary_text.delta`.", "enum": [ "response.reasoning_summary_text.delta" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "The next slice of a reasoning summary." }, "ResponsesSummaryPartFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryRef" } ], "description": "Which summary part of which item this is about." }, { "type": "object", "required": [ "part", "type", "sequence_number" ], "properties": { "part": { "description": "The part. Empty of text on `added`, complete on `done`." }, "type": { "type": "string", "description": "Whether the summary part is opening or finished.", "enum": [ "response.reasoning_summary_part.added", "response.reasoning_summary_part.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A part of a reasoning summary opened or closed." }, "ResponsesSummaryRef": { "type": "object", "description": "Which part of which reasoning summary a frame names.", "required": [ "item_id", "output_index", "summary_index" ], "properties": { "item_id": { "type": "string", "description": "The `id` of the output item." }, "output_index": { "type": "integer", "format": "int64", "description": "That item's position in `output[]`, counted from `0`." }, "summary_index": { "type": "integer", "format": "int64", "description": "The part's position within the item's summary, counted from `0`." } } }, "ResponsesSummaryTextFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesSummaryRef" } ], "description": "Which summary part of which item this closes." }, { "type": "object", "required": [ "text", "type", "sequence_number" ], "properties": { "text": { "type": "string", "description": "The whole summary text — every slice already sent, joined." }, "type": { "type": "string", "description": "Which move this is. Always `response.reasoning_summary_text.done`.", "enum": [ "response.reasoning_summary_text.done" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A reasoning summary part, finished and whole." }, "ResponsesToolChoice": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceMode" } ], "title": "Mode", "description": "The bare string form: `auto`, `none` or `required`." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunction" } ], "title": "Function tool", "description": "Forces one named function, written flat as `{\"type\": \"function\", \"name\": \"get_weather\"}`." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunctionLegacy" } ], "title": "Function tool, chat-style", "description": "The same forced function written the Chat Completions way, with the name nested under `function`. An addition of NagaAI's; the two spellings decode alike." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceAllowedTools" } ], "title": "Allowed tools", "description": "Confines the model to a named subset of the declared tools instead of forcing one of them." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceHostedWebSearch" } ], "title": "Hosted web search", "description": "Forces the hosted web-search tool, under any of its three accepted spellings." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceDroppedStub" } ], "title": "Accepted and dropped tool", "description": "Names a tool family the gateway does not run. It drops the choice." } ], "description": "Which tool, if any, the model calls this turn." }, "ResponsesUsage": { "type": "object", "description": "What the provider counted this request at. The bill counts separately.", "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int64", "description": "Tokens of the prompt, cached ones included." }, "input_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/ResponsesInputTokensDetails" } ], "description": "The split of `input_tokens` the provider reported." }, "output_tokens": { "type": "integer", "format": "int64", "description": "Tokens the model generated, reasoning and image tokens included." }, "output_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/ResponsesOutputTokensDetails" } ], "description": "The split of `output_tokens` the provider reported." }, "total_tokens": { "type": "integer", "format": "int64", "description": "The provider's own total for the request, reported as received." } } }, "ResponsesWebSearchCallFrame": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ResponsesItemRef" } ], "description": "Which item this is about." }, { "type": "object", "required": [ "type", "sequence_number" ], "properties": { "type": { "type": "string", "description": "Which move the search made.", "enum": [ "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed" ] }, "sequence_number": { "type": "integer", "format": "int64", "description": "This frame's position in the stream, counted from `0`." } } } ], "description": "A provider-run web search moved." }, "RoutingPreferences": { "type": "object", "description": "Routing preferences for one request. An unknown key inside draws a 400. A NagaAI extension.", "required": [ "strategy" ], "properties": { "strategy": { "allOf": [ { "$ref": "#/components/schemas/RoutingStrategyWire" } ], "description": "The strategy for this request. An unknown name draws a 400." } }, "additionalProperties": false }, "RoutingStrategyWire": { "type": "string", "description": "The order in which NagaAI tries the providers that serve a model. A NagaAI extension.", "enum": [ "reliability", "balanced", "latency", "throughput", "cache" ] }, "SearchContextSize": { "type": "string", "description": "How much of what a search turns up goes in front of the model.", "enum": [ "low", "medium", "high" ] }, "SearchResultBlockParam": { "type": "object", "description": "A search result replayed to the model, and the one block whose `citations` survives.", "properties": { "title": { "type": [ "string", "null" ], "description": "What the result is called. Its absence draws a refusal a step later." }, "source": { "type": [ "string", "null" ], "description": "Where the result came from. Its absence draws a refusal a step later." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextBlockParamPart" }, "description": "The text that was found, as `text` blocks. Absent means an empty list." }, "citations": { "type": [ "object", "null" ], "description": "Whether the model may cite this result.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "ServerToolUseBlockParam": { "type": "object", "description": "A call the model made to a server-side tool, replayed as history.", "properties": { "id": { "type": [ "string", "null" ], "description": "The identifier that pairs this call with the block reporting its outcome." }, "name": { "type": [ "string", "null" ], "description": "Which server tool was called. Only `web_search` goes further." }, "input": { "type": [ "object", "null" ], "description": "The arguments the model passed to the tool; only `query` counts.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "ShellTool": { "type": "object", "description": "A hosted tool the gateway takes and drops." }, "SpeechFormat": { "type": "string", "description": "The container synthesised speech comes back in, and the `Content-Type` it sets.", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "SpeechModel": { "type": "object", "description": "The request body of `POST /v1/audio/speech`, answered with audio.", "required": [ "model", "input", "voice" ], "properties": { "model": { "type": "string", "description": "The speech model to synthesise with, named by its id or alias." }, "input": { "type": "string", "description": "The text to read aloud, at most 32768 Unicode characters." }, "voice": { "type": "string", "description": "The voice to read in, by the name the model knows it under." }, "speed": { "type": [ "number", "null" ], "format": "double", "description": "How fast to read, as a multiplier of the model's normal pace. Zero or less draws a 400." }, "instructions": { "type": [ "string", "null" ], "description": "Free-form direction for how the text should be delivered." }, "response_format": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SpeechFormat" } ], "description": "The audio container to synthesise into, which also sets the answer's `Content-Type`." }, { "type": "null" } ] } } }, "StartupList": { "type": "object", "description": "Every startup the catalog records.", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogStartup" }, "description": "The startups, ordered by name." } }, "additionalProperties": false }, "StaticContent": { "type": "object", "description": "A block of predicted output, which reaches no provider.", "required": [ "content", "type" ], "properties": { "content": { "allOf": [ { "$ref": "#/components/schemas/StaticContentContent" } ], "description": "The text the model's reply is expected to match." }, "type": { "type": "string", "description": "The kind of predicted content, read as an ordinary string." } } }, "StaticContentContent": { "oneOf": [ { "type": "array", "title": "List of items", "items": {} }, { "type": "string", "title": "Plain text" } ], "description": "The predicted content itself: one string, or content parts." }, "StreamOptions": { "type": "object", "description": "Options that apply to a streaming request.", "properties": { "include_usage": { "type": "boolean", "description": "Whether one extra chunk carrying the request's token totals closes the stream." } } }, "TextBlockParam": { "type": "object", "description": "A run of plain text inside a content array.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text this block carries; the 20 MiB inline ceiling does not apply." } } }, "TextBlockParamPart": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextBlockParam" } ], "description": "`type: \"text\"` — the text block itself." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "`type: \"text\"` — the text block itself." } ], "description": "A `text` block where a bare list of them is expected, with its tag restored." }, "TextContent": { "type": "object", "description": "A run of plain text inside a message's content array.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text of this part." } } }, "TextInput": { "type": "object", "description": "A text part of a typed-parts `input` array.", "required": [ "type", "text" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/TextTag" } ], "description": "Always the literal `text`, and what selects this part shape." }, "text": { "type": "string", "description": "The text to moderate." } } }, "TextResponseFormat": { "type": "object", "description": "Plain text output, and what an absent `response_format` produces." }, "TextTag": { "type": "string", "description": "The tag of a text part.", "enum": [ "text" ] }, "ThinkingBlockParam": { "type": "object", "description": "A block of the model's own reasoning, replayed from an earlier assistant turn.", "required": [ "thinking" ], "properties": { "thinking": { "type": "string", "description": "The reasoning text, as the model wrote it." }, "signature": { "type": [ "string", "null" ], "description": "The opaque signature issued with that reasoning. Its absence draws a refusal." } } }, "ThinkingConfigAdaptiveParam": { "type": "object", "description": "Thinking depth left to the model, which sets no configuration at all." }, "ThinkingConfigDisabledParam": { "type": "object", "description": "Extended thinking turned off, which differs from leaving `thinking` out." }, "ThinkingConfigEnabledParam": { "type": "object", "description": "Extended thinking with a token budget. The budget picks a tier, and the figure itself reaches no provider.", "properties": { "budget_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "How many tokens the model may spend reasoning, and the value the tier follows from. Below 1024 draws a 400.", "minimum": 0 } } }, "ThinkingConfigParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ThinkingConfigEnabledParam" } ], "description": "Extended thinking on, with a token budget that decides the tier — see `ThinkingConfigEnabledParam` for the brackets and the refusals." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `enabled`.", "enum": [ "enabled" ] } } } ], "description": "Extended thinking on, with a token budget that decides the tier — see `ThinkingConfigEnabledParam` for the brackets and the refusals." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ThinkingConfigDisabledParam" } ], "description": "Extended thinking off: the provider is asked for no reasoning at all." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `disabled`.", "enum": [ "disabled" ] } } } ], "description": "Extended thinking off: the provider is asked for no reasoning at all." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ThinkingConfigAdaptiveParam" } ], "description": "Depth left to the model, which leaves the reasoning configuration unset entirely." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `adaptive`.", "enum": [ "adaptive" ] } } } ], "description": "Depth left to the model, which leaves the reasoning configuration unset entirely." } ], "description": "How much thinking the model does before it answers." }, "Tool": { "type": "object", "description": "A function tool: a `tools[]` entry typed `function`.", "required": [ "function" ], "properties": { "function": { "allOf": [ { "$ref": "#/components/schemas/FunctionDefinition" } ], "description": "The declaration itself — name, description and parameter schema." } } }, "ToolChoiceAllowedEntry": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunction" } ], "title": "Function tool", "description": "A function the model may call, spelled as in `tools[]`. An empty name drops the entry from the set." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceAllowedEntryStub" } ], "title": "Hosted or custom tool", "description": "A hosted or custom tool. The three web-search spellings stay in the set; the gateway strikes the other ten." } ], "description": "One tool of an allowed set: a function by name, or a tool by type." }, "ToolChoiceAllowedEntryStub": { "type": "object", "description": "An entry of an allowed set naming a tool rather than a function.", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/AllowedEntryType" } ], "description": "Which tool the entry names; web search is the one the gateway keeps." }, "name": { "type": [ "string", "null" ], "description": "The tool name for the families that carry one." } } }, "ToolChoiceAllowedTools": { "type": "object", "description": "A subset of the declared tools the model is confined to. An empty subset drops the whole choice.", "required": [ "type", "tools" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/AllowedToolsType" } ], "description": "Marks the choice as an allowed set. Always `allowed_tools`." }, "mode": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AllowedToolsMode" } ], "description": "How tightly the set binds: `auto` or `required`." }, { "type": "null" } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolChoiceAllowedEntry" }, "description": "The tools the model may pick from. More than 128 served tools draws a refusal." } } }, "ToolChoiceDroppedStub": { "type": "object", "description": "A choice naming a tool the gateway takes and drops.", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/DroppedChoiceType" } ], "description": "Which unserved tool family the choice names." }, "name": { "type": [ "string", "null" ], "description": "The tool name for the families that carry one, read and discarded." } } }, "ToolChoiceFunction": { "type": "object", "description": "A forced call to one function, with the name beside the tag.", "required": [ "type", "name" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunctionType" } ], "description": "Marks the choice as naming a function. Always `function`." }, "name": { "type": "string", "description": "The function to force, spelled as in `tools[]`. The gateway refuses an empty string." } } }, "ToolChoiceFunctionLegacy": { "type": "object", "description": "The same forced call, written chat-style. A NagaAI extension.", "required": [ "type", "function" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunctionType" } ], "description": "Always `function`. The name's place tells the two forms apart." }, "function": { "type": "object", "description": "Carries the function name under `name`; every value must be a string.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "ToolChoiceFunctionType": { "type": "string", "description": "The tag of a function choice. `function` is the only value this menu holds.", "enum": [ "function" ] }, "ToolChoiceHostedWebSearch": { "type": "object", "description": "A forced call to the hosted web search, where the provider offers one.", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/HostedWebSearchChoiceType" } ], "description": "Which of the three web-search spellings this names." } } }, "ToolChoiceMode": { "type": "string", "description": "The whole choice written as a single string.", "enum": [ "auto", "none", "required" ] }, "ToolChoiceNoneParam": { "type": "object", "description": "The body of the `none` form, whose discriminator is the whole object." }, "ToolChoiceParallelParam": { "type": "object", "description": "The body shared by the `auto` and `any` tool-choice forms.", "properties": { "disable_parallel_tool_use": { "type": [ "boolean", "null" ], "description": "Whether the model may ask for only one tool per turn. Absent leaves the question open." } } }, "ToolChoiceParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceParallelParam" } ], "description": "The model chooses for itself between answering in prose and calling one of the declared tools. Nothing is forced." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `auto`.", "enum": [ "auto" ] } } } ], "description": "The model chooses for itself between answering in prose and calling one of the declared tools. Nothing is forced." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceParallelParam" } ], "description": "The model must call a tool rather than answer in prose, and picks which one itself. That is the whole difference from `auto`, which also allows a plain answer, and from `tool`, which additionally fixes which tool is called." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `any`.", "enum": [ "any" ] } } } ], "description": "The model must call a tool rather than answer in prose, and picks which one itself. That is the whole difference from `auto`, which also allows a plain answer, and from `tool`, which additionally fixes which tool is called." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceToolParam" } ], "description": "The model must call the single tool the object names." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool`.", "enum": [ "tool" ] } } } ], "description": "The model must call the single tool the object names." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceNoneParam" } ], "description": "The model may not call any tool this turn, even though `tools` are declared for it to see." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `none`.", "enum": [ "none" ] } } } ], "description": "The model may not call any tool this turn, even though `tools` are declared for it to see." } ], "description": "What the model may do with the declared `tools`." }, "ToolChoiceToolParam": { "type": "object", "description": "The body of the `tool` form: the one tool the model must call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the tool the model has to call. An empty string draws a 400 a step later." }, "disable_parallel_tool_use": { "type": [ "boolean", "null" ], "description": "Whether the model may ask for only one tool per turn, once the named tool has been called." } } }, "ToolParam": { "type": "object", "description": "A tool the caller implements, carrying no `type` key.", "required": [ "name", "input_schema" ], "properties": { "name": { "type": "string", "description": "What the model calls the tool by, never empty." }, "description": { "type": [ "string", "null" ], "description": "What the tool does, written for the model to choose by." }, "input_schema": { "type": "object", "description": "A JSON Schema for the arguments the model must produce. Required, compiled at intake. A keyword the far side refuses travels no further.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the model's arguments follow `input_schema` exactly." } } }, "ToolReferenceBlockParam": { "type": "object", "description": "A reference to a tool by name, filtered out of the decoded output.", "properties": { "tool_name": { "type": [ "string", "null" ], "description": "The name of the tool being referenced, never read." } } }, "ToolResultBlockParam": { "type": "object", "description": "The answer to one client tool call, sent back in a `user` message.", "required": [ "tool_use_id" ], "properties": { "tool_use_id": { "type": "string", "description": "The `id` of the `tool_use` this answers, never empty." }, "content": { "allOf": [ { "$ref": "#/components/schemas/ToolResultBlockParamContent" } ], "description": "What the tool produced. Absent means the empty string.", "default": "" } } }, "ToolResultBlockParamContent": { "oneOf": [ { "type": "array", "title": "List of result blocks", "items": { "$ref": "#/components/schemas/ToolResultContentBlockParam" }, "description": "The output as an array of content entries." }, { "type": "string", "title": "Plain text", "description": "The output as a single run of text." } ], "description": "What a tool produced: one string, or an array of content entries." }, "ToolResultContentBlockParam": { "oneOf": [ { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextBlockParam" } ], "description": "Plain text handed back as the tool's output." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text`.", "enum": [ "text" ] } } } ], "description": "Plain text handed back as the tool's output." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageBlockParam" } ], "description": "An image handed back as the tool's output, on the same terms as an `image` block." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `image`.", "enum": [ "image" ] } } } ], "description": "An image handed back as the tool's output, on the same terms as an `image` block." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/SearchResultBlockParam" } ], "description": "A search result handed back as the tool's output, carrying its source, title and text." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `search_result`.", "enum": [ "search_result" ] } } } ], "description": "A search result handed back as the tool's output, carrying its source, title and text." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/DocumentBlockParam" } ], "description": "A document handed back as the tool's output. A `content` source leaves the entry nowhere to go, and the gateway drops it." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `document`.", "enum": [ "document" ] } } } ], "description": "A document handed back as the tool's output. A `content` source leaves the entry nowhere to go, and the gateway drops it." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolReferenceBlockParam" } ], "description": "A reference to a tool by name. Parsed and then filtered out of the output." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_reference`.", "enum": [ "tool_reference" ] } } } ], "description": "A reference to a tool by name. Parsed and then filtered out of the output." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "The replayed result of a hosted web-fetch call. Parsed and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `web_fetch_tool_result`.", "enum": [ "web_fetch_tool_result" ] } } } ], "description": "The replayed result of a hosted web-fetch call. Parsed and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "The replayed result of a hosted code-execution call. Parsed and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `code_execution_tool_result`.", "enum": [ "code_execution_tool_result" ] } } } ], "description": "The replayed result of a hosted code-execution call. Parsed and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "The replayed result of a hosted bash code-execution call. Parsed and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `bash_code_execution_tool_result`.", "enum": [ "bash_code_execution_tool_result" ] } } } ], "description": "The replayed result of a hosted bash code-execution call. Parsed and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "The replayed result of a hosted text-editor code-execution call. Parsed and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `text_editor_code_execution_tool_result`.", "enum": [ "text_editor_code_execution_tool_result" ] } } } ], "description": "The replayed result of a hosted text-editor code-execution call. Parsed and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "The replayed result of a hosted tool-search call. Parsed and dropped." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `tool_search_tool_result`.", "enum": [ "tool_search_tool_result" ] } } } ], "description": "The replayed result of a hosted tool-search call. Parsed and dropped." }, { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostedBlockParam" } ], "description": "A file offered to a hosted execution container, which the gateway drops." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The tag that selects this branch: `type` is `container_upload`.", "enum": [ "container_upload" ] } } } ], "description": "A file offered to a hosted execution container, which the gateway drops." } ], "description": "One entry of a `tool_result` block's content. Four of eleven members reach the model." }, "ToolSearchTool": { "type": "object", "description": "A tool search the caller runs: offered to the model as a `tool_search` function.", "properties": { "execution": { "type": [ "string", "null" ], "description": "Who runs the search. Only `client` is carried; `server` is dropped." }, "description": { "type": [ "string", "null" ], "description": "What the search does, written for the model." }, "parameters": { "type": [ "object", "null" ], "description": "The search's arguments, as a JSON Schema.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "ToolUnionParam": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolParam" } ], "title": "Client tool", "description": "A tool the caller implements and runs, declared without a `type` key." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolParam" } ], "title": "Web search tool", "description": "The built-in web search, declared with one of the two dated web-search stamps." }, { "allOf": [ { "$ref": "#/components/schemas/HostedToolParam" } ], "title": "Hosted tool", "description": "Everything else that carries a `type`: the hosted families the gateway drops, the long spelling of a client tool, and the unknown types it refuses." } ], "description": "One entry of `tools[]`, in one of the three shapes this dialect accepts." }, "ToolUseBlockParam": { "type": "object", "description": "A tool call the assistant made earlier, replayed as history.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The identifier a matching `tool_result` names back. It must not be empty." }, "name": { "type": "string", "description": "The name of the tool that was called, never empty." }, "input": { "type": "object", "description": "The arguments the call was made with. Absent means none.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "TotalStats": { "type": "object", "description": "The whole reporting window as one row.", "required": [ "total_requests", "total_cost", "total_input_tokens", "total_output_tokens" ], "properties": { "total_requests": { "type": "integer", "format": "int64", "description": "How many requests the account made in the window, failed ones included." }, "total_cost": { "type": "string", "description": "What the window cost in credits, as a decimal string." }, "total_input_tokens": { "type": "integer", "format": "int64", "description": "Input tokens summed over the window." }, "total_output_tokens": { "type": "integer", "format": "int64", "description": "Output tokens summed over the window." } } }, "Truncation": { "type": "string", "description": "What to do when the conversation outgrows the context window.", "enum": [ "auto", "disabled" ] }, "UrlImageSourceParam": { "type": "object", "description": "An image the provider fetches itself, named by URL.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Where the image lives: an `http(s)` URL, or a `data:` URI." } } }, "UrlPdfSourceParam": { "type": "object", "description": "A PDF the provider fetches itself, named by URL.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Where the document lives: an `http(s)` URL, or a `data:` URI." } } }, "Verbosity": { "type": "string", "description": "How long the reply runs. It reaches only some providers.", "enum": [ "low", "medium", "high" ] }, "WebSearchCallItem": { "type": "object", "description": "A web search the model ran earlier, replayed as history.", "properties": { "id": { "type": [ "string", "null" ], "description": "An identifier for this item. Nothing is resolved by it." }, "status": { "type": [ "string", "null" ], "description": "The state the search carried, taken as given." }, "action": { "type": [ "object", "null" ], "description": "What the search did. Three `type` shapes pass: `search`, `open_page` and `find_in_page`.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "WebSearchPreviewTool": { "type": "object", "description": "The earlier shape of the built-in web search, carried on the same terms.", "properties": { "search_context_size": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SearchContextSize" } ], "description": "How much search context goes in front of the model." }, { "type": "null" } ] }, "user_location": { "type": [ "object", "null" ], "description": "Roughly where the caller is, so results can favor that place.", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "WebSearchTool": { "type": "object", "description": "The built-in web search, and one of the two hosted tools the gateway carries.", "properties": { "filters": { "type": [ "object", "null" ], "description": "Narrowing applied to the search; the top-level `allowed_domains` wins over it.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "search_context_size": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SearchContextSize" } ], "description": "How much search context goes in front of the model." }, { "type": "null" } ] }, "user_location": { "type": [ "object", "null" ], "description": "Roughly where the caller is, so results can favor that place.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "external_web_access": { "type": [ "boolean", "null" ], "description": "Whether the search may reach the live web." }, "max_uses": { "type": [ "integer", "null" ], "format": "int64", "description": "How many searches one request may run. A NagaAI extension." }, "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Which domains results may come from. A NagaAI extension, exclusive with `blocked_domains`." }, "blocked_domains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Which domains results may not come from. A NagaAI extension, exclusive with `allowed_domains`." }, "allowed_callers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Who may invoke the tool. A NagaAI extension." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether the tool stays out of the opening instructions. A NagaAI extension." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the tool's inputs follow their schema exactly. A NagaAI extension." } } }, "WebSearchToolName": { "type": "string", "description": "The name a web-search entry carries: `web_search`.", "enum": [ "web_search" ] }, "WebSearchToolParam": { "type": "object", "description": "The built-in web search, and the one server-side family the gateway carries.", "required": [ "type", "name" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolVersion" } ], "description": "Which dated revision of the tool this asks for. Required." }, "name": { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolName" } ], "description": "The literal `web_search`. Required, even though only one value is legal." }, "user_location": { "type": [ "object", "null" ], "description": "Roughly where the caller is, so results can favor that place.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "search_context_size": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SearchContextSize" } ], "description": "How much search context goes in front of the model. A NagaAI extension." }, { "type": "null" } ] }, "external_web_access": { "type": [ "boolean", "null" ], "description": "Whether the search may reach the live web. A NagaAI extension." }, "max_uses": { "type": [ "integer", "null" ], "format": "int64", "description": "How many searches one request may run." }, "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Which domains results may come from. Exclusive with `blocked_domains`." }, "blocked_domains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Which domains results may not come from. Exclusive with `allowed_domains`." }, "allowed_callers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Who may invoke the tool." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether the tool stays out of the opening instructions." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether the tool's inputs follow their schema exactly." } } }, "WebSearchToolResultBlockParam": { "type": "object", "description": "What a server-side search returned, paired to an earlier call by `tool_use_id`.", "properties": { "tool_use_id": { "type": [ "string", "null" ], "description": "The `id` of the `server_tool_use` this closes." }, "content": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolResultContent" } ], "description": "The results, or the error object standing in for them." }, { "type": "null" } ] } } }, "WebSearchToolResultContent": { "oneOf": [ { "type": "array", "title": "List of result objects", "items": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "description": "The results the search returned, each tagged `web_search_result` with a string `url`." }, { "type": "object", "description": "A single object in place of the result array, tagged `web_search_tool_result_error`.", "additionalProperties": {}, "propertyNames": { "type": "string" } } ], "description": "What a `web_search_tool_result` block carries: the results, or a failure." }, "WebSearchToolVersion": { "type": "string", "description": "Which dated revision of the built-in web search an entry asks for.", "enum": [ "web_search_20250305", "web_search_20260209" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An account API key. Send it as `Authorization: Bearer `." }, "provisioningBearerAuth": { "type": "http", "scheme": "bearer", "description": "An account provisioning key. Send it as `Authorization: Bearer `. Provisioning keys manage the account and cannot reach a model." }, "xApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "An account API key. Send it as `x-api-key: `, the header Anthropic-style clients use." } } }, "security": [], "tags": [ { "name": "Chat Completions", "description": "The OpenAI Chat Completions dialect, with streaming, tools and multimodal input.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/chat", "description": "The OpenAI reference for this dialect." } }, { "name": "Messages", "description": "The Anthropic Messages dialect, as Claude-style clients and agents speak it.", "externalDocs": { "url": "https://docs.anthropic.com/en/api/messages", "description": "The Anthropic reference for this dialect." } }, { "name": "Responses", "description": "The OpenAI Responses dialect, with structured input, tools and streamed output items.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/responses", "description": "The OpenAI reference for this dialect." } }, { "name": "Embeddings", "description": "Vector embeddings for search, retrieval, clustering and ranking.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/embeddings", "description": "The OpenAI reference for this route." } }, { "name": "Images", "description": "Image generation and editing with multimodal models.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/images", "description": "The OpenAI reference for these routes." } }, { "name": "Audio", "description": "Speech from text, and text from uploaded audio.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/audio", "description": "The OpenAI reference for these routes." } }, { "name": "Moderations", "description": "Safety classification of text and image input.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/moderations", "description": "The OpenAI reference for this route." } }, { "name": "Models", "description": "The catalog of models, their capabilities and their prices.", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/models", "description": "The OpenAI reference for this route." } }, { "name": "Startups", "description": "The organizations whose models the catalog carries.", "externalDocs": { "url": "https://docs.naga.ac/get-started/models", "description": "The NagaAI guide to the model catalog." } }, { "name": "Account", "description": "The account's balance and its usage, behind a provisioning key.", "externalDocs": { "url": "https://docs.naga.ac/account/balance-and-activity", "description": "The NagaAI guide to balance and activity." } }, { "name": "API Keys", "description": "The account's API keys, behind a provisioning key.", "externalDocs": { "url": "https://docs.naga.ac/account/api-keys", "description": "The NagaAI guide to API keys." } } ], "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema" }