Doubao
更新时间: 2026/09/03 18:12:48
本文介绍网易云信大模型 API(以下简称 AIHub) 与 Volcengine/豆包 兼容的对话生成接口的使用说明。
云信 AIHub 通过 Volcengine/豆包 provider 提供 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 的同协议原生能力。您只需使用网易云信的 logical model,并改用云信下发的 API Key 即可无缝接入。
请求说明
| 协议 | 路径 | 示例 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions |
POST https://ai.yunxinapi.com/hub/v1/chat/completions |
| Anthropic Messages | POST /v1/messages |
POST https://ai.yunxinapi.com/hub/v1/messages |
| Responses | POST /v1/responses |
POST https://ai.yunxinapi.com/hub/v1/responses |
请求参数
Header 参数
| 参数 | 协议/位置 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
Authorization |
OpenAI/Responses/Anthropic 可选 Header | 必填或可选 | AIHub API Key Bearer 鉴权;统一 HTTP 客户端推荐使用。 | Bearer <AIHUB_API_KEY> |
x-api-key |
Anthropic Messages Header | Anthropic SDK 常用 | AIHub API Key,Anthropic SDK 形态。 | <AIHUB_API_KEY> |
Content-Type |
Header | 必填 | 请求体类型。 | application/json |
Body 参数
豆包的标准参数按本页对应协议构造。豆包私有扩展字段应按对应模型的原厂约束传递;AIHub 不把这些字段作为跨协议转换承诺,需要字段生效时应优先使用同协议原生入口。
OpenAI Chat Completions 参数
适用入口:POST https://ai.yunxinapi.com/hub/v1/chat/completions。以下参数表格直接合并 OpenAI-compatible Chat 参数。
| 参数 | 类型/位置 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
model |
string,body 顶层 | 必填 | AIHub logical model。AIHub 会按 API Key、模型授权、operation 和路由配置解析为上游模型;可见模型不等于支持所有字段。 | "doubao-seed-1-6" |
messages |
array,body 顶层 | 必填 | 按时间顺序排列的对话历史。普通对话至少包含一条 user 消息;工具调用场景必须保留 assistant tool_calls 和后续 tool 结果。 |
[{"role":"user","content":"你好"}] |
messages[].role |
string | 必填 | 消息角色。常见为 developer、system、user、assistant、tool;具体角色支持取决于目标模型。 |
"user" |
messages[].content |
string、content part[] 或 null | 通常必填 | 消息正文。文本可直接传 string;多模态、文件、音频等输入使用 content part 数组;assistant 只有工具调用时可为空。 | "总结这段文本" |
messages[].name |
string | 可选 | 发言者名称,只作为提示上下文,不是鉴权身份,也不能替代 role。部分上游会忽略。 |
"product_manager" |
messages[].tool_calls |
array | 条件必填 | assistant 发起的工具调用历史。续接工具闭环时必须原样保存 id、函数名和参数。 |
[{"id":"call_1","type":"function","function":{"name":"search","arguments":"{}"}}] |
messages[].tool_call_id |
string | 条件必填 | role: "tool" 消息关联的工具调用 ID,必须匹配前一轮 assistant tool_calls[].id。 |
"call_1" |
messages[].reasoning_content |
string | 厂商条件字段 | Qwen、Kimi、DeepSeek、GLM 等推理模型的历史推理字段。只有目标厂商要求保留时才原样回传,不要拼入 content。 |
"上一轮推理内容" |
messages[].partial |
boolean | 厂商条件字段 | Kimi Partial Mode 预填标识,通常只放在最后一条 assistant 消息。不是 OpenAI 标准字段。 | true |
messages[].content[].type |
string | content part 必填 | content part 类型,例如 text、image_url、input_audio、file。必须与同一对象里的字段匹配。 |
"text" |
messages[].content[].text |
string | 文本 part 必填 | 文本内容,承载用户可见自然语言、代码或结构化文本;不要混入历史推理字段。 | "识别图片里的文字" |
messages[].content[].image_url |
object | 图片 part 必填 | 图像输入配置,通常包含 url 和可选 detail;URL、data URL、格式和大小由目标模型决定。 |
{"url":"https://example.com/a.png","detail":"high"} |
messages[].content[].input_audio |
object | 音频 part 必填 | 音频输入配置,通常包含 base64 data 和 format;仅向支持音频输入的模型发送。 |
{"data":"BASE64","format":"wav"} |
messages[].content[].file |
object | 文件 part 必填 | 文件输入,可传上游文件 ID、内联文件数据或文件名。AIHub 不转换跨厂商文件 ID。 | {"file_id":"file_abc"} |
temperature |
number,body 顶层 | 可选 | 采样随机度。值越低越稳定,值越高越发散;通常不要和 top_p 同时大幅调节。 |
0.2 |
top_p |
number,body 顶层 | 可选 | nucleus sampling 阈值,从累计概率覆盖该阈值的候选 token 中采样。 | 0.9 |
max_completion_tokens |
integer,body 顶层 | 可选 | 最大 completion token 数。推理模型通常同时消耗可见输出和推理 token;新请求优先使用该字段。 | 1024 |
max_tokens |
integer,body 顶层 | 可选,旧字段 | 旧式输出 token 上限。部分新模型要求使用 max_completion_tokens,不要让两个字段表达冲突上限。 |
1024 |
stop |
string 或 string[] | 可选 | 停止序列。模型生成到匹配文本时停止,通常不会输出停止序列本身。 | ["END"] |
n |
integer | 可选 | 候选回复数量。每个候选都会计费;工具调用和多数跨协议场景建议保持 1。 |
1 |
seed |
integer | 可选 | 随机种子,用于尽量提高可复现性,不保证绝对确定。 | 1234 |
presence_penalty |
number | 可选 | 鼓励引入新概念或主题,适合降低重复话题,不替代格式校验。 | 0.1 |
frequency_penalty |
number | 可选 | 降低高频 token 重复,过高可能伤害术语、代码和固定格式。 | 0.2 |
logit_bias |
object | 可选 | 按 token ID 调整采样概率。tokenizer 强相关,不保证跨模型复用,也不做跨协议转换。 | {"50256":-100} |
logprobs |
boolean | 可选 | 是否返回输出 token 对数概率。会增大响应体,且并非所有模型支持。 | true |
top_logprobs |
integer | 条件可选 | 仅 logprobs: true 时有效,返回每个位置的候选 token 概率数量。 |
5 |
response_format |
object | 可选 | 结构化输出控制,可请求文本、JSON object 或 JSON Schema;服务端仍需解析和校验。 | {"type":"json_object"} |
response_format.type |
string | 可选 | 常见值为 text、json_object、json_schema;可用值以模型和厂商为准。 |
"json_schema" |
response_format.json_schema |
object | json_schema 条件必填 |
JSON Schema 输出定义,通常包含 name、description、schema 和可选 strict。 |
{"name":"todo","schema":{"type":"object"},"strict":true} |
tools |
array | 可选 | 可供模型调用的工具定义。AIHub 稳定公共子集是 OpenAI 风格 function 工具。 |
[{"type":"function","function":{"name":"lookup","parameters":{"type":"object"}}}] |
tools[].type |
string | 工具项必填 | 工具类型。公共 function calling 使用 function;其他厂商工具只在同协议原生入口使用。 |
"function" |
tools[].function.name |
string | function 必填 | 函数名,应与业务工具注册表一致,并在工具闭环中保持稳定。 | "get_weather" |
tools[].function.description |
string | 建议填写 | 说明何时调用、参数含义和副作用。描述越清楚,模型越不容易误调。 | "查询城市天气" |
tools[].function.parameters |
JSON Schema object | 建议填写 | 函数参数 schema。模型输出仍不可信,服务端必须校验、鉴权和限流。 | {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]} |
tools[].function.strict |
boolean | 可选 | 请求严格按 schema 输出工具参数。开启后 schema 必须满足目标模型支持的子集。 | true |
tool_choice |
string 或 object | 可选 | 控制模型是否、以及如何选择工具。常见为 none、auto、required 或指定 function。 |
{"type":"function","function":{"name":"get_weather"}} |
parallel_tool_calls |
boolean | 可选 | 是否允许并行工具调用。设置为 false 可降低编排复杂度,但不替代服务端幂等控制。 |
false |
stream |
boolean | 可选 | true 时返回 SSE 增量事件;流式只改变传输模式,不改变采样和工具语义。 |
true |
stream_options.include_usage |
boolean | 条件可选 | 流式最后请求附带 usage 汇总;中途断流时最终 usage 可能收不到。 | {"include_usage":true} |
modalities |
string[] | 可选 | 请求输出模态,例如文本或音频。启用音频时还需提供 audio,且模型必须支持。 |
["text"] |
audio |
object | 条件必填 | 音频输出配置。只有输出模态包含音频时使用,字段由模型支持矩阵决定。 | {"format":"wav","voice":"alloy"} |
audio.format |
string | 条件必填 | 请求的音频编码或封装格式。 | "wav" |
audio.voice |
string | 条件必填 | 音色或语音名称,受模型和账号授权限制。 | "alloy" |
prediction |
object | 可选 | 预测型输出优化候选内容,适合大部分输出可提前预知的编辑场景。 | {"type":"content","content":"固定前缀"} |
reasoning_effort |
string | 可选 | 推理强度提示。枚举、计费和是否生效由厂商与模型决定。 | "high" |
service_tier |
string | 可选 | 上游服务档位或延迟优先级。是否可用由账号、渠道和模型决定。 | "standard" |
prompt_cache_key |
string | 可选 | 提示缓存分组键或会话亲和提示。不要放密钥或敏感正文。 | "session_42" |
safety_identifier |
string | 可选 | 匿名稳定用户标识,用于安全追踪和滥用识别,避免传 PII。 | "user_hash_abc123" |
store |
boolean | 可选 | 请求上游存储响应或用于其平台功能。AIHub 不以此替代自身审计和日志策略。 | false |
metadata |
object | 可选 | 业务元数据,应短小且非敏感。metadata.aihub_* 为 AIHub 保留并会被剥离。 |
{"trace_id":"req_123"} |
user |
string | 可选,旧兼容字段 | 终端用户匿名标识,供部分上游做安全监测。新接入优先用厂商推荐字段。 | "user_123" |
functions |
array | 可选,已弃用 | 旧版 function calling 定义。新请求应使用 tools。 |
[{"name":"lookup","parameters":{"type":"object"}}] |
function_call |
string 或 object | 可选,已弃用 | 旧版函数选择控制。新请求应使用 tool_choice。 |
"auto" |
web_search_options |
object | 可选,兼容字段 | 个别 OpenAI-compatible 上游的旧式联网搜索配置,不是跨厂商统一能力。 | {"search_context_size":"medium"} |
Anthropic Messages 参数
适用入口:POST https://ai.yunxinapi.com/hub/v1/messages。使用 Anthropic SDK 时保留 x-api-key Header 形态。
| 参数 | 类型/位置 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
model |
string,body 顶层 | 必填 | AIHub logical model。必须对当前 API Key 可见,并在 Messages operation 上有可用路由。 | "doubao-seed-1-6" |
max_tokens |
integer,body 顶层 | 必填 | 本次最多生成的输出 token。thinking、工具输入和多模态输出可能影响实际 token 使用。 | 1024 |
messages |
array,body 顶层 | 必填 | 用户与 assistant 的对话消息。系统指令不放在数组内,使用 system。 |
[{"role":"user","content":"你好"}] |
messages[].role |
string | 必填 | 常用 user 或 assistant。跨协议转换时 system/developer 重排风险较高,应优先同协议调用。 |
"user" |
messages[].content |
string 或 content block[] | 必填 | 消息正文。简单文本用 string;图像、文档、工具、thinking 或缓存标记使用 block 数组。 | [{"type":"text","text":"解释一下"}] |
system |
string 或 content block[] | 可选 | 系统提示词,独立于 messages。使用缓存时通常把 cache_control 放在 system text block 上。 |
"以简洁中文回答" |
content[].type |
string | block 必填 | 内容块类型,如 text、image、document、thinking、tool_use、tool_result。 |
"text" |
content[].text |
string | text block 必填 | 文本内容。可附带 citations 或 cache_control,具体由厂商支持度决定。 |
"请总结" |
content[].image.source |
object | image block 必填 | 图像来源,可为 base64、URL 或上游文件资源,具体字段取决于厂商。 | {"type":"base64","media_type":"image/png","data":"BASE64"} |
content[].document.source |
object | document block 必填 | 文档来源。AIHub 不转换任一厂商文件资源 ID 或文档引用。 | {"type":"base64","media_type":"application/pdf","data":"BASE64"} |
content[].thinking |
string | thinking block 条件字段 | 模型输出的思考 block。多轮时仅在目标厂商要求时原样回带,不要修改或拼入 text。 | "上一轮 thinking" |
content[].signature |
string | thinking block 条件字段 | 思考签名。续接时需要原样保留,不能伪造、截断或改写。 | "sig_abc" |
content[].tool_use.id |
string | tool_use 必填 | assistant 请求调用工具的 ID,后续 tool_result.tool_use_id 必须匹配。 |
"toolu_1" |
content[].tool_use.name |
string | tool_use 必填 | 客户端工具名称,必须与业务工具注册表一致。 | "get_weather" |
content[].tool_use.input |
object | tool_use 必填 | 模型生成的工具输入。执行前必须做 schema、权限、限流和幂等校验。 | {"city":"杭州"} |
content[].tool_result.tool_use_id |
string | tool_result 必填 | 工具结果关联 ID,必须匹配已有 tool_use.id。 |
"toolu_1" |
content[].tool_result.content |
string 或 block[] | tool_result 必填 | 工具执行结果。失败时用 is_error,避免暴露凭证或内部堆栈。 |
"杭州 28 摄氏度" |
content[].tool_result.is_error |
boolean | 可选 | 标记工具结果是否为错误。 | false |
source.type |
string | source 必填 | 资源来源类别,例如 base64、URL 或上游文件资源。 | "base64" |
source.media_type |
string | base64 条件字段 | MIME 类型,必须与真实数据一致。 | "image/png" |
source.data |
string | base64 条件字段 | base64 编码数据,注意请求大小、重试成本和日志脱敏。 | "BASE64" |
source.url |
string | URL 条件字段 | 上游可访问 URL。调用方要保证权限、有效期和可达性。 | "https://example.com/file.pdf" |
temperature |
number | 可选 | 采样随机度。不同模型可能限制范围、固定采样或拒绝组合参数。 | 0.2 |
top_p |
number | 可选 | nucleus sampling 阈值。通常与 temperature 二选一调节。 |
0.9 |
top_k |
integer | 可选 | 每步采样考虑的候选 token 数。不是所有模型支持。 | 40 |
stop_sequences |
string[] | 可选 | 停止序列数组。应避免前缀歧义。 | ["END"] |
thinking |
object | 可选 | 扩展思考配置。支持度、预算范围和是否能关闭由厂商模型决定。 | {"type":"enabled","budget_tokens":1024} |
thinking.type |
string | thinking 条件字段 | 思考模式类型,可用枚举因厂商和模型不同而不同。 | "enabled" |
thinking.budget_tokens |
integer | 可选 | 分配给思考的 token 预算。DeepSeek Messages 可能忽略,详见厂商差异。 | 1024 |
tools |
array | 可选 | 客户端 function tool 或厂商服务器工具定义;高级工具只在原生支持时使用。 | [{"name":"get_weather","input_schema":{"type":"object"}}] |
tools[].name |
string | 客户端 tool 必填 | 工具稳定名称,必须与业务工具注册表一致。 | "get_weather" |
tools[].description |
string | 建议填写 | 说明何时调用、输入语义、输出形式和副作用。 | "查询城市天气" |
tools[].input_schema |
JSON Schema object | 客户端 tool 必填 | 工具输入 schema。模型输出仍需服务端校验、鉴权和限流。 | {"type":"object","properties":{"city":{"type":"string"}}} |
tools[].cache_control |
object | 可选 | 工具定义参与提示缓存时的缓存控制。位置和 TTL 语义由上游决定。 | {"type":"ephemeral"} |
tools[].type |
string | server tool 条件字段 | 上游服务器工具或高级工具类型。只在目标厂商原生 Messages 路由使用。 | "web_search_20250305" |
tool_choice |
object | 可选 | 指定工具选择行为,例如自动、任意工具、指定工具或禁用并行工具。 | {"type":"auto","disable_parallel_tool_use":true} |
tool_choice.type |
string | tool_choice 条件字段 | 工具选择类型,枚举由目标模型决定。 | "auto" |
tool_choice.name |
string | 指定工具条件字段 | 指定某个客户端工具时使用,必须匹配 tools[].name。 |
"get_weather" |
output_config |
object | 可选 | 输出行为配置,例如结构化输出或推理强度。不是所有兼容厂商都实现。 | {"format":{"type":"json_schema"}} |
output_config.format |
object | 可选 | 结构化输出格式,模型生成后仍需服务端验证。 | {"type":"json_schema","schema":{"type":"object"}} |
output_config.effort |
string | 可选 | 部分 Anthropic-compatible 厂商用于表达推理力度。 | "high" |
metadata |
object | 可选 | 调用元数据,应非敏感。metadata.aihub_* 为 AIHub 保留并剥离。 |
{"user_id":"user_hash_abc"} |
metadata.user_id |
string | 可选 | 业务终端用户的匿名稳定标识,不要传 PII。 | "user_hash_abc" |
stream |
boolean | 可选 | true 时返回 Anthropic SSE 事件,如 message_start、content_block_delta 和 message_stop。 |
true |
service_tier |
string | 可选 | 上游服务档位。是否可用由账号、区域、模型和厂商决定。 | "standard" |
container |
string 或 object | 可选 | 上游容器资源标识或配置,不是跨厂商资源。 | "container_abc" |
context_management |
object | 可选 | 长会话上下文管理策略,使用前评估截断或清理工具历史的业务影响。 | {"edits":[{"type":"clear_tool_uses_20250919"}]} |
mcp_servers |
array | 可选 | 远程 MCP server 声明,需要额外审计授权、网络出口和工具权限。 | [{"name":"crm","url":"https://mcp.example.com"}] |
mcp_servers[].authorization_token |
string | 可选 | 远程 MCP 授权 token。不要写进普通提示或长期日志。 | "Bearer token" |
cache_control.type |
string | 缓存 block 条件字段 | 缓存策略类型,例如上游规定的 ephemeral 策略。只能用于允许位置。 | "ephemeral" |
cache_control.ttl |
string | 可选 | 缓存生命周期提示。支持值、最大缓存点和计费由上游决定。 | "1h" |
OpenAI Responses 参数
适用入口:POST https://ai.yunxinapi.com/hub/v1/responses;支持 Compact 的厂商另有 POST https://ai.yunxinapi.com/hub/v1/responses/compact,Compact 只允许非流式。
| 参数 | 类型/位置 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
model |
string,body 顶层 | 必填 | AIHub logical model。必须支持 Responses operation;/v1/responses 可用不代表 /v1/responses/compact 可用。 |
"doubao-seed-1-6" |
input |
string 或 input item[] | 通常必填 | 本轮输入。简单文本可传字符串;多模态、工具续接或显式角色使用 item 数组。 | "总结这段内容" |
input[].type |
string | item 必填 | 输入 item 类型,例如 message、function_call、function_call_output、input_text、input_image。 |
"message" |
input[].role |
string | message 条件字段 | 消息角色,常见为 user、developer、system、assistant;支持度由模型决定。 |
"user" |
input[].content |
string 或 content part[] | message 条件字段 | message 内容。文本可直接传 string;多模态、文件和结构化 item 使用数组。 | [{"type":"input_text","text":"你好"}] |
input_text.text |
string | 文本 part 必填 | 文本输入内容。 | "列出风险" |
input_image.image_url |
string | 图片 part 条件字段 | 图像 URL 或 data URL。只向支持图片输入的目标模型发送。 | "https://example.com/a.png" |
input_image.file_id |
string | 图片 part 条件字段 | 上游文件资源 ID,只在创建它的上游资源域内有效。 | "file_abc" |
input_file.file_id |
string | 文件 part 条件字段 | 上游文件 ID。AIHub 不转换跨厂商文件资源。 | "file_pdf_123" |
input_file.file_data |
string | 文件 part 条件字段 | 内联文件内容,通常为 data URL 或厂商规定编码;注意请求体大小和日志脱敏。 | "data:application/pdf;base64,BASE64" |
input_file.filename |
string | 可选 | 内联文件名,用于上游识别展示;不能当作可信类型来源。 | "report.pdf" |
function_call.call_id |
string | 工具续接必填 | 模型发起函数调用的 ID,后续 function_call_output 必须使用同一 ID。 |
"call_1" |
function_call.name |
string | 工具续接必填 | 函数名,必须与业务工具注册表一致。 | "get_price" |
function_call.arguments |
string | 工具续接必填 | JSON 字符串形式的工具参数;执行前必须独立校验。 | "{\"sku\":\"A1\"}" |
function_call_output.call_id |
string | 工具结果必填 | 关联前面的 function call。缺失或错配会导致模型无法理解工具结果。 | "call_1" |
function_call_output.output |
string 或 object | 工具结果必填 | 工具执行结果。不要把异常堆栈、凭证或敏感日志直接暴露给模型。 | "库存 12 件" |
instructions |
string | 可选 | 本次响应的高优先级指令。多轮关键约束仍应按模型规则保留。 | "以 JSON 输出" |
previous_response_id |
string | 可选 | 续接上一条 Responses 响应 ID。AIHub 有历史映射时会优先回到同一 deployment identity。 | "resp_123" |
conversation |
string 或 object | 可选 | 上游托管 conversation 标识或配置。不是跨厂商资源,AIHub 不迁移。 | "conv_abc" |
background |
boolean | 可选 | 请求上游异步执行。AIHub 标准同步 HTTP/SSE 不把它变成统一任务查询契约。 | false |
max_output_tokens |
integer | 可选 | 本次响应可生成的输出 token 上限;推理和工具参数也可能计入。 | 1024 |
max_tool_calls |
integer | 可选 | 限制一次响应中的工具调用数量,用于控制成本和编排复杂度。 | 3 |
temperature |
number | 可选 | 采样随机度。推理模型或兼容厂商可能固定采样策略。 | 0.2 |
top_p |
number | 可选 | nucleus sampling 阈值。通常与 temperature 二选一调节。 |
0.9 |
top_logprobs |
integer | 可选 | 返回每个输出位置的候选 token 概率数量,会增加响应体。 | 5 |
reasoning |
object | 可选 | 推理配置对象,例如强度、摘要或模型允许的推理输出控制。 | {"effort":"high"} |
reasoning.effort |
string | 可选 | 请求推理强度。较高档位通常增加延迟和 token 消耗。 | "high" |
reasoning.summary |
string 或配置值 | 可选 | 请求可展示的推理摘要;摘要不是完整内部推理记录。 | "auto" |
text |
object | 可选 | 文本输出配置,包含格式、结构化输出或详细程度控制。 | {"format":{"type":"json_schema","name":"risk","schema":{"type":"object"}}} |
text.format.type |
string | 可选 | 文本格式类别,例如 text 或 JSON Schema。具体可用值以目标模型为准。 |
"json_schema" |
text.format.name |
string | JSON Schema 条件字段 | 结构化输出格式名称。 | "risk_list" |
text.format.schema |
object | JSON Schema 条件字段 | JSON Schema 定义,只使用模型支持的关键字子集。 | {"type":"object","properties":{"items":{"type":"array"}}} |
text.format.strict |
boolean | 可选 | 请求更严格遵循 schema;服务端仍要重新解析和验证。 | true |
text.verbosity |
string | 可选 | 对支持该字段的模型请求更简短或更详细的最终文本。 | "low" |
tools |
array | 可选 | 可供模型使用的 function 或上游内置工具。跨协议不保证保留内置工具。 | [{"type":"function","name":"lookup","parameters":{"type":"object"}}] |
tools[].type |
string | 工具项必填 | 工具类型,如 function、web_search、file_search、code_interpreter 等,需目标模型支持。 |
"function" |
tools[].name |
string | function 必填 | 函数工具名称。 | "lookup" |
tools[].description |
string | 建议填写 | 函数工具说明,描述调用条件、输入含义和副作用。 | "查询商品库存" |
tools[].parameters |
JSON Schema object | 建议填写 | 函数参数 schema,模型输出仍需应用侧校验。 | {"type":"object","properties":{"sku":{"type":"string"}}} |
tools[].strict |
boolean | 可选 | 请求严格按 schema 生成工具参数。 | true |
tool_choice |
string 或 object | 可选 | 工具选择策略,例如自动、禁止、必须或强制某个工具。 | "auto" |
parallel_tool_calls |
boolean | 可选 | 允许并行工具调用。业务方必须处理并行结果和失败回填。 | false |
truncation |
string | 可选 | 上下文过长时的截断策略。自动截断适合体验型请求,不适合必须完整保留的流程。 | "auto" |
prompt |
string 或 object | 可选 | 引用上游托管 prompt 模板或版本。AIHub 不创建、迁移或解析上游模板资源。 | {"id":"pmpt_123","version":"1"} |
prompt.id |
string | prompt object 条件字段 | 上游托管 prompt ID。 | "pmpt_123" |
prompt.version |
string | 可选 | 模板版本,避免生产请求因模板更新漂移。 | "1" |
prompt.variables |
object | 可选 | 模板变量。敏感值应遵守上游存储与日志策略。 | {"topic":"release"} |
prompt_cache_key |
string | 可选 | 缓存分组键,也可作为 AIHub 亲和候选;不要放敏感正文。 | "session_42" |
include |
string[] | 可选 | 请求额外返回上游扩展输出。每个 include 值依赖工具、模型和厂商。 | ["web_search_call.results"] |
store |
boolean | 可选 | 请求上游保存 response,用于后续 response 或 conversation 功能。 | false |
service_tier |
string | 可选 | 上游服务档位或延迟优先级提示。 | "standard" |
safety_identifier |
string | 可选 | 匿名、稳定的业务主体标识,避免传手机号、邮箱等 PII。 | "user_hash_abc123" |
user |
string | 可选,兼容字段 | 终端用户匿名标识,只在目标模型仍支持时使用。 | "user_123" |
metadata |
object | 可选 | 业务元数据。metadata.aihub_* 为 AIHub 保留并会被剥离。 |
{"trace_id":"req_123"} |
stream |
boolean | 可选 | true 时 Responses 返回事件化 SSE;https://ai.yunxinapi.com/hub/v1/responses/compact 不允许 true。 |
true |
stream_options |
object | 条件可选 | 流式扩展对象,字段随厂商演进,只在原生 Responses 路由中使用。 | {"include_usage":true} |
请求示例
json{
"model": "doubao-seed-1-6",
"messages": [
{
"role": "user",
"content": "整理下面需求的执行步骤。"
}
],
"response_format": {
"type": "json_object"
},
"max_completion_tokens": 1024
}
接口可用性由当前 API Key 的模型授权、目标模型能力和路由状态共同决定。
响应示例
以下为 Chat Completions 的典型非流式成功响应。请求使用 response_format: {"type":"json_object"} 时,message.content 仍是 JSON 字符串,客户端需要再次解析并校验业务 schema。
json{
"id": "chatcmpl-aihub-doubao-example",
"object": "chat.completion",
"created": 1786406400,
"model": "doubao-seed-1-6",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "{\"steps\":[\"确认目标与约束\",\"拆分任务并指定负责人\",\"按验收条件检查结果\"]}"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 22,
"completion_tokens": 39,
"total_tokens": 61
}
}
豆包模型可能追加厂商扩展字段;同协议原生路由会尽量保留兼容字段,但调用方不应依赖未在目标模型文档中声明的可选字段。




