# Chat Completion > Large Language Models Creates an OpenAI-compatible Chat Completions request. ## Endpoint `POST https://api.modelverse.cn/v1/chat/completions` ## Request Body ## Responses - **200** — Chat completion response. Response details can be described by responses_body.jsonc. - **400** — Bad request. Usually caused by unsupported fields, invalid message shape, or model-specific limits. - **default** — Error response. ## OpenAPI Definition ```json { "openapi": "3.1.0", "info": { "title": "Chat Completions API Reference", "version": "1.0.0", "description": "OpenAI-compatible Chat Completions API for ModelVerse.\n" }, "servers": [ { "url": "https://api.modelverse.cn", "description": "Mainland China endpoint, recommended for users in China for lower latency." }, { "url": "https://api-sg.umodelverse.ai", "description": "Singapore endpoint, recommended for users in Southeast Asia." }, { "url": "https://api-us-ca.umodelverse.ai", "description": "Los Angeles endpoint, recommended for international users. Data is not routed back to China." }, { "url": "https://api-ge-fra.umodelverse.ai", "description": "Frankfurt endpoint, recommended for users in Europe." } ], "tags": [ { "name": "Chat Completions", "description": "Compatible chat completion request." } ], "paths": { "/v1/chat/completions": { "post": { "tags": [ "Chat Completions" ], "operationId": "createChatCompletion", "summary": "Chat Completion", "description": "Creates an OpenAI-compatible Chat Completions request.\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "examples": { "minimal": { "summary": "Minimal text request", "value": { "model": "model-name", "messages": [ { "role": "user", "content": "你好" } ] } }, "multimodal": { "summary": "Multimodal user message", "value": { "model": "model-name", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png", "detail": "auto" } } ] } ] } } } } } }, "responses": { "200": { "description": "Chat completion response. Response details can be described by responses_body.jsonc.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "Bad request. Usually caused by unsupported fields, invalid message shape, or model-specific limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "schemas": { "ChatCompletionRequest": { "type": "object", "additionalProperties": true, "required": [ "model", "messages" ], "properties": { "messages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChatCompletionMessage" }, "description": "Conversation messages in chronological order.\nrole can be developer, system, user, assistant, tool, or function.\nfunction messages are legacy compatibility messages; tool messages require tool_call_id.\n" }, "model": { "type": "string", "description": "Model name or model ID, such as gpt-5.5, glm-5.2, or claude-sonnet-4-6." }, "function_call": { "$ref": "#/components/schemas/FunctionCallOption", "description": "Deprecated. Use tool_choice instead. Controls whether a legacy function is called.", "deprecated": true }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] }, "description": "Output modality list. The default is usually [\"text\"]; audio output usually also requires the audio parameter." }, "frequency_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2, "description": "Positive values reduce the likelihood of tokens that have already appeared frequently, reducing repetition." }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "JSON object whose keys are tokenizer token IDs (represented as strings in JSON) and whose values are biases from -100 to 100.\n-100 usually approximates banning a token, while 100 strongly favors selecting a token.\n" }, "logprobs": { "type": "boolean", "description": "Whether to return the log probability for each output token." }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 1, "description": "Maximum number of tokens the model can generate, including visible output tokens and reasoning tokens." }, "max_tokens": { "type": [ "integer", "null" ], "minimum": 1, "deprecated": true, "description": "Gradually replaced by max_completion_tokens. Limits the number of text generation tokens." }, "n": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 128, "default": 1, "description": "Number of completion choices to generate for each input. Keep this at 1 to control costs." }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to enable parallel tool calls." }, "prediction": { "$ref": "#/components/schemas/PredictionContent" }, "presence_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2, "description": "Positive values penalize tokens that have already appeared, making the model more likely to introduce new content." }, "prompt_cache_key": { "type": "string", "description": "Used to improve cache hits for similar requests." }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "Controls the reasoning intensity for reasoning models.\nCommon GPT model values are none/minimal/low/medium/high/xhigh.\nglm-5.2 supports max.\n" }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "seed": { "type": [ "integer", "null" ], "description": "Random seed that improves reproducibility but does not guarantee exact consistency across models or versions." }, "stop": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "type": "string" }, "title": "array" }, { "type": "null", "title": "null" } ], "description": "Stops generation when a stop sequence is matched. Limits vary by model." }, "store": { "type": [ "boolean", "null" ], "description": "Whether to allow the platform to store requests or outputs for later product features." }, "stream": { "type": [ "boolean", "null" ], "default": false, "description": "Whether to return the response as a stream." }, "temperature": { "type": [ "number", "null" ], "description": "Sampling temperature. Higher values are more random; avoid changing this and top_p substantially at the same time." }, "tool_choice": { "$ref": "#/components/schemas/ToolChoice" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "List of tool definitions." }, "top_logprobs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "Returns the top N token log probabilities for each output position. Usually requires logprobs=true." }, "top_p": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Nucleus sampling parameter. Some models may restrict the value range and decimal precision." }, "cache_control": { "$ref": "#/components/schemas/CacheControl", "description": "Only Anthropic Claude models are supported." }, "thinking": { "$ref": "#/components/schemas/ThinkingConfig" } } }, "ChatCompletionMessage": { "oneOf": [ { "$ref": "#/components/schemas/DeveloperMessage" }, { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage" }, { "$ref": "#/components/schemas/ToolMessage" }, { "$ref": "#/components/schemas/FunctionMessage" } ], "discriminator": { "propertyName": "role" } }, "DeveloperMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "const": "developer", "description": "Developer instruction. o1 and newer models prefer developer over system." }, "name": { "type": "string", "description": "Optional participant name, used to distinguish participants with the same role." }, "content": { "$ref": "#/components/schemas/TextOnlyMessageContent" } } }, "SystemMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "const": "system", "description": "System message. Some reasoning or vision models do not support it or do not apply it." }, "name": { "type": "string" }, "content": { "$ref": "#/components/schemas/TextOnlyMessageContent" } } }, "UserMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "const": "user" }, "name": { "type": "string" }, "content": { "$ref": "#/components/schemas/UserMessageContent" } } }, "AssistantMessage": { "type": "object", "additionalProperties": true, "required": [ "role" ], "properties": { "role": { "type": "string", "const": "assistant" }, "name": { "type": "string" }, "audio": { "$ref": "#/components/schemas/AssistantAudio" }, "content": { "$ref": "#/components/schemas/AssistantMessageContent" }, "reasoning_content": { "type": "string", "description": "Reasoning content fragment. Preserve historical thinking content completely and without modification when passing it through." }, "encrypted_content": { "type": "string", "description": "Encrypted thinking content." }, "refusal": { "type": "string", "description": "Text of the assistant refusal." }, "partial": { "type": "boolean", "default": false, "description": "Prefix continuation switch. Support depends on the model." }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls returned by the model in the previous turn. Pass them back in multi-turn conversations." }, "function_call": { "$ref": "#/components/schemas/FunctionCall", "deprecated": true } } }, "ToolMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "tool_call_id", "content" ], "properties": { "role": { "type": "string", "const": "tool" }, "tool_call_id": { "type": "string", "description": "Corresponds to assistant.tool_calls[$index].id from the previous turn." }, "content": { "$ref": "#/components/schemas/ToolMessageContent" } } }, "FunctionMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "name", "content" ], "deprecated": true, "properties": { "role": { "type": "string", "const": "function", "description": "Legacy function message. Prefer role=tool for new APIs." }, "name": { "type": "string" }, "content": { "type": "string", "description": "Only strings are supported. Structured results must be JSON-serialized first." } } }, "TextOnlyMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ], "description": "Text content. Array form supports only text content parts." }, "UserMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "title": "string" }, { "$ref": "#/components/schemas/ChatContentPart" } ] }, "title": "array" } ], "description": "User message content. Can be a string, an array of strings, or an array of multimodal content parts.\nSupported content parts depend on the model.\n" }, "AssistantMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "null", "title": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AssistantContentPart" }, "title": "array" } ], "description": "Assistant content. Can be a string, null, an array of text parts, or a single refusal part." }, "ToolMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ], "description": "Tool output content. Structured data must be JSON-serialized as a string." }, "ChatContentPart": { "oneOf": [ { "$ref": "#/components/schemas/TextContentPart" }, { "$ref": "#/components/schemas/ImageUrlContentPart" }, { "$ref": "#/components/schemas/InputAudioContentPart" }, { "$ref": "#/components/schemas/FileContentPart" }, { "$ref": "#/components/schemas/FileUrlContentPart" }, { "$ref": "#/components/schemas/VideoFramesContentPart" }, { "$ref": "#/components/schemas/VideoUrlContentPart" } ], "discriminator": { "propertyName": "type" } }, "AssistantContentPart": { "oneOf": [ { "$ref": "#/components/schemas/TextContentPart" }, { "$ref": "#/components/schemas/RefusalContentPart" } ], "discriminator": { "propertyName": "type" } }, "TextContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" }, "cache_control": { "$ref": "#/components/schemas/CacheControl" } } }, "ImageUrlContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "const": "image_url" }, "image_url": { "type": "object", "additionalProperties": true, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Image URL, Base64 data URL, or file reference." }, "detail": { "type": "string", "enum": [ "auto", "low", "high", "default", "xhigh" ], "description": "Image detail level. Specific enum values depend on the model." }, "max_long_side_pixel": { "type": "integer", "description": "Longest-side limit. Support depends on the model." }, "image_pixel_limit": { "$ref": "#/components/schemas/ImagePixelLimit" } } } } }, "ImagePixelLimit": { "type": "object", "additionalProperties": false, "properties": { "min_pixels": { "type": "integer" }, "max_pixels": { "type": "integer" } }, "description": "Image pixel limit, with higher priority than detail." }, "InputAudioContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "input_audio" ], "properties": { "type": { "type": "string", "const": "input_audio" }, "input_audio": { "type": "object", "additionalProperties": true, "properties": { "data": { "type": "string", "description": "Base64 audio data. Some models also allow a URL string." }, "url": { "type": "string", "description": "Audio URL." }, "file_id": { "type": "string", "description": "File ID." }, "format": { "type": "string", "description": "Audio format, such as wav, mp3, or a MIME type." } } } } }, "FileContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "file" ], "properties": { "type": { "type": "string", "const": "file" }, "file": { "type": "object", "additionalProperties": true, "properties": { "file_id": { "type": "string" }, "file_data": { "type": "string", "description": "Base64 file data or data URL." }, "file_url": { "type": "string" }, "filename": { "type": "string", "description": "File name. Some models may require it when file_data is used." } } } } }, "FileUrlContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "file_url" ], "properties": { "type": { "type": "string", "const": "file_url" }, "file_url": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "File URL. This content part does not use Base64." } } } } }, "VideoFramesContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "video" ], "properties": { "type": { "type": "string", "const": "video" }, "video": { "type": "array", "items": { "type": "string" }, "description": "Video image-frame list." }, "fps": { "type": "number" }, "min_pixels": { "type": "integer" }, "max_pixels": { "type": "integer" }, "total_pixels": { "type": "integer" } } }, "VideoUrlContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "video_url" ], "properties": { "type": { "type": "string", "const": "video_url" }, "video_url": { "type": "object", "additionalProperties": true, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Video URL, Base64 data URL, or file reference." }, "file_id": { "type": "string" }, "detail": { "type": "string", "enum": [ "low", "default", "high" ] }, "fps": { "type": "number", "minimum": 0.2, "maximum": 5 }, "max_long_side_pixel": { "type": "integer" } } }, "fps": { "type": "number" }, "min_pixels": { "type": "integer" }, "max_pixels": { "type": "integer" }, "total_pixels": { "type": "integer" } } }, "RefusalContentPart": { "type": "object", "additionalProperties": false, "required": [ "type", "refusal" ], "properties": { "type": { "type": "string", "const": "refusal" }, "refusal": { "type": "string" } } }, "AssistantAudio": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Previous model audio response ID. Can be passed back in multi-turn voice conversations." } } }, "ChatCompletionAudioParam": { "type": "object", "additionalProperties": false, "required": [ "format", "voice" ], "properties": { "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ], "description": "Output audio format." }, "voice": { "anyOf": [ { "type": "string", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse", "marin", "cedar" ], "title": "string" }, { "type": "string", "description": "Voice names supported by other models.", "title": "string" }, { "$ref": "#/components/schemas/CustomVoice" } ], "description": "Built-in voice name or custom voice object." } } }, "CustomVoice": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Custom voice ID, such as voice_1234." } } }, "FunctionCallOption": { "anyOf": [ { "type": "string", "enum": [ "none", "auto" ], "title": "string" }, { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the function to force-call." } }, "title": "object" } ] }, "FunctionCall": { "type": "object", "additionalProperties": false, "required": [ "name", "arguments" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "Model-generated JSON string. Validate it before use." } } }, "ToolCall": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolCall" }, { "$ref": "#/components/schemas/CustomToolCall" }, { "$ref": "#/components/schemas/ProviderToolCall" } ] }, "FunctionToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function" }, "function": { "type": "object", "additionalProperties": true, "required": [ "name", "arguments" ], "properties": { "index": { "type": "integer", "description": "tool_calls array index." }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON string. Parse and validate it before executing the tool." } } } } }, "CustomToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "custom" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "custom" }, "custom": { "type": "object", "additionalProperties": true, "required": [ "name", "input" ], "properties": { "name": { "type": "string" }, "input": { "type": "string" } } } } }, "ProviderToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "web_search", "retrieval", "mcp" ] }, "web_search": { "$ref": "#/components/schemas/AnyJson" }, "retrieval": { "$ref": "#/components/schemas/AnyJson" }, "mcp": { "$ref": "#/components/schemas/AnyJson" } }, "description": "Built-in tool call that may appear in responses or historical messages." }, "ToolDefinition": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolDefinition" }, { "$ref": "#/components/schemas/CustomToolDefinition" }, { "$ref": "#/components/schemas/WebSearchToolDefinition" }, { "$ref": "#/components/schemas/RetrievalToolDefinition" }, { "$ref": "#/components/schemas/McpToolDefinition" }, { "$ref": "#/components/schemas/ServerToolDefinition" } ] }, "FunctionToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "additionalProperties": true, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "object", "additionalProperties": true, "description": "JSON Schema object. Some models may require it." }, "strict": { "type": "boolean", "description": "Whether to enable strict schema adherence. Support depends on the model." } } } } }, "CustomToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type", "custom" ], "properties": { "type": { "type": "string", "const": "custom" }, "custom": { "type": "object", "additionalProperties": true, "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "format": { "oneOf": [ { "$ref": "#/components/schemas/CustomToolTextFormat" }, { "$ref": "#/components/schemas/CustomToolGrammarFormat" } ] } } } } }, "CustomToolTextFormat": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "text" } } }, "CustomToolGrammarFormat": { "type": "object", "additionalProperties": false, "required": [ "type", "grammar" ], "properties": { "type": { "type": "string", "const": "grammar" }, "grammar": { "type": "object", "additionalProperties": false, "required": [ "definition", "syntax" ], "properties": { "definition": { "type": "string" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] } } } } }, "WebSearchToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "web_search" }, "web_search": { "type": "object", "additionalProperties": true, "properties": { "enable": { "type": "boolean" }, "search_engine": { "type": "string" }, "search_query": { "type": "string" }, "search_intent": { "type": "string" }, "count": { "type": "integer" }, "search_domain_filter": { "type": "string" }, "search_recency_filter": { "type": "string" }, "content_size": { "type": "string" }, "result_sequence": { "type": "string" }, "search_result": { "type": "boolean" }, "require_search": { "type": "boolean" }, "search_prompt": { "type": "string" } } } }, "description": "web_search tool configuration." }, "RetrievalToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type", "retrieval" ], "properties": { "type": { "type": "string", "const": "retrieval" }, "retrieval": { "type": "object", "additionalProperties": true, "properties": { "knowledge_id": { "type": "string" }, "prompt_template": { "type": "string" } } } } }, "McpToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type", "mcp" ], "properties": { "type": { "type": "string", "const": "mcp" }, "mcp": { "type": "object", "additionalProperties": true, "properties": { "server_label": { "type": "string" }, "server_url": { "type": "string" }, "transport_type": { "type": "string" }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "ServerToolDefinition": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "server:web_search", "server:web_fetch", "server:bash", "server:subagent", "server:advisor", "server:image_generation" ] } }, "description": "Server tools." }, "ToolChoice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ], "title": "string" }, { "$ref": "#/components/schemas/FunctionToolChoice" }, { "$ref": "#/components/schemas/CustomToolChoice" }, { "$ref": "#/components/schemas/AllowedToolsChoice" }, { "$ref": "#/components/schemas/ServerToolChoice" } ], "description": "Defaults to none when tools is absent, and usually defaults to auto when tools is present." }, "FunctionToolChoice": { "type": "object", "additionalProperties": false, "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" } } } } }, "CustomToolChoice": { "type": "object", "additionalProperties": false, "required": [ "type", "custom" ], "properties": { "type": { "type": "string", "const": "custom" }, "custom": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" } } } } }, "AllowedToolsChoice": { "type": "object", "additionalProperties": false, "required": [ "type", "allowed_tools" ], "properties": { "type": { "type": "string", "const": "allowed_tools" }, "allowed_tools": { "type": "object", "additionalProperties": false, "required": [ "mode", "tools" ], "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ] }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "ServerToolChoice": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "server:web_search", "server:web_fetch", "server:bash", "server:subagent", "server:advisor", "server:image_generation" ] } } }, "ResponseFormat": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJsonObject" }, { "$ref": "#/components/schemas/ResponseFormatJsonSchema" }, { "$ref": "#/components/schemas/ResponseFormatGrammar" }, { "$ref": "#/components/schemas/ResponseFormatPython" } ] }, "ResponseFormatText": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "text" } } }, "ResponseFormatJsonObject": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "json_object" } }, "description": "Legacy JSON mode. You usually still need to explicitly ask for JSON output in the system/user message." }, "ResponseFormatJsonSchema": { "type": "object", "additionalProperties": false, "required": [ "type", "json_schema" ], "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" } } } }, "description": "Structured output. When strict=true, usually only a subset of JSON Schema is supported." }, "ResponseFormatGrammar": { "type": "object", "additionalProperties": true, "required": [ "type", "grammar" ], "properties": { "type": { "type": "string", "const": "grammar" }, "grammar": { "type": "string" } }, "description": "Extended response_format." }, "ResponseFormatPython": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "python" } }, "description": "Extended response_format." }, "StreamOptions": { "type": "object", "additionalProperties": true, "properties": { "include_obfuscation": { "type": "boolean", "description": "Set to false to reduce bandwidth if you trust the network path." }, "include_usage": { "type": "boolean", "description": "Returns an extra usage chunk before [DONE]. It may not be received if the stream is interrupted." } } }, "PredictionContent": { "type": "object", "additionalProperties": false, "required": [ "type", "content" ], "properties": { "type": { "type": "string", "const": "content" }, "content": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ], "description": "Static predicted content expected to match." } } }, "WebSearchOptions": { "type": "object", "additionalProperties": true, "properties": { "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "user_location": { "type": "object", "additionalProperties": true, "properties": { "approximate": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "approximate" }, "city": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "region": { "type": "string" }, "timezone": { "type": "string" } } } } } } }, "CacheControl": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "ephemeral" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "description": "Content-part cache TTL." } } }, "StopServerToolCondition": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "finish_reason_is", "has_tool_call", "max_cost", "max_tokens_used", "step_count_is" ] }, "finish_reason": { "type": "string" }, "tool_name": { "type": "string" }, "max_cost": { "type": "number" }, "max_tokens_used": { "type": "integer" }, "step_count": { "type": "integer" } } }, "ThinkingConfig": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled", "auto", "adaptive" ], "description": "Use enabled to turn on unified thinking mode, and disabled to turn it off.\nOnly some models support auto or adaptive, where the model decides whether to enable thinking based on the conversation.\n" } } }, "AnyJson": { "description": "Any JSON value.", "anyOf": [ { "type": "object", "additionalProperties": true, "title": "object" }, { "type": "array", "items": {}, "title": "array" }, { "type": "string", "title": "string" }, { "type": "number", "title": "number" }, { "type": "integer", "title": "integer" }, { "type": "boolean", "title": "boolean" }, { "type": "null", "title": "null" } ] }, "ChatCompletionResponse": { "oneOf": [ { "$ref": "#/components/schemas/ChatCompletionObject" }, { "$ref": "#/components/schemas/ChatCompletionChunk" } ], "description": "Chat completion response body. Non-streaming responses return a full object; streaming responses return chunk objects." }, "ChatCompletionObject": { "type": "object", "additionalProperties": true, "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the chat completion response." }, "u_trace_id": { "type": "string", "description": "Request ID." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChoice" } }, "created": { "type": "integer", "description": "Unix timestamp in seconds when the chat completion was created." }, "model": { "type": "string", "description": "Model used to generate this chat completion." }, "object": { "type": "string", "enum": [ "chat.completion", "chat.completion.chunk" ], "description": "Object type. Non-streaming responses are usually chat.completion; streaming responses are usually chat.completion.chunk." }, "service_tier": { "type": [ "string", "null" ], "enum": [ "auto", "default", "flex", "scale", "priority", "fast", null ], "description": "Service tier or latency/throughput preference." }, "usage": { "$ref": "#/components/schemas/CompletionUsage" }, "content_filter": { "type": "array", "description": "Content filtering results.", "items": { "$ref": "#/components/schemas/ContentFilterResult" } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional response metadata." } } }, "ChatCompletionChunk": { "type": "object", "additionalProperties": true, "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "Unique identifier associated with the same streaming response." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChunkChoice" } }, "created": { "type": "integer", "description": "Unix timestamp in seconds when the chunk was created." }, "model": { "type": "string", "description": "Model that generated this chunk." }, "object": { "type": "string", "const": "chat.completion.chunk" }, "service_tier": { "type": [ "string", "null" ], "enum": [ "auto", "default", "flex", "scale", "priority", "fast", null ] }, "system_fingerprint": { "type": [ "string", "null" ] }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/CompletionUsage" }, { "type": "null", "title": "null" } ] } } }, "ChatCompletionChoice": { "type": "object", "additionalProperties": true, "required": [ "index", "message" ], "properties": { "finish_reason": { "$ref": "#/components/schemas/FinishReason" }, "index": { "type": "integer", "description": "Index of this choice in the choices array." }, "logprobs": { "anyOf": [ { "$ref": "#/components/schemas/ChoiceLogprobs" }, { "type": "null", "title": "null" } ] }, "matched_stop": { "anyOf": [ { "type": "integer", "title": "integer" }, { "type": "string", "title": "string" }, { "type": "null", "title": "null" } ], "description": "Matched stop condition." }, "message": { "$ref": "#/components/schemas/ChatCompletionResponseMessage" }, "moderation_hit_type": { "type": [ "string", "null" ], "enum": [ "severe_violation", "violence", null ], "description": "Content guardrail hit type." } } }, "ChatCompletionChunkChoice": { "type": "object", "additionalProperties": true, "required": [ "index", "delta" ], "properties": { "delta": { "$ref": "#/components/schemas/ChatCompletionResponseDelta" }, "finish_reason": { "$ref": "#/components/schemas/FinishReason" }, "index": { "type": "integer" }, "logprobs": { "anyOf": [ { "$ref": "#/components/schemas/ChoiceLogprobs" }, { "type": "null", "title": "null" } ] } } }, "FinishReason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call", "abort", "error", "sensitive", "network_error", "model_context_window_exceeded", null ], "description": "Reason generation stopped. null is common when a streaming response has not finished yet." }, "ChatCompletionResponseMessage": { "type": "object", "additionalProperties": true, "required": [ "role" ], "properties": { "role": { "type": "string", "const": "assistant" }, "name": { "type": "string" }, "reasoning": { "type": [ "string", "null" ], "description": "Reasoning output text." }, "reasoning_content": { "type": "string", "description": "Thinking content fragment." }, "encrypted_content": { "type": "string", "description": "Encrypted thinking content." }, "reasoning_details": { "type": "array", "items": { "$ref": "#/components/schemas/ReasoningDetail" } }, "content": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "null", "title": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ] }, "audio_content": { "type": "string", "description": "Audio content string." }, "refusal": { "type": [ "string", "null" ], "description": "Text of the model refusal." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseImage" } }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseAnnotation" } }, "audio": { "$ref": "#/components/schemas/ResponseAudio" }, "function_call": { "$ref": "#/components/schemas/FunctionCall", "deprecated": true }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseToolCall" } } } }, "ChatCompletionResponseDelta": { "type": "object", "additionalProperties": true, "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": [ "string", "null" ] }, "reasoning_content": { "type": "string" }, "encrypted_content": { "type": "string" }, "function_call": { "anyOf": [ { "$ref": "#/components/schemas/FunctionCall" }, { "type": "null", "title": "null" } ], "deprecated": true }, "audio": { "$ref": "#/components/schemas/ResponseAudio" }, "refusal": { "type": [ "string", "null" ] }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseToolCall" } } } }, "ReasoningDetail": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Structured thinking fragment type." }, "id": { "type": "string" }, "format": { "type": "string" }, "index": { "type": "integer" }, "text": { "type": "string" } } }, "ResponseImage": { "type": "object", "additionalProperties": true, "properties": { "image_url": { "type": "object", "additionalProperties": true, "properties": { "url": { "type": "string" } } } } }, "ResponseAnnotation": { "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "url_citation" }, "url_citation": { "type": "object", "additionalProperties": true, "properties": { "start_index": { "type": "integer" }, "end_index": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" } } } } }, "ResponseAudio": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the audio response." }, "data": { "type": "string", "description": "Base64 audio bytes or streaming audio fragment." }, "expires_at": { "type": "integer", "description": "Unix expiration timestamp in seconds." }, "transcript": { "type": "string", "description": "Transcript text generated for the audio." } } }, "ResponseToolCall": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFunctionToolCall" }, { "$ref": "#/components/schemas/ResponseCustomToolCall" }, { "$ref": "#/components/schemas/ResponseMcpToolCall" } ] }, "ResponseFunctionToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function" }, "index": { "type": "integer" }, "function": { "type": "object", "additionalProperties": true, "required": [ "name", "arguments" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "Model-generated JSON string. Validate it before calling." } } } } }, "ResponseCustomToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "custom" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "custom" }, "custom": { "type": "object", "additionalProperties": true, "required": [ "name", "input" ], "properties": { "name": { "type": "string" }, "input": { "type": "string" } } } } }, "ResponseMcpToolCall": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "mcp" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "mcp" }, "mcp": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "server_label": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "output": { "$ref": "#/components/schemas/AnyJson" }, "error": { "$ref": "#/components/schemas/AnyJson" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/AnyJson" } } } } } }, "ChoiceLogprobs": { "type": "object", "additionalProperties": true, "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TokenLogprob" } }, "refusal": { "type": "array", "items": { "$ref": "#/components/schemas/TokenLogprob" } } } }, "TokenLogprob": { "type": "object", "additionalProperties": true, "required": [ "token", "logprob" ], "properties": { "token": { "type": "string" }, "bytes": { "anyOf": [ { "type": "array", "items": { "type": "integer" }, "title": "array" }, { "type": "null", "title": "null" } ], "description": "UTF-8 byte representation of the token." }, "logprob": { "type": "number" }, "top_logprobs": { "type": "array", "items": { "$ref": "#/components/schemas/TopLogprob" } } } }, "TopLogprob": { "type": "object", "additionalProperties": true, "required": [ "token", "logprob" ], "properties": { "token": { "type": "string" }, "bytes": { "anyOf": [ { "type": "array", "items": { "type": "integer" }, "title": "array" }, { "type": "null", "title": "null" } ] }, "logprob": { "type": "number" } } }, "ModerationEnvelope": { "type": "object", "additionalProperties": true, "properties": { "input": { "oneOf": [ { "$ref": "#/components/schemas/ModerationResults" }, { "$ref": "#/components/schemas/ModerationError" } ] }, "output": { "oneOf": [ { "$ref": "#/components/schemas/ModerationResults" }, { "$ref": "#/components/schemas/ModerationError" } ] } } }, "ModerationResults": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "const": "moderation_results" }, "model": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ModerationResult" } } } }, "ModerationResult": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "const": "moderation_result" }, "model": { "type": "string" }, "flagged": { "type": "boolean" }, "categories": { "type": "object", "additionalProperties": { "type": "boolean" } }, "category_scores": { "type": "object", "additionalProperties": { "type": "number" } }, "category_applied_input_types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "ModerationError": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "const": "error" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "RoutingMetadata": { "type": "object", "additionalProperties": true, "properties": { "attempt": { "type": "integer" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingAttempt" } }, "endpoints": { "type": "object", "additionalProperties": true, "properties": { "available": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingEndpoint" } }, "total": { "type": "integer" } } }, "is_byok": { "type": "boolean" }, "params": { "type": "object", "additionalProperties": true, "properties": { "quality_floor": { "type": "number" }, "throughput_floor": { "type": "number" }, "version_group": { "type": "string" } } }, "pipeline": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPipelineStep" } }, "region": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "null", "title": "null" } ] }, "requested": { "type": "string" }, "strategy": { "type": "string", "enum": [ "direct", "auto", "free", "latest", "alias", "fallback", "pareto", "bodybuilder", "fusion" ] }, "summary": { "type": "string" } } }, "RoutingAttempt": { "type": "object", "additionalProperties": true, "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "integer" } } }, "RoutingEndpoint": { "type": "object", "additionalProperties": true, "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "selected": { "type": "boolean" } } }, "RoutingPipelineStep": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "cost_usd": { "type": "number" }, "data": { "$ref": "#/components/schemas/AnyJson" } } }, "CompletionUsage": { "type": "object", "additionalProperties": true, "properties": { "completion_tokens": { "type": "integer", "description": "Number of tokens used by generated content." }, "prompt_tokens": { "type": "integer", "description": "Number of tokens used by the prompt." }, "reasoning_tokens": { "type": "integer", "description": "Number of tokens consumed by thinking content." }, "total_tokens": { "type": "integer", "description": "Total number of tokens in the request." }, "completion_tokens_details": { "$ref": "#/components/schemas/CompletionTokensDetails" }, "prompt_tokens_details": { "$ref": "#/components/schemas/PromptTokensDetails" } } }, "CompletionTokensDetails": { "type": "object", "additionalProperties": true, "properties": { "accepted_prediction_tokens": { "type": "integer" }, "audio_tokens": { "type": "integer" }, "reasoning_tokens": { "type": "integer" }, "text_tokens": { "type": "integer" }, "rejected_prediction_tokens": { "type": "integer" } } }, "PromptTokensDetails": { "type": "object", "additionalProperties": true, "properties": { "audio_tokens": { "type": "integer" }, "audio_cached_tokens": { "type": "integer" }, "text_tokens": { "type": "integer" }, "video_tokens": { "type": "integer" }, "image_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" }, "cached_tokens": { "type": "integer" }, "cache_creation": { "type": "object", "additionalProperties": true, "properties": { "ephemeral_5m_input_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_type": { "type": "string", "const": "ephemeral" } } } } }, "ContentFilterResult": { "type": "object", "additionalProperties": true, "properties": { "role": { "type": "string", "enum": [ "assistant", "user", "history" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 3 } } }, "BaseResponse": { "type": "object", "additionalProperties": true, "properties": { "status_code": { "type": "integer", "description": "Business status code." }, "status_msg": { "type": "string", "description": "Error details or status description." } } }, "ErrorResponse": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "integer", "title": "integer" }, { "type": "null", "title": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true, "title": "object" }, { "type": "null", "title": "null" } ] } } } } } } } } ```