Multimodal Understanding API Reference
将文本、图片、视频、音频传给模型并接收文本或结构化结果的 VOD API。请先指定 VOD 应用程序的 SubAppId 签发 API 密钥,再用已签发的 ApiToken 调用模型。
调用规范
调用准备
1. 选择 VOD 应用程序
在 VOD 中创建要使用的应用程序并确认 SubAppId。密钥签发与配额管理均使用此 ID。模型调用会应用与密钥关联的应用程序信息。
2. 签发 API 密钥
调用 vod.intl.tencentcloudapi.com 的 CreateAigcApiToken。此步骤使用腾讯云 SecretId 与 SecretKey 进行 TC3 签名。
{
"SubAppId": 123456789
}使用 TC3 调用脚本时:
python3 tencent-api.py vod CreateAigcApiToken create-token.json将响应中的 ApiToken 用作后续模型请求的 Bearer 密钥。请勿将应用程序 ID 或 SecretKey 作为 Bearer 密钥传递。
3. 用签发的密钥调用模型
export VOD_API_TOKEN='your-vod-aigc-token'
curl https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer ${VOD_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "用一句话说明为什么要逐步拉长重试间隔。"
}
],
"max_tokens": 2048,
"stream": false
}'模型调用的地址为 mmu.vod-qcloud.com。请与签发密钥所用的腾讯云 API 地址区分开。
API 密钥管理
| 操作 | VOD action | 认证 |
|---|---|---|
| 签发 | CreateAigcApiToken | TC3 签名 |
| 列表查询 | DescribeAigcApiTokens | TC3 签名 |
| 删除 | DeleteAigcApiToken | TC3 签名 |
| 配额查询 | DescribeAigcQuotas | TC3 签名 |
| 配额生成 / 变更 / 删除 | CreateAigcQuota / ModifyAigcQuota / DeleteAigcQuota | TC3 签名 |
密钥长期有效,最多可签发 50 个。生成与删除后反映到列表可能需要约 30 秒。需为子账号授予相应 VOD action 的 CAM 权限。
协议选择
| 协议 | 请求路径 | 输入的中心字段 | 结果的中心字段 |
|---|---|---|---|
| Chat Completions | POST /v1/chat/completions | messages | choices.message |
| Responses | POST /v1/responses | input | output |
| Messages | POST /v1/messages | messages / system | content |
即使是同一模型可以用多种协议调用,但请求字段与响应结构不同。请在各模型文档的支持协议中选择要使用的路径,再按该规范构造请求。
认证与会话头
| 头 | 必填 | 值 / 用途 |
|---|---|---|
Authorization | 必填 | Bearer ${VOD_API_TOKEN} |
Content-Type | 必填 | application/json |
x-api-key | 可选 | Messages 联动中可用的 API 密钥头 |
X-Request-Id | 可选 | 请求追踪 ID |
Tx-User-Session-Id | 可选 | 串联同一对话请求的会话 ID |
查询可调用模型
curl https://mmu.vod-qcloud.com/v1/models \
-H "Authorization: Bearer ${VOD_API_TOKEN}"响应中的 data.id 即为请求中要填入的 model 值。请区分模型的显示名称与 API 标识符。
API 列表与请求参数
Chat Completions
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | 必填 | String | 模型 ID |
messages | 必填 | Array | 含角色与内容的对话历史 |
stream | 可选 | Boolean | 是否 SSE 流式 |
max_tokens | 可选 | Integer | 最大生成令牌数。包含推理令牌 |
max_completion_tokens | 可选 | Integer | SDK 兼容用生成令牌上限。请勿与 max_tokens 重复指定 |
temperature | 可选 | Number | 采样温度。允许范围参见各模型文档 |
top_p | 可选 | Number | 基于累积概率的采样 |
top_k | 可选 | Integer | 支持模型的候选令牌数限制 |
reasoning_effort | 可选 | String | 各模型的推理强度 |
thinking_enabled | 可选 | Boolean | 支持模型是否启用推理 |
tools | 可选 | Array | 可调用工具与输入 Schema |
tool_choice | 可选 | String / Object | 自动选择、强制使用工具、选择特定工具 |
response_format | 可选 | Object | 普通文本、JSON 或 JSON Schema 输出 |
stream_options | 可选 | Object | 通过 include_usage=true 接收流式用量 |
max_tokens 不是输入与输出相加的上下文上限。模型的上下文上限、生成上限、账号的 TPM 配额各自单独适用。
消息结构
| 字段 | 类型 | 说明 |
|---|---|---|
role | String | system / developer / user / assistant / tool |
content | String / Array | 文本或媒体 Part 数组 |
tool_calls | Array | 模型请求的函数名与参数 |
tool_call_id | String | 连接工具结果与原始调用的 ID |
响应示例
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "拉长重试间隔可以避免请求集中涌向故障服务器。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 32,
"total_tokens": 56
}
}finish_reason=length 表示已达到生成上限。在使用推理的请求中,请设置上限时为最终答案也保留令牌。
Responses
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | 必填 | String | 模型 ID |
input | 必填 | String / Array | 输入文本、消息、工具结果 |
instructions | 可选 | String | 模型应遵循的响应指令 |
max_output_tokens | 可选 | Integer | 含推理的最大输出令牌 |
reasoning | 可选 | Object | effort 等支持模型的推理设置 |
text | 可选 | Object | 输出格式与支持模型的文本设置 |
tools | 可选 | Array | 函数名、说明、参数 Schema |
tool_choice | 可选 | String / Object | 工具选择方式 |
stream | 可选 | Boolean | 是否 SSE 流式 |
请求示例
{
"model": "gpt-5.6-sol",
"instructions": "请用中文简洁回答。",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "请说明哪些情况需要让缓存失效。"
}
]
}
],
"reasoning": {
"effort": "low"
},
"max_output_tokens": 2048,
"stream": false
}响应示例
{
"id": "resp_example",
"object": "response",
"status": "completed",
"model": "gpt-5.6-sol",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "源数据变化时,需要刷新缓存或使其失效。",
"annotations":
}
]
}
],
"usage": {
"input_tokens": 24,
"output_tokens": 32,
"total_tokens": 56
}
}output 中除消息外还可包含推理与函数调用项。文本从 type=message 的 content 中读取 type=output_text。
Messages
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | 必填 | String | 模型 ID |
messages | 必填 | Array | user / assistant 对话历史 |
max_tokens | 必填 | Integer | 最大生成令牌 |
system | 可选 | String / Array | 与对话历史分离的响应指令 |
stream | 可选 | Boolean | 是否 SSE 流式 |
temperature | 可选 | Number | 支持模型的采样温度 |
top_p / top_k | 可选 | Number / Integer | 支持模型的采样设置 |
thinking | 可选 | Object | 支持模型的推理方式与预算 |
output_config | 可选 | Object | 支持模型的推理强度等输出设置 |
tools | 可选 | Array | name、description、input_schema |
tool_choice | 可选 | Object | auto、any、tool 等工具选择方式 |
stop_sequences | 可选 | Array | 停止生成的字符串列表 |
请求示例
{
"model": "deepseek-v4.1-flash",
"system": "请用中文回答。",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请说明请求超时与重试策略。"
}
]
}
],
"max_tokens": 2048,
"stream": false
}响应示例
{
"id": "msg_example",
"type": "message",
"role": "assistant",
"model": "deepseek-v4.1-flash",
"content": [
{
"type": "text",
"text": "超时时无法确定请求是否已完成,因此重试时需要考虑重复执行。"
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 24,
"output_tokens": 32
}
}推理设置
| 协议 | 设置位置 | 示例 |
|---|---|---|
| Chat Completions | 顶层 reasoning_effort | "reasoning_effort": "high" |
| Chat Completions | 支持模型的 thinking_enabled | "thinking_enabled": true |
| Responses | reasoning.effort | "reasoning": {"effort": "high"} |
| Messages | 各模型的 thinking / output_config | 参见各模型文档中的设置 |
推理设置的名称与允许值随协议与模型版本而不同。请勿将 thinking_enabled 通用地放入所有模型。返回的推理令牌计入生成令牌用量。
Media Input
Chat Completions 的 Part
| type | 输入字段 | 内容 |
|---|---|---|
text | text | 问题与指令 |
image_url | image_url.url | 图片 URL 或 data URL |
video_url | video_url.url | 视频 URL |
input_audio | input_audio | 音频 URL 或 data / format |
file | file.file_url / file.file_data / file.file_name | 文件 URL 或 Base64 数据与名称 |
媒体支持范围请在各模型文档中确认。请勿将视频与音频的支持与否等同于图片输入支持与否。超过 100MB 的视频请使用 URL 输入。
对话与角色
system 用于回答规则,user 用于问题与媒体,assistant 用于此前的模型响应。工具结果通过 Chat Completions 的 tool、Responses 的 function_call_output、Messages 的 tool_result 传递。
Chat Completions 详细字段
协议的字段结构。各模型支持的功能与允许值遵循该模型的各版本规范。
核心参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | 字符串 | 必填 | - | 模型标识符。平台的默认服务 ID 与模型名称相同(例:hy3、deepseek-v4-flash)。自定义服务格式为 ep-xxxxxxxx。 |
messages | 数组 | 必填 | - | 聊天上下文消息数组。详见 Messages 参数。 |
stream | 布尔值 | 可选 | false | 是否启用流式输出(SSE)。 |
stream_options | 对象 | 可选 | - | 流式选项。仅在 stream=true 时适用。 |
stream_options.include_usage | 布尔值 | 可选 | false | 流式模式的最后一个分块是否包含 usage 统计。平台始终请求用量,此字段仅控制是否传递给客户端。 |
Messages 参数
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
role | 字符串 | 必填 | 固定为 "system" |
content | 字符串 | 必填 | 设定模型行为与上下文的系统指令。 |
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
role | 字符串 | 必填 | 固定为 "user" |
content | 字符串或数组 | 必填 | 普通文本对应字符串,多模态内容对应数组(参见下方 Content Part)。 |
| 字段 | 类型 | 说明 |
|---|---|---|
type | 字符串 | 内容类型:"text" / "image_url" / "video_url" / "file_url" |
text | 字符串 | type="text" 时的文本内容。 |
image_url | 对象 | type="image_url" 时的图片信息。 |
image_url.url | 字符串 | 图片 HTTP(S) URL 或 data:image/...;base64,... 格式的 Data URL |
image_url.detail | 字符串 | 图片分辨率策略:"auto" / "low" / "high"。默认值为 "auto"。 |
video_url | 对象 | type="video_url" 时的视频信息。 |
video_url.url | 字符串 | 视频 HTTP(S) URL。 |
file_url | 对象 | type="file_url" 时的文件信息。 |
file_url.url | 字符串 | 文件 HTTP URL(仅支持直接 HTTP 链接,不支持 Base64)。 |
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
role | 字符串 | 必填 | 固定为 "assistant" |
content | 字符串 | 可选 | 模型响应文本(若无 tool_calls 则必填)。 |
reasoning_content | 字符串 | 可选 | 推理链内容。思考时会随模型响应返回,在多轮对话中保持上下文连贯需原样再次输入。 |
reasoning_details | 数组 | 可选 | 含签名的推理链块数组。在多轮对话中保持上下文连贯需原样再次传递。 |
tool_calls | 数组 | 可选 | 工具调用列表。参见 工具调用参数。 |
prefix | 布尔值 | 可选 | 部分 DeepSeek 模型支持。设为 true 时,模型会将此消息的内容用作续写前缀,且需要相应的 Beta 端点。在标准端点中此字段被忽略,不影响请求结果。 |
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
role | 字符串 | 必填 | 固定为 "tool" |
content | 字符串 | 必填 | 工具函数返回的结果内容(建议用 JSON 字符串格式)。 |
tool_call_id | 字符串 | 必填 | 与 assistant.tool_calls.id 对应的值。 |
name | 字符串 | 可选 | 工具函数名称。 |
生成控制参数
| 参数 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
temperature | 实数 | 可选 | 1.0 | [0.0, 2.0] | 采样温度。值越高输出越随机,越低越确定。通常只调整此参数与 top_p 中的一个。 |
top_p | 实数 | 可选 | 1.0 | (0.0, 1.0] | 核采样概率阈值。top_p=0 在平台中会被规范化为 null(与默认值相同)。 |
max_tokens | 整数 | 可选 | 模型最大值 | ≥ 1 | 单次响应可生成的最大令牌数。超过此限制时 finish_reason 为 "length"。 |
max_completion_tokens | 整数 | 可选 | 模型最大值 | ≥ 1 | 可生成的最大令牌数(OpenAI 的新字段,语义上与 max_tokens 相同)。请只提供其中一个。平台优先使用 max_completion_tokens。 |
n | 整数 | 可选 | 1 | ≥ 1 | 候选响应数。为 n > 1 时按总令牌数计费。部分模型不支持。启用推理模式时 n 必须为 1,否则返回 400 错误。 |
stop | 字符串或数组 | 可选 | - | 最多 4 个 | 停止序列。出现匹配的序列时立即停止生成。超过 4 个 时会在校验中被拒绝。 |
seed | 整数 | 可选 | - | 任意整数 | 随机种子。使用相同种子时,系统会尽力保证输出一致。 |
frequency_penalty | 实数 | 可选 | 0 | [-2.0, 2.0] | 频率惩罚。正值会降低已出现令牌的重复概率。0 会被规范化为 null。 |
presence_penalty | 实数 | 可选 | 0 | [-2.0, 2.0] | 存在惩罚。正值会鼓励生成新主题。0 会被规范化为 null。 |
logprobs | 布尔值 | 可选 | false | - | 是否返回输出令牌的对数概率。 |
top_logprobs | 整数 | 可选 | 0 | [0, 20] | 返回每个位置概率最高的 N 个令牌。需要 logprobs=true,否则校验失败。 |
reasoning_effort | 字符串 | 可选 | - | "low" / "medium" / "high" | 推理深度。适用于推理模型。Hunyuan 模型会应用内部映射转换。 |
响应格式参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
response_format | 对象 | 可选 | {"type":"text"} | 控制响应格式。 |
response_format.type | 字符串 | 必填 | "text" | 格式类型:"text" / "json_object" / "json_schema"。 |
response_format.json_schema | 对象 | 条件必填 | - | type="json_schema" 时必填。定义输出的 JSON 结构。 |
response_format.json_schema.name | 字符串 | 必填 | - | Schema 名称。 |
response_format.json_schema.schema | 对象 | 必填 | - | JSON Schema 定义(遵循 JSON Schema 规范)。 |
response_format.json_schema.strict | 布尔值 | 可选 | false | 是否强制严格匹配 Schema。 |
工具调用参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
tools | 数组 | 可选 | - | 工具定义列表。 |
tools.type | 字符串 | 必填 | - | 固定为 "function"。 |
tools.function | 对象 | 必填 | - | 函数定义。 |
tools.function.name | 字符串 | 必填 | - | 工具函数名称(仅含字母、数字、下划线、连字符)。 |
tools.function.description | 字符串 | 可选 | - | 说明工具函数,帮助模型判断调用时机。 |
tools.function.parameters | 对象 | 可选 | {} | 输入参数定义(JSON Schema 对象格式)。 |
tool_choice | 字符串或对象 | 可选 | "auto" | 工具调用策略。详见下方枚举。 |
parallel_tool_calls | 布尔值 | 可选 | true | 是否允许多个工具并行调用。 |
| 值 | 说明 |
|---|---|
"none" | 不调用工具(在 Hunyuan 环境下 tools 字段也一并留空)。 |
"auto" | 由模型自行决定是否调用工具(默认值)。 |
"required" | 强制模型调用一个或多个工具。注意:启用思考模式时(deepseek-v4-* 等模型默认启用),使用此值或指定函数对象会返回 400 错误。使用前必须显式传递 thinking: {"type": "disabled"}。 |
{"type":"function","function":{"name":"xxx"}} | 指定要调用的工具。 |
思考模式参数
| 参数 | 类型 | 必填 | 默认值 | 说明 | 适用模型 |
|---|---|---|---|---|---|
thinking | 对象 | 可选 | - | 思考模式控制(标准方式) | 思考模型(例:Hy 及 DeepSeek) |
thinking.type | 字符串 | 必填 | - | 启用为 "enabled" / 禁用为 "disabled" / 自适应模式为 "adaptive"。传递 thinking 对象时此字段必填。若未提供 type 而只提供 budget_tokens,则返回 400 错误。 | 思考模型(与 thinking 相同,可用的具体值因模型而异)。 |
thinking.budget_tokens | 整数 | 可选 | 8192(自动填入) | 推理过程的最大令牌数。若为 type=enabled 且未指定此值,则自动填入 8192。该值为预期上限而非硬性限制。部分模型的实际推理令牌数可能超过设定值。准确的推理令牌数请参考响应中的 usage.completion_tokens_details.reasoning_tokens。 | 思考模型(部分模型仅供参考,不严格执行)。 |
enable_thinking | 布尔值 | 可选 | - | 是否启用思考模式(简化开关)。是 thinking.type 的替代方案,部分模型(例:DeepSeek 系列)可用。建议统一使用 thinking.type。 | Hy 及 DeepSeek 等部分模型 |
thinking_budget | 整数 | 可选 | - | 推理过程的最大令牌数(简化字段)。必须与 enable_thinking 一起使用。建议统一使用 thinking.budget_tokens。 | Hy 及 DeepSeek 等部分模型 |
interleaved_thinking | 布尔值 | 可选 | - | 交错推理链模式。推理与输出同时进行,适合流式展示。此字段为扩展功能,实际支持程度因模型而异。不支持的模型不会产生错误,而是忽略此字段。 | 部分模型(以具体模型功能说明为准) |
reasoning_split | 布尔值 | 可选 | - | 将推理内容与最终答案作为独立分段输出。此字段为扩展功能。不支持的模型不会产生错误,而是忽略此字段。 | 部分模型 |
缓存参数
| 参数 | 类型 | 必填 | 默认值 | 说明 | 适用模型 |
|---|---|---|---|---|---|
prompt_cache_key | 字符串 | 可选 | - | 手动指定 Prompt 缓存键。键相同的请求可复用缓存。缓存命中后按缓存价格计费。可在响应的 usage.prompt_tokens_details.cached_tokens 中确认命中的缓存令牌数。 | 支持 Prompt Cache 的模型 |
其他参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
user | 字符串 | 可选 | - | 最终用户标识符。为检测滥用与追踪用量,会原样传递给模型服务。 |
user_id | 字符串或数字 | 可选 | - | 平台业务层的用户 ID(兼容数字类型,平台会自动转换为字符串)。仅用于平台内部用户识别,不会传给模型服务。要向模型服务传递用户标识符请使用 user 字段。 |
safety_identifier | 字符串 | 可选 | - | 安全标识符。风控系统用于追踪用户级内容审核。 |
extra_body | 对象 | 可选 | - | 平台不解析、原样传给模型服务的附加参数。部分模型会将此字段合并到请求体顶层,其他模型服务则会忽略。 |
顶层结构
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | chatcmpl-{uuid} 格式的唯一请求标识符(由平台生成,与模型服务返回的 ID 无关)。 |
object | 字符串 | 对象类型,固定为 "chat.completion"。 |
created | 整数 | 生成时间(Unix 时间戳,秒)。 |
model | 字符串 | 用户请求中传入的原始模型名称(并非模型服务实际使用的模型名称)。 |
choices | 数组 | 候选结果列表,元素数量与请求中指定的 n 相同。 |
usage | 对象 | 令牌用量统计。详见 "usage" 对象。 |
search_info | 对象或 null | 联网搜索信息(使用 Hunyuan/AISearch 路径时包含,否则为 null)。 |
Choices 数组元素
| 字段 | 类型 | 说明 |
|---|---|---|
index | 整数 | choices 数组内的选项索引,从 0 开始。 |
message | 对象 | 响应消息对象。详见 message 对象。 |
finish_reason | 字符串 | 生成结束原因。参见下方枚举。 |
logprobs | 对象或 null | 令牌概率信息(需在请求中设置 logprobs=true)。 |
| 值 | 说明 | 处理建议 |
|---|---|---|
"stop" | 正常结束(模型自行停止或与 stop 序列匹配)。 | 正常处理即可。 |
"length" | 达到 max_tokens / max_completion_tokens 限制导致输出被截断。 | 建议增大 max_tokens 的值,或将内容分段生成。 |
"tool_calls" | 模型需要调用工具。 | 执行工具并将结果作为 tool 消息包含进来继续请求。 |
"content_filter" | 内容被安全策略过滤。 | 请确认输入内容是否触发安全规则。 |
| 字段 | 类型 | 说明 | 适用场景 |
|---|---|---|---|
role | 字符串 | 固定为 "assistant" | 全部 |
content | 字符串或 null | 响应文本内容。存在 tool_calls 时可能为 null。 | 全部 |
reasoning_content | 字符串 | 推理链 / 推理过程内容 | 思考模型 |
reasoning_details | 数组 | 推理链块数组(含 signature) | 思考模型 |
tool_calls | 数组 | 工具调用列表 | 函数调用 |
refusal | 字符串或 null | 拒绝原因 | 内容安全过滤 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | call_{uuid} 格式的唯一工具调用 ID。 |
type | 字符串 | 固定为 "function"。 |
function.name | 字符串 | 被调函数的名称。 |
function.arguments | 字符串 | 函数参数(JSON 字符串格式,使用前需以 JSON.parse 解析)。 |
Usage 对象
| 字段 | 类型 | 说明 |
|---|---|---|
prompt_tokens | 整数 | 输入令牌数(含 system、messages 及工具定义的令牌)。 |
completion_tokens | 整数 | 输出令牌数(含推理令牌)。 |
total_tokens | 整数 | 总令牌数 |
cache_read_tokens | 整数 | 通过 Prompt Cache 命中读取的令牌数(部分模型可用,可降低计费)。 |
cache_write_tokens | 整数 | 写入 Prompt Cache 的令牌数(部分模型可用)。 |
prompt_tokens_details | 对象 | 输入令牌明细(部分模型可用)。 |
prompt_tokens_details.cached_tokens | 整数 | 已缓存的令牌数 |
completion_tokens_details | 对象 | 输出令牌明细(部分模型可用)。 |
completion_tokens_details.reasoning_tokens | 整数 | 推理所用令牌数(OpenAI 兼容路径)。 |
completion_tokens_details.audio_tokens | 整数 | 音频输出所用令牌数 |
| 字段 | 类型 | 说明 |
|---|---|---|
object | 字符串 | 固定为 "chat.completion.chunk"。 |
choices.delta | 对象 | 增量内容。 |
choices.delta.role | 字符串 | 仅出现在第一个分块,值为 "assistant"。 |
choices.delta.content | 字符串 | 增量文本片段,累积拼接后即为完整响应。 |
choices.delta.reasoning_content | 字符串 | 增量推理链片段(推理链模式下先于 content 输出)。 |
choices.delta.reasoning_details | 数组 | 增量推理链块(含 signature。流结束后需完整收集并在多轮中返回)。 |
choices.delta.tool_calls | 数组 | 增量工具调用(含标识数组位置的 index 字段)。 |
choices.delta.search_results | 数组 | 增量联网搜索结果(部分模型在流中推送)。 |
choices.finish_reason | 字符串或 null | 生成中为 null,完成时会变为结束原因。 |
usage | 对象或 null | 仅在 include_usage=true 时的最后一个正式分块中包含。 |
| 场景 | 处理方式 |
|---|---|
首个数据包之前失败(HTTP 200 头写入之前) | 返回标准 JSON 错误体,此处可正常解析错误码。若配置了 Fallback Provider,会自动执行回退重试。 |
200 响应头发送后出错 | 平台会在 SSE 流中插入 data: {"error":{"type":"...","message":"..."}}\\n\\n 错误帧,再发送 data: [DONE]\\n\\n 帧结束流。客户端需检查 delta 中是否包含 error 字段。 |
示例:多轮思考过程对话(含 signature)
Responses 详细字段
协议的字段结构。各模型支持的功能与允许值遵循该模型的各版本规范。
基本参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | 字符串 | 可选 | 用于生成响应的模型 ID(例:hy3)。 |
input | 字符串或数组 | 可选 | 传给模型的文本、图片或文件输入。字符串表示普通文本(等同于 user 角色的文本)。数组表示输入项列表。详见 输入类型详细信息。 |
instructions | 字符串 | 可选 | 插入模型上下文的系统(或开发者)消息。系统消息与 previous_response_id 一起使用时,此前响应的指令不会延续到下一次响应,因此可以替换系统消息。 |
stream | 布尔值 | 可选 | 设为 true 时,模型响应数据通过 SSE 流式传输,事件包含 response.created、response.output_text.delta、response.completed 等。 |
生成控制参数
| 参数 | 类型 | 取值范围 | 说明 |
|---|---|---|---|
max_output_tokens | 数字 | ≥ 1 | 响应中可生成的最大令牌数,包含展示的输出令牌与推理令牌。推理模型的推理令牌也计入此限制。 |
temperature | 数字 | [0, 2] | 控制输出随机性的采样温度。值越高输出越随机、越有创造性,越低越集中、越确定。 |
top_p | 数字 | (0, 1] | 核采样参数。模型仅考虑累积概率质量处于前 top_p 的令牌。建议只调整 temperature 与 top_p 中的一个。 |
truncation | 字符串 | "auto" / "disabled" | 上下文超过模型最大长度时应用的截断策略。auto 从对话开头的条目开始删除,disabled(默认值)在超出限制时让请求以 400 错误失败。三个模型都接受此参数,但不会原样返回到响应体中。 |
工具调用
| 参数 | 类型 | 说明 |
|---|---|---|
tools | 数组 | 模型生成响应时可调用的工具数组。支持函数调用、文件搜索、联网搜索等。详见 工具类型说明。 |
tool_choice | 字符串或对象 | 模型选择工具的方式。具体取值参见下表。 |
parallel_tool_calls | 布尔值 | 是否允许模型并行执行工具调用。 |
| 值 / 类型 | 说明 |
|---|---|
"none" | 模型不调用工具,直接生成消息。 |
"auto" | 模型可以生成消息或调用一个或多个工具。 |
{ "type": "function", "name": "..." } | 强制模型调用特定函数。 |
{ "type": "mcp", "server_label": "...", "name": "..." } | 强制模型调用特定 MCP 服务器的工具。 |
输出格式控制
| 格式类型 | 说明 |
|---|---|
{ "type": "text" } | 生成文本响应的默认格式。 |
{ "type": "json_schema", "name": "...", "schema": {...} } | 保证模型输出遵循指定 JSON Schema 的结构化输出。 |
{ "type": "json_object" } | 保证输出为有效 JSON 的旧版 JSON 模式(不建议用于新模型)。 |
| 值 | 说明 |
|---|---|
file_search_call.results | 包含文件搜索工具调用的搜索结果。 |
web_search_call.results | 包含联网搜索工具调用的结果。 |
message.input_image.image_url | 包含输入消息中的图片 URL。 |
code_interpreter_call.outputs | 包含代码解释器执行输出。 |
reasoning.encrypted_content | 包含用于无状态多轮对话的推理令牌加密版本。 |
message.output_text.logprobs | 包含助手消息的对数概率。 |
推理控制
| 字段 | 类型 | 说明 |
|---|---|---|
effort | "none" / "low" / "medium" / "high" | 限制推理强度级别。降低推理强度级别可减少响应时间与推理令牌消耗。 |
summary | "auto" / "concise" / "detailed" | 模型推理过程的摘要,用于调试与理解推理过程。 |
其他参数
| 参数 | 类型 | 说明 |
|---|---|---|
background | 布尔值 | 是否在后台异步执行。所有模型都接受此参数,但实际均为同步返回。 |
store | 布尔值 | 是否保存响应以便后续检索。三个模型都不报错地接受此参数,但实际不会原样返回到响应中。 |
metadata | 对象 | 附加到响应的键值对元数据(最多 16 对,键长 ≤ 64 字符,值长 ≤ 512 字符)。三个模型都接受此参数,但不会原样返回到响应体中。 |
service_tier | 字符串 | 服务层级:auto / default / flex / scale / priority。 |
| 字段 | 类型 | 说明 |
|---|---|---|
content | 字符串或数组 | 文本、图片或音频输入,也可包含此前的助手响应。 |
role | "user" / "assistant" / "system" / "developer" | 消息角色。developer 或 system 的指令优先于 user 的指令。 |
phase | "commentary" / "final_answer" | 可选。将助手消息标记为中间解说或最终答案。 |
type | "message" | 可选。消息输入类型,始终为 message。 |
| 字段 | 类型 | 说明 |
|---|---|---|
detail | "low" / "high" / "auto" / "original" | 图片细节级别,默认值为 auto。 |
type | "input_image" | 类型,始终为 input_image。 |
file_id | 字符串 | 可选。文件 ID。 |
image_url | 字符串 | 可选。图片 URL 或 base64 编码的 data URL。 |
| 字段 | 类型 | 说明 |
|---|---|---|
type | "input_file" | 类型,始终为 input_file。 |
file_data | 字符串 | 可选。文件内容(base64 编码)。 |
file_id | 字符串 | 可选。文件 ID。 |
file_url | 字符串 | 可选。文件 URL。 |
filename | 字符串 | 可选。文件名称。 |
| 字段 | 类型 | 说明 |
|---|---|---|
type | "function" | 类型,始终为 function。 |
name | 字符串 | 函数名称 |
parameters | 对象 | 描述函数参数的 JSON Schema 对象。 |
strict | 布尔值 | 是否强制严格参数校验。默认值为 true。 |
description | 字符串 | 可选。供模型判断调用与否的函数说明。 |
| 字段 | 类型 | 说明 |
|---|---|---|
type | "file_search" | 类型,始终为 file_search。 |
vector_store_ids | 字符串数组 | 要检索的向量存储 ID 列表。 |
max_num_results | 数字 | 可选。返回的最大结果数,范围为 1-50。 |
filters | ComparisonFilter 或 CompoundFilter | 可选。过滤条件。详见 过滤器类型。 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 响应的唯一标识符。 |
object | "response" | 对象类型,始终为 response。 |
created_at | 数字 | 响应生成的 Unix 时间戳(秒)。 |
status | 字符串 | 响应状态:completed / incomplete / failed / in_progress / cancelled。 |
completed_at | 数字 | 响应完成的 Unix 时间戳(秒)。 |
error | 对象 | 请求失败时返回的错误对象。成功完成时不会返回。 |
incomplete_details | 对象 | 响应被截断时的详细信息。reason 字段可能为 "max_output_tokens" 或 "content_filter"。 |
instructions | 字符串 | 原样返回请求中传入的系统消息,不做改动。 |
max_output_tokens | 数字 | 请求中指定的最大输出令牌数。未指定时不返回。 |
model | 字符串 | 用于生成响应的模型 ID。 |
output | 数组 | 模型生成的输出项列表。详见 输出项类型。 |
parallel_tool_calls | 布尔值或 null | 是否允许并行工具调用。 |
previous_response_id | 字符串 | 多轮对话中上一次响应的 ID。单轮对话不返回。 |
usage | 对象 | 令牌消耗统计。详见 ResponseUsage 对象。 |
service_tier | 字符串 | 实际使用的服务层级。 |
| 字段 | 类型 | 说明 |
|---|---|---|
input_tokens | 数字 | 输入令牌数。 |
input_tokens_details | 对象 | 含 cached_tokens 的输入令牌详细信息 |
output_tokens | 数字 | 输出令牌数。 |
output_tokens_details | 对象 | 含 reasoning_tokens 的输出令牌详细信息 |
total_tokens | 数字 | 总令牌数(输入 + 输出)。 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 输出消息的唯一 ID。 |
type | "message" | 类型,始终为 message。 |
role | "assistant" | 角色,始终为 assistant。 |
status | "in_progress" / "completed" / "incomplete" | 消息状态。 |
content | 数组 | 消息内容数组。各项包含 type: "output_text" 与 text 字段。 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 唯一 ID。 |
type | "function_call" | 类型,始终为 function_call。 |
call_id | 字符串 | 函数调用 ID,提交 function_call_output 时必须传递。 |
name | 字符串 | 被调函数的名称。 |
arguments | 字符串 | 函数参数的 JSON 字符串。 |
status | 字符串 | in_progress / completed / incomplete。 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 唯一 ID。 |
type | "reasoning" | 类型,始终为 reasoning。 |
summary | 数组 | 推理摘要文本列表。各项包含 type: "summary_text" 与 text 字段。 |
status | 字符串 | 状态。 |
示例:推理模型
| 字段 | 类型 | 说明 |
|---|---|---|
key | 字符串 | 要比较的属性键 |
type | "eq" / "ne" / "gt" / "gte" / "lt" / "lte" / "in" / "nin" | 比较运算符 |
value | 字符串 / 数字 / 布尔值 / 数组 | 要比较的值 |
| 字段 | 类型 | 说明 |
|---|---|---|
type | "and" / "or" | 运算类型 |
filters | 数组 | 要组合的过滤器数组(ComparisonFilter 或 CompoundFilter) |
Messages 详细字段
协议的字段结构。各模型支持的功能与允许值遵循该模型的各版本规范。
基本参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 要使用的模型名称。例:deepseek-v4-flash。 |
messages | array | 必填 | 按时间顺序排列、包含完整上下文的对话消息列表。平台不管理会话。多轮对话中客户端需传递完整历史。详见 消息对象详细信息。 |
system | string 或 array | 可选 | 系统提示词。不包含在 messages 中,通过顶层 system 字段单独传递。这是与 OpenAI Chat 协议的主要差异。 |
max_tokens | integer | 必填 | 单次模型输出中可生成的最大令牌数。各模型有自身限制。推理链中消耗的令牌也计入此限制。因此启用 thinking 时,该值须大于 budget_tokens。达到限制时 stop_reason 为 "max_tokens"。 |
stream | boolean | 可选 | 是否启用流式响应(默认值:false)。为 true 时,响应以 SSE 格式按事件逐个返回。 |
生成控制参数
| 参数 | 类型 | 范围 | 说明 |
|---|---|---|---|
temperature | float | [0, 1] | 采样温度。Messages 协议的范围是 [0, 1],与 OpenAI 的 [0, 2] 不同。 |
top_p | float | (0, 1] | 核采样。通常只调整 temperature 与 top_p 中的一个。 |
top_k | integer | - | 仅从概率最高的前 K 个令牌中采样。Messages 协议专有参数,OpenAI Chat 协议中没有。 |
stop_sequences | string[] | - | 自定义停止序列。任意序列匹配即立即停止,并将 stop_reason 设为 "stop_sequence"。匹配到的序列会再次记录到响应的 stop_sequence 字段中。 |
工具调用
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
name | string | 必填 | 工具名称。 |
description | string | 可选 | 说明工具用途,帮助模型判断调用时机。 |
input_schema | object | 必填 | 遵循 JSON Schema 格式的参数定义。 |
type | string | 可选 | 普通工具请留空。内置工具请输入类型名称(例:web_search_20250305)。 |
max_uses | integer | 可选 | 内置工具每会话的最大调用次数。 |
cache_control | object | 可选 | 工具定义级别的缓存标记。 |
| Messages tool_choice | 等价的 OpenAI 值 | 说明 |
|---|---|---|
{"type":"auto"} | "auto" | 默认值,由模型自行决定。 |
{"type":"any"} | "required" | 让模型必须调用可用工具中的一个。 |
{"type":"none"} | "none" | 禁用工具调用。 |
{"type":"tool","name":"x"} | {"type":"function","function":{"name":"x"}} | 让模型必须调用指定工具。 |
思维链(扩展 thinking)
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
type | string | 必填 | 启用为 "enabled" / 禁用为 "disabled" / 自适应模式为 "adaptive"。 |
budget_tokens | integer | 条件必填 | enabled 时建议使用。思维链令牌预算(建议范围:1024~32000)。该值须小于 max_tokens。 |
display | string | 可选 | 推理过程展示方式(部分模型支持)。 |
输出构成
| 字段 | 类型 | 说明 |
|---|---|---|
effort | string | 输出工作量级别:low / medium / high / xhigh / max。 |
format.type | string | 结构化输出类型(例:json_schema)。 |
format.schema | object | JSON Schema 定义。 |
缓存(提示词缓存)
| 级别 | 标记位置 | 说明 |
|---|---|---|
| 工具级别 | tools[n].cache_control | 工具定义缓存 |
| 系统级别 | system[n].cache_control | 系统内容块缓存 |
| 消息 / 内容块级别 | messages[n].content[m].cache_control | 历史消息或内容块缓存 |
元数据与服务层级
| 值 | 说明 |
|---|---|
auto | 自动选择 |
standard | 标准层级 |
priority | 优先层级(更高保障) |
batch | 批处理层级 |
请求头
| 请求头 | 是否必填 | 说明 |
|---|---|---|
x-api-key | 必填 | API 密钥(Messages 协议规则),平台同时支持 Authorization: Bearer <key>。 |
anthropic-version | 必填 | API 版本,固定为 2023-06-01。 |
content-type | 必填 | application/json |
anthropic-beta | 可选 | beta 功能开关(例:prompt-caching 与 interleaved-thinking),平台不做改动,透明传递给模型服务。 |
| role | 说明 | 使用位置 |
|---|---|---|
user | 人类用户的输入(含 tool_result) | 奇数轮对话。 |
assistant | 模型此前的响应(可含 text / thinking / tool_use) | 用于偶数轮对话。多轮对话中需传递历史上下文。 |
| 块类型 | 主要字段 | 适用的 role | 说明 |
|---|---|---|---|
text | text、cache_control | user / assistant | 文本内容 |
image | source | user | 图片 |
video | source | user | 视频 |
document | source、title、context、citations、cache_control | user | 文档输入与引用 |
search_result | source、title、content、citations | user | 搜索结果内容块 |
tool_use | id、name、input | assistant | 请求工具调用的模型请求 |
tool_result | tool_use_id、content | user | 工具执行结果 |
thinking | thinking、signature | assistant | 推理链内容 |
redacted_thinking | data | assistant | 编辑后的推理链 |
source 字段 | 类型 | 说明 |
|---|---|---|
type | string | "base64" 或 "url"。 |
media_type | string | 选择 base64 时必填。例:image/jpeg、image/png、image/gif 或 image/webp。 |
data | string | 选择 base64 时为图片数据。 |
url | string | 选择 url 时为图片地址。 |
detail | string | 指定图片分析细粒度的 low / high / auto。 |
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 工具调用的唯一 ID,需返回到相应的 tool_result 中。 |
name | string | 要调用的工具名称。 |
input | object | 工具参数(是对象而非 JSON 字符串,与 OpenAI 的 arguments 字符串不同)。 |
| 字段 | 类型 | 说明 |
|---|---|---|
tool_use_id | string | 对应 tool_use.id。 |
content | string 或 array | 工具结果,可以是普通文本或内容块数组(支持 text+image)。 |
is_error | boolean | 工具执行失败时设为 true。 |
cache_control | object | 缓存标记。 |
| 字段 | 类型 | 说明 |
|---|---|---|
thinking | string | 模型推理过程的文本 |
signature | string | 推理块的完整性签名 |
非流式响应
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 响应的唯一标识符(前缀 msg_)。 |
type | string | 固定为 "message"。 |
role | string | 固定为 "assistant"。 |
model | string | 实际使用的模型名称。 |
content | array | 内容块数组,通常顺序为 thinking → text → tool_use。 |
stop_reason | string | 停止原因。参见下方枚举。 |
stop_sequence | string 或 null | 匹配到的停止序列(stop_sequences 匹配时)。 |
usage | object | 令牌用量。参见 令牌用量。 |
container | object | 代码执行容器信息(id、expires_at)。仅在使用内置 code_execution 工具时返回。 |
service_tier | string | 实际匹配的服务层级。 |
流式响应(SSE)
| 事件 | 说明 | 主要字段 |
|---|---|---|
message_start | 表示消息开始,返回初始消息骨架。 | message(含初始 usage 及 input/cache) |
content_block_start | 内容块开始 | index 与 content_block(类型为 text/thinking/tool_use) |
content_block_delta | 内容增量 | index 与 delta(参见下表) |
content_block_stop | 内容块结束 | index |
message_delta | 消息级增量 | delta.stop_reason 与 usage(最终 output_tokens) |
message_stop | 消息结束 | - |
| delta.type | 字段 | 含义 |
|---|---|---|
text_delta | text | 文本增量。 |
thinking_delta | thinking | 推理过程增量。 |
signature_delta | signature | 推理块的完整性签名(在 thinking 块结束前传递)。 |
input_json_delta | partial_json | 工具参数 JSON 片段,累积后需整体解析。 |
stop_reason 枚举
| 值 | 说明 | 推荐处理方式 |
|---|---|---|
end_turn | 模型正常结束。 | 正常处理即可。 |
max_tokens | 达到 max_tokens 限制导致输出被截断。 | 请增大 max_tokens 的值或拆分内容生成。 |
stop_sequence | stop_sequences 已匹配。 | 请确认匹配到的 stop_sequence 字段。 |
tool_use | 模型请求调用工具。 | 执行工具并通过 tool_result 返回结果以继续对话。 |
pause_turn | 服务器工具的长时间轮次暂停 | 原样返回当前内容不做改动,并继续请求以恢复。 |
refusal | 模型因安全原因拒绝响应。 | 请确认输入是否触发安全策略。 |
令牌用量
| 字段 | 类型 | 说明 |
|---|---|---|
input_tokens | integer | 净输入令牌(不含缓存读 / 写操作) |
output_tokens | integer | 输出令牌(含 thinking 内容) |
cache_creation_input_tokens | integer | 写入缓存的令牌数 |
cache_read_input_tokens | integer | 缓存命中读取的令牌数(计费大幅降低) |
cache_creation.ephemeral_5m_input_tokens | integer | 5 分钟 TTL 缓存创建令牌(按 TTL 分列明细) |
cache_creation.ephemeral_1h_input_tokens | integer | 1 小时 TTL 缓存创建令牌(按 TTL 分列明细) |
server_tool_use.web_search_requests | integer | 内置 web_search 调用次数 |
server_tool_use.web_fetch_requests | integer | 内置 web_fetch 调用次数 |
service_tier | string | 实际匹配的服务层级 |
示例:提示词缓存
响应与执行流程
流式
Chat Completions
指定 stream=true 并按顺序拼接 choices.delta.content。使用 stream_options.include_usage=true 时也会处理最后的用量事件。
data: {"choices":[{"index":0,"delta":{"content":"你好"}}]}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}
data: [DONE]Responses
从 response.output_text.delta 中读取文本,并在 response.completed 中确认最终状态与用量。同时处理错误与中断事件。
Messages
按 message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop 的顺序构成消息。工具输入按独立于文本响应的块处理。
SSE 事件边界与网络数据包边界并不一致。请将收到的数据按行累积,并以空行作为事件分隔符。
工具调用
| 协议 | 工具声明 | 模型的调用 | 结果传递 |
|---|---|---|---|
| Chat Completions | tools.function.parameters | message.tool_calls | role=tool / tool_call_id |
| Responses | tools.parameters | type=function_call | type=function_call_output / call_id |
| Messages | tools.input_schema | type=tool_use | type=tool_result / tool_use_id |
即使声明了工具,API 也不会执行用户函数。应用程序需确认函数名称与参数后执行,并将结果传递到下一次请求。在需要模型返回的签名或推理块的后续调用中,请保留相应字段。
错误与调用限制
调用限制与错误处理
默认调用范围为 30 RPM / 300K TPM。请根据账号适用的配额调整并发请求数与重试间隔。
| 情况 | 处理 |
|---|---|
| 认证失败 | 确认密钥的有效状态及关联的应用程序 |
| 模型 / 参数错误 | 确认模型 ID、协议及各版本的允许值 |
| 超出调用频率 / 令牌上限 | 减少请求并间隔重试 |
| 服务器错误 / 超时 | 记录请求 ID,并确认是否完成及是否存在重复执行可能 |
配额管理 API 通过 TC3 签名调用。Text 配额以 ApiToken 为准。若要重新开始累计配额,请删除现有配额后重新创建。
请求示例
请使用要调用的模型或协议的请求示例。请勿将不同路径的认证方式与请求字段混合在同一个请求中。请同时查看下方引擎文档与各协议的参数。
结果与资源管理
用量与缓存
| 协议 | 输入 / 输出令牌 | 缓存读取 |
|---|---|---|
| Chat Completions | prompt_tokens / completion_tokens | prompt_tokens_details.cached_tokens |
| Responses | input_tokens / output_tokens | input_tokens_details.cached_tokens |
| Messages | input_tokens / output_tokens | cache_read_input_tokens |
Messages 的缓存创建量在 cache_creation_input_tokens 中确认。各协议的用量字段含义不同,请勿混用同一个计算式。
统计与日志
| API | 用途 | 限制 |
|---|---|---|
DescribeAigcUsageData | 各模型的输入 / 输出 / 缓存输入用量 | 最近 365 天 中一次最多 90 天 |
GET /v1/statistics | 请求数、状态码、令牌、缓存、TTFT | 每秒 2 次 |
GET /v1/request-logs | 各请求的模型、令牌、延迟、结果码 | 每秒 2 次 / scroll_token 分页 |
statistics 使用 granularity=1m、5m、1h。1 分钟 / 5 分钟 数据保存 31 天,1 小时 数据保存 90 天。查询的 app_id 必须与 API 密钥的所属应用程序一致。