# 聊天补全 > 大语言模型 创建一次 Chat Completions 兼容对话请求。 ## 请求地址 `POST https://api.modelverse.cn/v1/chat/completions` ## 请求体 ## 响应 - **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 定义 ```json { "openapi": "3.1.0", "info": { "title": "Modelverse Chat Completions 兼容接口", "version": "1.0.0", "description": "Modelverse Chat Completions 兼容接口\n" }, "servers": [ { "url": "https://api.modelverse.cn", "description": "中国大陆节点，国内用户推荐，访问延迟低。" }, { "url": "https://api-sg.umodelverse.ai", "description": "新加坡节点，东南亚用户推荐，访问更快。" }, { "url": "https://api-us-ca.umodelverse.ai", "description": "美国洛杉矶节点，海外用户推荐，数据不回国。" }, { "url": "https://api-ge-fra.umodelverse.ai", "description": "法兰克福节点，欧洲用户推荐，访问更快。" } ], "tags": [ { "name": "Chat Completions", "description": "Compatible chat completion request." } ], "paths": { "/v1/chat/completions": { "post": { "tags": [ "Chat Completions" ], "operationId": "createChatCompletion", "summary": "聊天补全", "description": "创建一次 Chat Completions 兼容对话请求。\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": "对话消息列表，按历史顺序排列。\nrole 可取 developer、system、user、assistant、tool、function。\nfunction message 已属于旧版兼容；tool message 需要 tool_call_id。\n" }, "model": { "type": "string", "description": "模型名称或模型 ID，例如 gpt-5.5、glm-5.2、claude-sonnet-4-6 等。" }, "function_call": { "$ref": "#/components/schemas/FunctionCallOption", "description": "已弃用，使用 tool_choice 替代。可控制旧版 function 是否被调用。", "deprecated": true }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] }, "description": "输出模态列表。默认通常为 [\"text\"]；请求音频输出时通常还需要 audio 参数。" }, "frequency_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2, "description": "正值会降低已频繁出现 token 再次出现的概率，减少重复表达。" }, "logit_bias": { "type": "object", "additionalProperties": { "type": "number", "minimum": -100, "maximum": 100 }, "description": "JSON 对象，key 是 tokenizer token ID（JSON 中表现为字符串），value 是 -100 到 100 的偏置。\n-100 通常近似禁止某 token，100 通常强烈倾向选择某 token。\n" }, "logprobs": { "type": "boolean", "description": "是否返回每个输出 token 的 log probability。" }, "max_completion_tokens": { "type": [ "integer", "null" ], "minimum": 1, "description": "模型可生成的最大 token 数，包含可见输出 token 和推理 token。" }, "max_tokens": { "type": [ "integer", "null" ], "minimum": 1, "deprecated": true, "description": "已逐步由 max_completion_tokens 替代；用于限制文本生成 token 数。" }, "n": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 128, "default": 1, "description": "每条输入生成的 completion choices 数量；建议保持 1 以控制成本。" }, "parallel_tool_calls": { "type": "boolean", "description": "是否开启并行工具调用。" }, "prediction": { "$ref": "#/components/schemas/PredictionContent" }, "presence_penalty": { "type": [ "number", "null" ], "minimum": -2, "maximum": 2, "description": "正值会惩罚已经出现过的 token，使模型更倾向引入新内容。" }, "prompt_cache_key": { "type": "string", "description": "用于相似请求缓存命中优化。" }, "reasoning_effort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "控制推理模型的推理强度。\ngpt模型常见值为 none/minimal/low/medium/high/xhigh；\nglm-5.2 支持max；\n" }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "seed": { "type": [ "integer", "null" ], "description": "随机种子，用于提高可复现性，但不保证跨模型或跨版本完全一致。" }, "stop": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "type": "string" }, "title": "array" }, { "type": "null", "title": "null" } ], "description": "命中停止词时停止生成。不同模型对数量限制不同。" }, "store": { "type": [ "boolean", "null" ], "description": "是否允许平台存储请求/输出用于后续产品能力。" }, "stream": { "type": [ "boolean", "null" ], "default": false, "description": "是否以流式方式返回响应。" }, "temperature": { "type": [ "number", "null" ], "description": "采样温度，值越高越随机；建议不要和 top_p 同时大幅调整。" }, "tool_choice": { "$ref": "#/components/schemas/ToolChoice" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "工具定义列表。" }, "top_logprobs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "返回每个输出位置 top N token 的 log probabilities，通常需要 logprobs=true。" }, "top_p": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "nucleus sampling 参数；部分模型可能限制取值范围和小数位数。" }, "cache_control": { "$ref": "#/components/schemas/CacheControl", "description": "仅支持 Anthropic Claude 模型。" }, "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 指令；o1 及更新模型优先使用 developer 而不是 system。" }, "name": { "type": "string", "description": "可选参与者名称，用于区分同 role 参与者。" }, "content": { "$ref": "#/components/schemas/TextOnlyMessageContent" } } }, "SystemMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "const": "system", "description": "系统消息；部分推理/视觉模型不支持或不生效。" }, "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": "思考内容片段；透传历史思考内容时需保持完整未修改。" }, "encrypted_content": { "type": "string", "description": "加密思考内容。" }, "refusal": { "type": "string", "description": "助手拒绝回答的文本。" }, "partial": { "type": "boolean", "default": false, "description": "前缀续写开关；具体支持取决于模型。" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "上一轮模型返回的工具调用；多轮对话时需回传。" }, "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": "对应上一轮 assistant.tool_calls[$index].id。" }, "content": { "$ref": "#/components/schemas/ToolMessageContent" } } }, "FunctionMessage": { "type": "object", "additionalProperties": true, "required": [ "role", "name", "content" ], "deprecated": true, "properties": { "role": { "type": "string", "const": "function", "description": "旧版 function message；新接口优先使用 role=tool。" }, "name": { "type": "string" }, "content": { "type": "string", "description": "仅支持字符串；结构化结果需先 JSON 序列化。" } } }, "TextOnlyMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ], "description": "文本内容；数组形式只支持 text 内容块。" }, "UserMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "title": "string" }, { "$ref": "#/components/schemas/ChatContentPart" } ] }, "title": "array" } ], "description": "user 消息内容。可以是字符串、字符串数组或多模态内容块数组。\n具体内容块是否支持取决于模型。\n" }, "AssistantMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "null", "title": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AssistantContentPart" }, "title": "array" } ], "description": "assistant 内容；可为 string、null、文本块数组或单个 refusal 块。" }, "ToolMessageContent": { "anyOf": [ { "type": "string", "title": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/TextContentPart" }, "title": "array" } ], "description": "工具输出内容；结构化数据需 JSON 序列化为字符串。" }, "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": "图片 URL、Base64 data URL 或文件引用。" }, "detail": { "type": "string", "enum": [ "auto", "low", "high", "default", "xhigh" ], "description": "图片细节等级；具体枚举取决于模型。" }, "max_long_side_pixel": { "type": "integer", "description": "最长边限制；具体支持取决于模型。" }, "image_pixel_limit": { "$ref": "#/components/schemas/ImagePixelLimit" } } } } }, "ImagePixelLimit": { "type": "object", "additionalProperties": false, "properties": { "min_pixels": { "type": "integer" }, "max_pixels": { "type": "integer" } }, "description": "图片像素限制，优先级高于 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 音频数据；部分模型也允许 URL 字符串。" }, "url": { "type": "string", "description": "音频 URL。" }, "file_id": { "type": "string", "description": "文件 ID。" }, "format": { "type": "string", "description": "音频格式，例如 wav、mp3 或 MIME 类型。" } } } } }, "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 文件数据或 data URL。" }, "file_url": { "type": "string" }, "filename": { "type": "string", "description": "文件名；部分模型在使用 file_data 时可能要求必填。" } } } } }, "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": "文件 URL；此内容块不使用 Base64。" } } } } }, "VideoFramesContentPart": { "type": "object", "additionalProperties": true, "required": [ "type", "video" ], "properties": { "type": { "type": "string", "const": "video" }, "video": { "type": "array", "items": { "type": "string" }, "description": "视频图片帧列表。" }, "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": "视频 URL、Base64 data URL 或文件引用。" }, "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": "模型先前音频响应 ID；多轮语音对话可回传。" } } }, "ChatCompletionAudioParam": { "type": "object", "additionalProperties": false, "required": [ "format", "voice" ], "properties": { "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ], "description": "输出音频格式。" }, "voice": { "anyOf": [ { "type": "string", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse", "marin", "cedar" ], "title": "string" }, { "type": "string", "description": "其它模型支持的声音名称。", "title": "string" }, { "$ref": "#/components/schemas/CustomVoice" } ], "description": "内置声音名或自定义 voice object。" } } }, "CustomVoice": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "自定义声音 ID，例如 voice_1234。" } } }, "FunctionCallOption": { "anyOf": [ { "type": "string", "enum": [ "none", "auto" ], "title": "string" }, { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "强制调用的函数名。" } }, "title": "object" } ] }, "FunctionCall": { "type": "object", "additionalProperties": false, "required": [ "name", "arguments" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "模型生成的 JSON 字符串，使用前必须校验。" } } }, "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 数组索引。" }, "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON 字符串，执行工具前应解析并校验。" } } } } }, "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": "响应或历史消息中可能出现的内置工具调用。" }, "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；部分模型可能要求必填。" }, "strict": { "type": "boolean", "description": "是否启用严格 schema 遵循；具体支持取决于模型。" } } } } }, "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 工具配置。" }, "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": "没有 tools 时默认 none；有 tools 时通常默认 auto。" }, "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": "旧 JSON mode；通常仍需在 system/user 消息中明确要求输出 JSON。" }, "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": "结构化输出；strict=true 时通常只支持 JSON Schema 子集。" }, "ResponseFormatGrammar": { "type": "object", "additionalProperties": true, "required": [ "type", "grammar" ], "properties": { "type": { "type": "string", "const": "grammar" }, "grammar": { "type": "string" } }, "description": "扩展 response_format。" }, "ResponseFormatPython": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "python" } }, "description": "扩展 response_format。" }, "StreamOptions": { "type": "object", "additionalProperties": true, "properties": { "include_obfuscation": { "type": "boolean", "description": "如果信任网络链路，可设为 false 减少带宽。" }, "include_usage": { "type": "boolean", "description": "在 [DONE] 前额外返回 usage chunk；流中断时可能收不到。" } } }, "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": "期望匹配的静态预测内容。" } } }, "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": "内容块缓存 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": "统一开启思考模式时使用 enabled，关闭时使用 disabled。\n仅部分模型支持 auto 或 adaptive，表示由模型根据对话内容自动判断是否启用思考模式。\n" } } }, "AnyJson": { "description": "任意 JSON 值。", "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": "聊天补全响应体；非流式返回完整对象，流式返回 chunk 对象。" }, "ChatCompletionObject": { "type": "object", "additionalProperties": true, "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "聊天补全响应的唯一标识符。" }, "u_trace_id": { "type": "string", "description": "请求 ID。" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChoice" } }, "created": { "type": "integer", "description": "聊天补全创建时的 Unix 秒级时间戳。" }, "model": { "type": "string", "description": "用于生成此聊天补全的模型。" }, "object": { "type": "string", "enum": [ "chat.completion", "chat.completion.chunk" ], "description": "对象类型；非流式通常为 chat.completion，流式通常为 chat.completion.chunk。" }, "service_tier": { "type": [ "string", "null" ], "enum": [ "auto", "default", "flex", "scale", "priority", "fast", null ], "description": "服务层级或时延/吞吐偏好。" }, "usage": { "$ref": "#/components/schemas/CompletionUsage" }, "content_filter": { "type": "array", "description": "内容过滤结果。", "items": { "$ref": "#/components/schemas/ContentFilterResult" } }, "metadata": { "type": "object", "additionalProperties": true, "description": "响应附加元数据。" } } }, "ChatCompletionChunk": { "type": "object", "additionalProperties": true, "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "与同一次流式响应相关的唯一标识符。" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChunkChoice" } }, "created": { "type": "integer", "description": "chunk 创建时的 Unix 秒级时间戳。" }, "model": { "type": "string", "description": "生成此 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": "此选项在 choices 数组中的索引。" }, "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": "命中的停止条件。" }, "message": { "$ref": "#/components/schemas/ChatCompletionResponseMessage" }, "moderation_hit_type": { "type": [ "string", "null" ], "enum": [ "severe_violation", "violence", null ], "description": "内容护栏命中类型。" } } }, "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": "生成停止原因；null 常见于流式响应尚未结束时。" }, "ChatCompletionResponseMessage": { "type": "object", "additionalProperties": true, "required": [ "role" ], "properties": { "role": { "type": "string", "const": "assistant" }, "name": { "type": "string" }, "reasoning": { "type": [ "string", "null" ], "description": "推理输出文本。" }, "reasoning_content": { "type": "string", "description": "思考内容片段。" }, "encrypted_content": { "type": "string", "description": "加密思考内容。" }, "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": "音频内容字符串。" }, "refusal": { "type": [ "string", "null" ], "description": "模型拒绝回答的文本。" }, "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": "结构化思考片段类型。" }, "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": "音频响应的唯一标识符。" }, "data": { "type": "string", "description": "Base64 音频字节或流式音频片段。" }, "expires_at": { "type": "integer", "description": "Unix 秒级过期时间戳。" }, "transcript": { "type": "string", "description": "生成音频的转录文本。" } } }, "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": "模型生成的 JSON 字符串，调用前需要校验。" } } } } }, "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": "token 的 UTF-8 字节表示。" }, "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": "生成内容使用的 token 数。" }, "prompt_tokens": { "type": "integer", "description": "提示词使用的 token 数。" }, "reasoning_tokens": { "type": "integer", "description": "思考内容消耗的 token 数。" }, "total_tokens": { "type": "integer", "description": "请求总 token 数。" }, "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": "业务状态码。" }, "status_msg": { "type": "string", "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" } ] } } } } } } } } ```