跳到内容

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 签名。

json
{
  "SubAppId": 123456789
}

使用 TC3 调用脚本时:

bash
python3 tencent-api.py vod CreateAigcApiToken create-token.json

将响应中的 ApiToken 用作后续模型请求的 Bearer 密钥。请勿将应用程序 ID 或 SecretKey 作为 Bearer 密钥传递。

3. 用签发的密钥调用模型 ​

bash
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认证
签发CreateAigcApiTokenTC3 签名
列表查询DescribeAigcApiTokensTC3 签名
删除DeleteAigcApiTokenTC3 签名
配额查询DescribeAigcQuotasTC3 签名
配额生成 / 变更 / 删除CreateAigcQuota / ModifyAigcQuota / DeleteAigcQuotaTC3 签名

密钥长期有效,最多可签发 50 个。生成与删除后反映到列表可能需要约 30 秒。需为子账号授予相应 VOD action 的 CAM 权限。

协议选择 ​

协议请求路径输入的中心字段结果的中心字段
Chat CompletionsPOST /v1/chat/completionsmessageschoices.message
ResponsesPOST /v1/responsesinputoutput
MessagesPOST /v1/messagesmessages / systemcontent

即使是同一模型可以用多种协议调用,但请求字段与响应结构不同。请在各模型文档的支持协议中选择要使用的路径,再按该规范构造请求。

认证与会话头 ​

头必填值 / 用途
Authorization必填Bearer ${VOD_API_TOKEN}
Content-Type必填application/json
x-api-key可选Messages 联动中可用的 API 密钥头
X-Request-Id可选请求追踪 ID
Tx-User-Session-Id可选串联同一对话请求的会话 ID

查询可调用模型 ​

bash
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可选IntegerSDK 兼容用生成令牌上限。请勿与 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 配额各自单独适用。

消息结构 ​

字段类型说明
roleStringsystem / developer / user / assistant / tool
contentString / Array文本或媒体 Part 数组
tool_callsArray模型请求的函数名与参数
tool_call_idString连接工具结果与原始调用的 ID

响应示例 ​

json
{
  "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可选Objecteffort 等支持模型的推理设置
text可选Object输出格式与支持模型的文本设置
tools可选Array函数名、说明、参数 Schema
tool_choice可选String / Object工具选择方式
stream可选Boolean是否 SSE 流式

请求示例 ​

json
{
  "model": "gpt-5.6-sol",
  "instructions": "请用中文简洁回答。",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "请说明哪些情况需要让缓存失效。"
        }
      ]
    }
  ],
  "reasoning": {
    "effort": "low"
  },
  "max_output_tokens": 2048,
  "stream": false
}

响应示例 ​

json
{
  "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必填Arrayuser / assistant 对话历史
max_tokens必填Integer最大生成令牌
system可选String / Array与对话历史分离的响应指令
stream可选Boolean是否 SSE 流式
temperature可选Number支持模型的采样温度
top_p / top_k可选Number / Integer支持模型的采样设置
thinking可选Object支持模型的推理方式与预算
output_config可选Object支持模型的推理强度等输出设置
tools可选Arrayname、description、input_schema
tool_choice可选Objectauto、any、tool 等工具选择方式
stop_sequences可选Array停止生成的字符串列表

请求示例 ​

json
{
  "model": "deepseek-v4.1-flash",
  "system": "请用中文回答。",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请说明请求超时与重试策略。"
        }
      ]
    }
  ],
  "max_tokens": 2048,
  "stream": false
}

响应示例 ​

json
{
  "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
Responsesreasoning.effort"reasoning": {"effort": "high"}
Messages各模型的 thinking / output_config参见各模型文档中的设置

推理设置的名称与允许值随协议与模型版本而不同。请勿将 thinking_enabled 通用地放入所有模型。返回的推理令牌计入生成令牌用量。

Media Input ​

Chat Completions 的 Part ​

type输入字段内容
texttext问题与指令
image_urlimage_url.url图片 URL 或 data URL
video_urlvideo_url.url视频 URL
input_audioinput_audio音频 URL 或 data / format
filefile.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。
filtersComparisonFilter 或 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 详细字段 ​

协议的字段结构。各模型支持的功能与允许值遵循该模型的各版本规范。

基本参数 ​

参数类型必填说明
modelstring必填要使用的模型名称。例:deepseek-v4-flash。
messagesarray必填按时间顺序排列、包含完整上下文的对话消息列表。平台不管理会话。多轮对话中客户端需传递完整历史。详见 消息对象详细信息。
systemstring 或 array可选系统提示词。不包含在 messages 中,通过顶层 system 字段单独传递。这是与 OpenAI Chat 协议的主要差异。
max_tokensinteger必填单次模型输出中可生成的最大令牌数。各模型有自身限制。推理链中消耗的令牌也计入此限制。因此启用 thinking 时,该值须大于 budget_tokens。达到限制时 stop_reason 为 "max_tokens"。
streamboolean可选是否启用流式响应(默认值:false)。为 true 时,响应以 SSE 格式按事件逐个返回。

生成控制参数 ​

参数类型范围说明
temperaturefloat[0, 1]采样温度。Messages 协议的范围是 [0, 1],与 OpenAI 的 [0, 2] 不同。
top_pfloat(0, 1]核采样。通常只调整 temperature 与 top_p 中的一个。
top_kinteger-仅从概率最高的前 K 个令牌中采样。Messages 协议专有参数,OpenAI Chat 协议中没有。
stop_sequencesstring[]-自定义停止序列。任意序列匹配即立即停止,并将 stop_reason 设为 "stop_sequence"。匹配到的序列会再次记录到响应的 stop_sequence 字段中。

工具调用 ​

字段类型是否必填说明
namestring必填工具名称。
descriptionstring可选说明工具用途,帮助模型判断调用时机。
input_schemaobject必填遵循 JSON Schema 格式的参数定义。
typestring可选普通工具请留空。内置工具请输入类型名称(例:web_search_20250305)。
max_usesinteger可选内置工具每会话的最大调用次数。
cache_controlobject可选工具定义级别的缓存标记。
Messages tool_choice等价的 OpenAI 值说明
{"type":"auto"}"auto"默认值,由模型自行决定。
{"type":"any"}"required"让模型必须调用可用工具中的一个。
{"type":"none"}"none"禁用工具调用。
{"type":"tool","name":"x"}{"type":"function","function":{"name":"x"}}让模型必须调用指定工具。

思维链(扩展 thinking) ​

字段类型是否必填说明
typestring必填启用为 "enabled" / 禁用为 "disabled" / 自适应模式为 "adaptive"。
budget_tokensinteger条件必填enabled 时建议使用。思维链令牌预算(建议范围:1024~32000)。该值须小于 max_tokens。
displaystring可选推理过程展示方式(部分模型支持)。

输出构成 ​

字段类型说明
effortstring输出工作量级别:low / medium / high / xhigh / max。
format.typestring结构化输出类型(例:json_schema)。
format.schemaobjectJSON 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说明
texttext、cache_controluser / assistant文本内容
imagesourceuser图片
videosourceuser视频
documentsource、title、context、citations、cache_controluser文档输入与引用
search_resultsource、title、content、citationsuser搜索结果内容块
tool_useid、name、inputassistant请求工具调用的模型请求
tool_resulttool_use_id、contentuser工具执行结果
thinkingthinking、signatureassistant推理链内容
redacted_thinkingdataassistant编辑后的推理链
source 字段类型说明
typestring"base64" 或 "url"。
media_typestring选择 base64 时必填。例:image/jpeg、image/png、image/gif 或 image/webp。
datastring选择 base64 时为图片数据。
urlstring选择 url 时为图片地址。
detailstring指定图片分析细粒度的 low / high / auto。
字段类型说明
idstring工具调用的唯一 ID,需返回到相应的 tool_result 中。
namestring要调用的工具名称。
inputobject工具参数(是对象而非 JSON 字符串,与 OpenAI 的 arguments 字符串不同)。
字段类型说明
tool_use_idstring对应 tool_use.id。
contentstring 或 array工具结果,可以是普通文本或内容块数组(支持 text+image)。
is_errorboolean工具执行失败时设为 true。
cache_controlobject缓存标记。
字段类型说明
thinkingstring模型推理过程的文本
signaturestring推理块的完整性签名

非流式响应 ​

字段类型说明
idstring响应的唯一标识符(前缀 msg_)。
typestring固定为 "message"。
rolestring固定为 "assistant"。
modelstring实际使用的模型名称。
contentarray内容块数组,通常顺序为 thinking → text → tool_use。
stop_reasonstring停止原因。参见下方枚举。
stop_sequencestring 或 null匹配到的停止序列(stop_sequences 匹配时)。
usageobject令牌用量。参见 令牌用量。
containerobject代码执行容器信息(id、expires_at)。仅在使用内置 code_execution 工具时返回。
service_tierstring实际匹配的服务层级。

流式响应(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_deltatext文本增量。
thinking_deltathinking推理过程增量。
signature_deltasignature推理块的完整性签名(在 thinking 块结束前传递)。
input_json_deltapartial_json工具参数 JSON 片段,累积后需整体解析。

stop_reason 枚举 ​

值说明推荐处理方式
end_turn模型正常结束。正常处理即可。
max_tokens达到 max_tokens 限制导致输出被截断。请增大 max_tokens 的值或拆分内容生成。
stop_sequencestop_sequences 已匹配。请确认匹配到的 stop_sequence 字段。
tool_use模型请求调用工具。执行工具并通过 tool_result 返回结果以继续对话。
pause_turn服务器工具的长时间轮次暂停原样返回当前内容不做改动,并继续请求以恢复。
refusal模型因安全原因拒绝响应。请确认输入是否触发安全策略。

令牌用量 ​

字段类型说明
input_tokensinteger净输入令牌(不含缓存读 / 写操作)
output_tokensinteger输出令牌(含 thinking 内容)
cache_creation_input_tokensinteger写入缓存的令牌数
cache_read_input_tokensinteger缓存命中读取的令牌数(计费大幅降低)
cache_creation.ephemeral_5m_input_tokensinteger5 分钟 TTL 缓存创建令牌(按 TTL 分列明细)
cache_creation.ephemeral_1h_input_tokensinteger1 小时 TTL 缓存创建令牌(按 TTL 分列明细)
server_tool_use.web_search_requestsinteger内置 web_search 调用次数
server_tool_use.web_fetch_requestsinteger内置 web_fetch 调用次数
service_tierstring实际匹配的服务层级

示例:提示词缓存 ​

响应与执行流程 ​

流式 ​

Chat Completions ​

指定 stream=true 并按顺序拼接 choices.delta.content。使用 stream_options.include_usage=true 时也会处理最后的用量事件。

text
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 Completionstools.function.parametersmessage.tool_callsrole=tool / tool_call_id
Responsestools.parameterstype=function_calltype=function_call_output / call_id
Messagestools.input_schematype=tool_usetype=tool_result / tool_use_id

即使声明了工具,API 也不会执行用户函数。应用程序需确认函数名称与参数后执行,并将结果传递到下一次请求。在需要模型返回的签名或推理块的后续调用中,请保留相应字段。

错误与调用限制 ​

调用限制与错误处理 ​

默认调用范围为 30 RPM / 300K TPM。请根据账号适用的配额调整并发请求数与重试间隔。

情况处理
认证失败确认密钥的有效状态及关联的应用程序
模型 / 参数错误确认模型 ID、协议及各版本的允许值
超出调用频率 / 令牌上限减少请求并间隔重试
服务器错误 / 超时记录请求 ID,并确认是否完成及是否存在重复执行可能

配额管理 API 通过 TC3 签名调用。Text 配额以 ApiToken 为准。若要重新开始累计配额,请删除现有配额后重新创建。

请求示例 ​

请使用要调用的模型或协议的请求示例。请勿将不同路径的认证方式与请求字段混合在同一个请求中。请同时查看下方引擎文档与各协议的参数。

结果与资源管理 ​

用量与缓存 ​

协议输入 / 输出令牌缓存读取
Chat Completionsprompt_tokens / completion_tokensprompt_tokens_details.cached_tokens
Responsesinput_tokens / output_tokensinput_tokens_details.cached_tokens
Messagesinput_tokens / output_tokenscache_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 密钥的所属应用程序一致。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages