GET https://ark.cn-beijing.volces.com/api/v3/responses/{responseId}
通过 ID 查询 Response 详情。如果 Response 已完成，接口会返回完整的 Response 对象；如果 Response 仍在生成中，接口会返回错误码。
鉴权#
本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数#
Path 参数#
responseId string 必选 | Response ID
要查询的 Response ID。
Query 参数#
在 URL Query String 中传入。
include string[] | 额外字段
指定响应中需要包含的额外字段。
响应参数#
created_at integer | 创建时间
本次请求创建时间的 Unix 时间戳（秒）
id string | 响应 ID
本次请求的唯一标识。
model string | 模型 ID
本次请求实际使用的模型名称和版本。
object string | 对象类型
固定为 response
output object[] | 输出条目
模型的输出消息列表，包含模型响应本次请求生成的回答、思维链、工具调用。
消息输出 object
模型生成的消息输出，包含文本内容。
content object[] | 输出内容
output.content
输出内容列表。
模型回答文本 object
模型生成的最终回答文本。
type string | 类型
output.content.type
内容类型，此处固定为 output_text
annotations object[] | 标注列表
output.content.annotations
文本附带的标注信息列表（如引用来源等）
网页引用 object
引用自互联网网页的标注信息。
title string | 标题
output.content.annotations.title
引用网页的标题。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 url_citation
url string | 网址
output.content.annotations.url
引用网页的 URL 地址。
cover_image object | 封面图
output.content.annotations.cover_image
网页封面图片信息。
height integer | 高度
output.content.annotations.cover_image.height
封面图片高度（像素）
url string | 图片地址
output.content.annotations.cover_image.url
封面图片的 URL 地址。
width integer | 宽度
output.content.annotations.cover_image.width
封面图片宽度（像素）
freshness_info string | 新鲜度
output.content.annotations.freshness_info
内容新鲜度信息。
logo_url string | Logo 地址
output.content.annotations.logo_url
网站 Logo 图标地址。
mobile_url string | 移动端地址
output.content.annotations.mobile_url
移动端访问地址。
publish_time string | 发布时间
output.content.annotations.publish_time
网页发布时间。
site_name string | 站点名
output.content.annotations.site_name
站点名称。
summary string | 摘要
output.content.annotations.summary
网页内容摘要。
文档引用 object
引用自私域知识库文档的标注信息。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 doc_citation
chunk_attachment object[] | 分块附件
output.content.annotations.chunk_attachment
引用分块附带的附件信息列表。
chunk_id integer | 分块 ID
output.content.annotations.chunk_id
引用文档分块的 ID。
doc_id string | 文档 ID
output.content.annotations.doc_id
引用文档的 ID。
doc_name string | 文档名
output.content.annotations.doc_name
引用文档的名称。
text string | 文本内容
output.content.text
模型生成的文本内容。
模型思维链文本 object
模型生成的思维链文本。
type string | 类型
output.content.type
内容类型，此处固定为 reasoning_text
annotations object[] | 标注列表
output.content.annotations
思维链附带的标注信息列表。
网页引用 object
引用自互联网网页的标注信息。
title string | 标题
output.content.annotations.title
引用网页的标题。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 url_citation
url string | 网址
output.content.annotations.url
引用网页的 URL 地址。
cover_image object | 封面图
output.content.annotations.cover_image
网页封面图片信息。
height integer | 高度
output.content.annotations.cover_image.height
封面图片高度（像素）
url string | 图片地址
output.content.annotations.cover_image.url
封面图片的 URL 地址。
width integer | 宽度
output.content.annotations.cover_image.width
封面图片宽度（像素）
freshness_info string | 新鲜度
output.content.annotations.freshness_info
内容新鲜度信息。
logo_url string | Logo 地址
output.content.annotations.logo_url
网站 Logo 图标地址。
mobile_url string | 移动端地址
output.content.annotations.mobile_url
移动端访问地址。
publish_time string | 发布时间
output.content.annotations.publish_time
网页发布时间。
site_name string | 站点名
output.content.annotations.site_name
站点名称。
summary string | 摘要
output.content.annotations.summary
网页内容摘要。
文档引用 object
引用自私域知识库文档的标注信息。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 doc_citation
chunk_attachment object[] | 分块附件
output.content.annotations.chunk_attachment
引用分块附带的附件信息列表。
chunk_id integer | 分块 ID
output.content.annotations.chunk_id
引用文档分块的 ID。
doc_id string | 文档 ID
output.content.annotations.doc_id
引用文档的 ID。
doc_name string | 文档名
output.content.annotations.doc_name
引用文档的名称。
text string | 文本内容
output.content.text
模型思维链文本内容。
id string | 条目 ID
output.id
输出条目唯一标识。
role string | 角色
output.role
角色，固定为 assistant
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 message
partial boolean | 增量片段
output.partial
是否为流式增量片段。
phase string | 消息阶段
output.phase
标记 assistant 消息属于中间讲解还是最终回答。在回放 assistant 历史消息时，建议保留并原样回传该字段。可选值：commentary、final_answer。
函数调用输出 object
模型发起的函数调用请求。
type string | 类型
output.type
输出类型，此处固定为 function_call
arguments string | 参数
output.arguments
函数参数的 JSON 字符串。
call_id string | 调用 ID
output.call_id
函数调用的唯一 ID。
id string | 条目 ID
output.id
输出条目唯一标识。
name string | 函数名
output.name
调用的函数名称。
status string | 状态
output.status
输出状态。
思维链输出 object
模型的深度思考过程输出。
status string | 状态
output.status
输出状态。
summary object[] | 推理摘要
output.summary
推理摘要内容列表。
type string | 类型
output.summary.type
摘要片段类型，固定为 summary_text
text string | 摘要文本
output.summary.text
思维链摘要文本内容。
type string | 类型
output.type
输出类型，此处固定为 reasoning
content object[] | 推理内容
output.content
思维链推理过程的内容元素列表。
模型回答文本 object
模型生成的最终回答文本。
type string | 类型
output.content.type
内容类型，此处固定为 output_text
annotations object[] | 标注列表
output.content.annotations
文本附带的标注信息列表（如引用来源等）
网页引用 object
引用自互联网网页的标注信息。
title string | 标题
output.content.annotations.title
引用网页的标题。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 url_citation
url string | 网址
output.content.annotations.url
引用网页的 URL 地址。
cover_image object | 封面图
output.content.annotations.cover_image
网页封面图片信息。
height integer | 高度
output.content.annotations.cover_image.height
封面图片高度（像素）
url string | 图片地址
output.content.annotations.cover_image.url
封面图片的 URL 地址。
width integer | 宽度
output.content.annotations.cover_image.width
封面图片宽度（像素）
freshness_info string | 新鲜度
output.content.annotations.freshness_info
内容新鲜度信息。
logo_url string | Logo 地址
output.content.annotations.logo_url
网站 Logo 图标地址。
mobile_url string | 移动端地址
output.content.annotations.mobile_url
移动端访问地址。
publish_time string | 发布时间
output.content.annotations.publish_time
网页发布时间。
site_name string | 站点名
output.content.annotations.site_name
站点名称。
summary string | 摘要
output.content.annotations.summary
网页内容摘要。
文档引用 object
引用自私域知识库文档的标注信息。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 doc_citation
chunk_attachment object[] | 分块附件
output.content.annotations.chunk_attachment
引用分块附带的附件信息列表。
chunk_id integer | 分块 ID
output.content.annotations.chunk_id
引用文档分块的 ID。
doc_id string | 文档 ID
output.content.annotations.doc_id
引用文档的 ID。
doc_name string | 文档名
output.content.annotations.doc_name
引用文档的名称。
text string | 文本内容
output.content.text
模型生成的文本内容。
模型思维链文本 object
模型生成的思维链文本。
type string | 类型
output.content.type
内容类型，此处固定为 reasoning_text
annotations object[] | 标注列表
output.content.annotations
思维链附带的标注信息列表。
网页引用 object
引用自互联网网页的标注信息。
title string | 标题
output.content.annotations.title
引用网页的标题。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 url_citation
url string | 网址
output.content.annotations.url
引用网页的 URL 地址。
cover_image object | 封面图
output.content.annotations.cover_image
网页封面图片信息。
height integer | 高度
output.content.annotations.cover_image.height
封面图片高度（像素）
url string | 图片地址
output.content.annotations.cover_image.url
封面图片的 URL 地址。
width integer | 宽度
output.content.annotations.cover_image.width
封面图片宽度（像素）
freshness_info string | 新鲜度
output.content.annotations.freshness_info
内容新鲜度信息。
logo_url string | Logo 地址
output.content.annotations.logo_url
网站 Logo 图标地址。
mobile_url string | 移动端地址
output.content.annotations.mobile_url
移动端访问地址。
publish_time string | 发布时间
output.content.annotations.publish_time
网页发布时间。
site_name string | 站点名
output.content.annotations.site_name
站点名称。
summary string | 摘要
output.content.annotations.summary
网页内容摘要。
文档引用 object
引用自私域知识库文档的标注信息。
type string | 类型
output.content.annotations.type
标注类型，此处固定为 doc_citation
chunk_attachment object[] | 分块附件
output.content.annotations.chunk_attachment
引用分块附带的附件信息列表。
chunk_id integer | 分块 ID
output.content.annotations.chunk_id
引用文档分块的 ID。
doc_id string | 文档 ID
output.content.annotations.doc_id
引用文档的 ID。
doc_name string | 文档名
output.content.annotations.doc_name
引用文档的名称。
text string | 文本内容
output.content.text
模型思维链文本内容。
encrypted_content string | 加密思维链
output.encrypted_content
经加密及压缩处理后的思维链原文，用于多轮复用。
id string | 条目 ID
output.id
输出条目唯一标识。
语音转写输出 object
模型返回的语音转写输出。
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 transcription
id string | 条目 ID
output.id
输出条目唯一标识。
transcription object[] | 转写内容
output.transcription
语音转写结果片段列表。
type string | 类型
output.transcription.type
转写片段类型，固定为 transcription_text
chunks object[] | 音频小段
output.transcription.chunks
当前片段对应的音频小段列表。
end_time integer | 结束时间
output.transcription.chunks.end_time
片段结束时间（毫秒）
start_time integer | 开始时间
output.transcription.chunks.start_time
片段开始时间（毫秒）
text string | 文字内容
output.transcription.chunks.text
当前片段对应的文字内容。
text string | 转写文本
output.transcription.text
当前片段的转写文本。
网页搜索调用 object
模型发起的网页搜索调用记录。
id string | 条目 ID
output.id
输出条目唯一标识。
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 web_search_call
action object | 搜索动作
output.action
网页搜索动作详情。
query string | 查询语句
output.action.query
模型实际发起的搜索查询语句。
type string | 类型
output.action.type
网页搜索动作类型，固定为 search
queries string[] | 查询语句列表
output.action.queries
本次网页搜索产生的查询语句列表。
图像处理调用 object
模型发起的图像处理调用记录。
id string | 条目 ID
output.id
输出条目唯一标识。
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 image_process
action object | 处理动作
output.action
图像处理动作详情。
type string | 类型
output.action.type
图像处理动作类型。
result_image_url string | 结果图地址
output.action.result_image_url
处理后图像的 URL 地址。
arguments object | 处理参数
output.arguments
图像处理参数（JSON 对象）
error object | 错误信息
output.error
图像处理失败时的错误信息。
message string | 错误描述
output.error.message
错误的可读描述。
MCP 审批请求 object
MCP 工具调用前的审批请求记录。
arguments string | 调用参数
output.arguments
工具调用参数的 JSON 字符串。
name string | 工具名
output.name
待运行的工具名称。
server_label string | 服务标签
output.server_label
发起请求的 MCP Server 标签。
type string | 类型
output.type
输出类型，此处固定为 mcp_approval_request
id string | 请求 ID
output.id
审批请求的唯一 ID。
MCP 工具清单 object
MCP Server 提供的工具清单输出。
server_label string | 服务标签
output.server_label
MCP Server 标签。
type string | 类型
output.type
输出类型，此处固定为 mcp_list_tools
error string | 列表错误
output.error
当 MCP Server 无法返回工具列表时的错误信息。
id string | 列表 ID
output.id
工具列表的唯一 ID。
tools object[] | 工具列表
output.tools
该 MCP Server 上可用的工具列表。
name string | 工具名
output.tools.name
工具名称。
annotations object | 注解信息
output.tools.annotations
工具的附加注解信息。
description string | 工具描述
output.tools.description
工具的功能描述。
input_schema object | 入参 Schema
output.tools.input_schema
描述工具入参的 JSON Schema。
MCP 工具调用 object
模型对 MCP 工具的实际调用记录及结果。
name string | 工具名
output.name
实际运行的工具名称。
server_label string | 服务标签
output.server_label
运行工具的 MCP Server 标签。
type string | 类型
output.type
输出类型，此处固定为 mcp_call
arguments string | 调用参数
output.arguments
传递给工具的调用参数 JSON 字符串。通过 response.mcp_call_arguments.delta 流式追加，初始 output_item.added 事件可能不携带该字段。
error string | 调用错误
output.error
工具调用失败时的错误信息。
id string | 调用 ID
output.id
工具调用的唯一 ID。
output string | 返回结果
output.output
工具调用的返回结果。
知识库检索调用 object
模型发起的私域知识库检索调用记录。
knowledge_resource_id string | 知识库 ID
output.knowledge_resource_id
检索使用的知识库 ID。
queries string[] | 查询语句
output.queries
实际执行的检索查询语句列表。
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 knowledge_search_call
id string | 条目 ID
output.id
输出条目唯一标识。
豆包应用调用 object
模型对豆包助手能力的调用记录。
type string | 类型
output.type
输出类型，此处固定为 doubao_app_call
blocks object[] | 内容块
output.blocks
豆包应用调用产出的内容块列表。
文本输出 object
豆包应用产出的文本输出内容块。
type string | 类型
output.blocks.type
内容块类型，此处固定为 output_text
id string | 块 ID
output.blocks.id
内容块的唯一标识。
parent_id string | 父级 ID
output.blocks.parent_id
所属父级条目的 ID。
status string | 状态
output.blocks.status
内容块状态。
text string | 文本内容
output.blocks.text
思维链文本 object
豆包应用产出的思维链文本内容块。
type string | 类型
output.blocks.type
内容块类型，此处固定为 reasoning_text
id string | 块 ID
output.blocks.id
内容块的唯一标识。
parent_id string | 父级 ID
output.blocks.parent_id
所属父级条目的 ID。
reasoning_text string | 思考文本
output.blocks.reasoning_text
思维链文本内容。
status string | 状态
output.blocks.status
内容块状态。
搜索过程 object
豆包应用 AI 搜索过程产出的内容块。
type string | 类型
output.blocks.type
内容块类型，此处固定为 search
id string | 块 ID
output.blocks.id
内容块的唯一标识。
parent_id string | 父级 ID
output.blocks.parent_id
所属父级条目的 ID。
queries string[] | 查询语句
output.blocks.queries
搜索查询语句列表。
results object[] | 搜索结果
output.blocks.results
搜索结果列表。
text_card object | 文本卡片
output.blocks.results.text_card
文本卡片形式的搜索结果。
sitename string | 站点名
output.blocks.results.text_card.sitename
来源站点名称。
title string | 标题
output.blocks.results.text_card.title
搜索结果标题。
url string | 网址
output.blocks.results.text_card.url
搜索结果 URL 地址。
status string | 状态
output.blocks.status
内容块状态。
summary string | 搜索总结
output.blocks.summary
推理搜索过程 object
豆包应用推理搜索过程产出的内容块。
type string | 类型
output.blocks.type
内容块类型，此处固定为 reasoning_search
id string | 块 ID
output.blocks.id
内容块的唯一标识。
parent_id string | 父级 ID
output.blocks.parent_id
所属父级条目的 ID。
queries string[] | 查询语句
output.blocks.queries
搜索查询语句列表。
results object[] | 搜索结果
output.blocks.results
搜索结果列表。
text_card object | 文本卡片
output.blocks.results.text_card
文本卡片形式的搜索结果。
sitename string | 站点名
output.blocks.results.text_card.sitename
来源站点名称。
title string | 标题
output.blocks.results.text_card.title
搜索结果标题。
url string | 网址
output.blocks.results.text_card.url
搜索结果 URL 地址。
status string | 状态
output.blocks.status
内容块状态。
summary string | 搜索总结
output.blocks.summary
推理搜索总结。
feature string | 功能名
output.feature
触发的豆包子功能名称（如 chat、deep_chat、ai_search、reasoning_search）
id string | 条目 ID
output.id
输出条目唯一标识。
status string | 状态
output.status
输出状态。
智能体工具调用 object
模型发起的智能体工具调用记录。
name string | 工具名
output.name
被调用的智能体工具名称。
status string | 状态
output.status
输出状态。
type string | 类型
output.type
输出类型，此处固定为 agent_tool_call
id string | 条目 ID
output.id
输出条目唯一标识。
caching object | 上下文缓存
是否开启缓存。
prefix boolean | 仅写缓存
caching.prefix
是否仅写入前缀缓存，不生成回复。true 只写缓存，不返回模型输出；false 正常生成回复并写缓存。
type string | 缓存模式
caching.type
缓存模式。enabled 开启上下文缓存；disabled 关闭上下文缓存。
context_management object | 上下文管理
上下文管理响应，请求过程中应用的上下文管理策略信息。
applied_edits object[] | 已应用编辑
context_management.applied_edits
已应用的上下文编辑结果列表。
清理工具调用 object
已应用的清理工具调用编辑结果。
cleared_tool_uses integer | 清理次数
context_management.applied_edits.cleared_tool_uses
已清理的工具调用数量。
type string | 类型
context_management.applied_edits.type
编辑类型，此处固定为 clear_tool_uses
清理思维链 object
已应用的清理思维链编辑结果。
cleared_thinking_turns integer | 清理轮次
context_management.applied_edits.cleared_thinking_turns
已清理的思维链轮次数量。
type string | 类型
context_management.applied_edits.type
编辑类型，此处固定为 clear_thinking
error object | 错误信息
模型未能生成响应时返回的错误对象。
code string | 错误码
error.code
message string | 错误描述
error.message
错误信息的可读描述。
expire_at integer | 过期时间戳
响应储存的过期时刻 Unix 时间戳（秒）
incomplete_details object | 未完成详情
响应未能完成的细节。
reason string | 原因
incomplete_details.reason
响应未完成的原因。
content_filter object | 内容过滤
incomplete_details.content_filter
内容过滤详情。
details string | 详情
incomplete_details.content_filter.details
内容过滤命中的详细描述。
type string | 类型
incomplete_details.content_filter.type
内容过滤命中的类型。
instructions string | 系统指令
在模型上下文中插入一条系统（或开发者）消息，作为首项。当与 previous_response_id 一起使用时，前一响应中的指令不会延续到下一响应。
max_output_tokens integer | 最大输出长度
模型输出最大 token 数，包含模型回答和思维链内容。
max_tool_calls integer | 最大调用轮次
本次请求生效的最大工具调用轮次。
metadata object | 自定义元数据
回显请求中的 metadata 键值对元数据。最多支持 16 对键值，key 长度不超过 64 个字符，value 长度不超过 512 个字符，服务端不会解释其中内容。
previous_response_id string | 上轮响应 ID
本次请求时传入的历史响应 ID。
reasoning object | 思考工作量
本次请求实际生效的深度思考工作量配置。
effort string | 思考力度
reasoning.effort
限制深度思考的工作量。减少深度思考工作量可使响应速度更快，并且深度思考的 token 用量更小。
service_tier string | 推理模式
本次请求实际使用的推理模式。
fast：本次请求使用 在线推理（低延迟） 模式。auto：本次请求使用 在线推理（TPM 保障包） 模式。default：本次请求使用 在线推理（常规） 模式。flex：本次请求使用 在线推理（低优） 模式。
status string | 响应状态
生成响应的状态。completed 表示已完成；failed 表示失败；in_progress 表示响应中；incomplete 表示未完成。
store boolean | 存储响应
是否存储生成的模型响应，以便后续通过 API 检索。
temperature number | 采样温度
text object | 输出格式
用于定义输出的格式，可以是纯文本，也可以是结构化的 JSON 数据。
format object | 输出格式
text.format
文本输出格式定义。
type string | 格式类型
text.format.type
输出格式类型。取值范围：text、json_schema、json_object
description string | 格式描述
text.format.description
格式描述信息。
name string | 格式名称
text.format.name
格式名称（仅 json_schema 类型时需要）
schema object | Schema 定义
text.format.schema
JSON Schema 定义（仅 json_schema 类型时需要）
strict boolean | 严格模式
text.format.strict
是否严格校验输出格式。
thinking object | 深度思考开关
是否开启深度思考模式。
type string | 思考模式
thinking.type
深度思考模式。enabled 开启深度思考；disabled 关闭深度思考；auto 由模型自行判断是否需要深度思考。
tool_choice string / object | 工具调用策略
本次请求实际生效的工具调用策略。
简单策略 string
直接传入字符串 none、auto 或 required，控制工具调用整体策略。
指定工具 object
通过对象指定具体工具类型或工具名进行调用。
type string | 工具类型
tool_choice.type
指定工具的类型，例如 function、web_search、mcp、knowledge_search 等内置工具类型。取值：function / web_search / image_process / mcp / knowledge_search / doubao_app。
name string | 工具名称
tool_choice.name
当通过名称选择具体工具时使用，例如指定 MCP 服务下的某个工具名。
tools object[] | 工具列表
模型可以调用的工具列表。
函数调用 object
自定义函数调用（Function Calling），让模型生成结构化的函数参数。
name string | 函数名
tools.name
函数名称。
type string | 类型
tools.type
工具类型，此处固定为 function
description string | 函数描述
tools.description
函数的描述信息，帮助模型理解何时使用该函数。
parameters object | 参数定义
tools.parameters
函数参数定义，遵循 JSON Schema 格式。
联网搜索 object
联网搜索工具，让模型在需要时自动进行网页搜索获取实时信息。
type string | 类型
tools.type
工具类型，此处固定为 web_search
limit integer | 最大结果数
tools.limit
每轮搜索最大返回结果数量。
取值范围：[1, 50]
max_keyword integer | 最大关键词数
tools.max_keyword
最大并行搜索关键词数量。
取值范围：[1, 50]
sources string[] | 搜索来源
tools.sources
搜索信息来源限制，指定模型可从哪些渠道检索网页内容。可选值：toutiao、douyin、moji、search_engine、doubao。
user_location object | 用户位置
tools.user_location
用户地理位置信息，用于搜索优化。
type string | 类型
tools.user_location.type
位置类型，此处固定为 approximate
city string | 城市
tools.user_location.city
用户所在城市。
country string | 国家
tools.user_location.country
用户所在国家。
region string | 地区
tools.user_location.region
用户所在地区。
timezone number | 时区
tools.user_location.timezone
用户所在时区。
图像处理 object
图像处理工具，让模型对图片进行画点、选区、缩放、旋转等操作。
type string | 类型
tools.type
工具类型，此处固定为 image_process
grounding object | 选区功能
tools.grounding
选区/裁切功能开关。
type string | 开关
tools.grounding.type
功能开关。
point object | 画点功能
tools.point
画点/画线功能开关。
type string | 开关
tools.point.type
功能开关。
rotate object | 旋转功能
tools.rotate
旋转功能开关（0-359 度）
type string | 开关
tools.rotate.type
功能开关。
zoom object | 缩放功能
tools.zoom
缩放功能开关（0.5-2.0 倍）
type string | 开关
tools.zoom.type
功能开关。
MCP 工具 object
MCP（Model Context Protocol）工具，让模型调用外部 MCP Server 提供的工具。
server_label string | 服务标签
tools.server_label
MCP Server 标识标签。
server_url string | 服务地址
tools.server_url
MCP Server URL 地址。
type string | 类型
tools.type
工具类型，此处固定为 mcp
allowed_tools string[] / object | 允许工具
tools.allowed_tools
允许调用的工具范围。
工具名数组 string[]
直接传入允许调用的工具名称数组。
工具过滤器 object
通过过滤器对象指定允许调用的工具范围。
tool_names string[] | 工具名列表
tools.allowed_tools.tool_names
允许调用的工具名称列表。
headers object | 请求头
tools.headers
HTTP 请求头（如鉴权信息等）
require_approval string / object | 审批策略
tools.require_approval
工具调用审批策略。取值可为字符串 always、never，或包含审批过滤规则的对象。
简单策略 string
直接传入字符串 always 或 never，对所有工具应用统一审批策略。
工具过滤器 object
通过过滤器对象按工具粒度配置审批策略。
always object | 始终审批
tools.require_approval.always
始终需要审批的工具过滤器。
tool_names string[] | 工具名列表
tools.require_approval.always.tool_names
始终需要审批的工具名称列表。
never object | 无需审批
tools.require_approval.never
无需审批的工具过滤器。
tool_names string[] | 工具名列表
tools.require_approval.never.tool_names
无需审批即可调用的工具名称列表。
server_description string | 服务描述
tools.server_description
MCP Server 的描述信息，帮助模型理解何时使用该 Server。
知识库搜索 object
私域知识库搜索工具，让模型检索企业内部知识库中的文档内容。
knowledge_resource_id string | 知识库 ID
tools.knowledge_resource_id
type string | 类型
tools.type
工具类型，此处固定为 knowledge_search
dense_weight number | 稠密权重
tools.dense_weight
稠密向量权重。
取值范围：[0.2, 1]
description string | 知识库描述
tools.description
知识库描述信息，帮助模型理解何时使用该知识库。
doc_filter object | 文档过滤
tools.doc_filter
文档字段级别的检索过滤条件。
limit integer | 最大结果数
tools.limit
最大搜索结果数量。
取值范围：[1, 200]
max_keyword integer | 最大关键词数
tools.max_keyword
最大并行搜索关键词数量。
取值范围：[1, 50]
ranking_options object | 排序选项
tools.ranking_options
检索后处理选项（重排序、分段扩散等）
豆包助手 object
豆包助手工具，让模型使用豆包的聊天、深度思考、AI 搜索和推理搜索能力。
feature object | 功能配置
tools.feature
豆包子功能配置。
ai_search object | AI 搜索
tools.feature.ai_search
AI 搜索功能配置。
role_description string | 角色描述
tools.feature.ai_search.role_description
角色描述，用于定义该功能的行为特征。
type string | 开关
tools.feature.ai_search.type
功能开关。取值范围：enabled、disabled
chat object | 普通聊天
tools.feature.chat
普通聊天功能配置。
role_description string | 角色描述
tools.feature.chat.role_description
角色描述，用于定义该功能的行为特征。
type string | 开关
tools.feature.chat.type
功能开关。取值范围：enabled、disabled
deep_chat object | 深度聊天
tools.feature.deep_chat
深度聊天功能配置。
role_description string | 角色描述
tools.feature.deep_chat.role_description
角色描述，用于定义该功能的行为特征。
type string | 开关
tools.feature.deep_chat.type
功能开关。取值范围：enabled、disabled
reasoning_search object | 推理搜索
tools.feature.reasoning_search
推理搜索功能配置。
role_description string | 角色描述
tools.feature.reasoning_search.role_description
角色描述，用于定义该功能的行为特征。
type string | 开关
tools.feature.reasoning_search.type
功能开关。取值范围：enabled、disabled
type string | 类型
tools.type
工具类型，此处固定为 doubao_app
user_location object | 用户位置
tools.user_location
用户地理位置信息，用于搜索优化。
type string | 类型
tools.user_location.type
位置类型，此处固定为 approximate
city string | 城市
tools.user_location.city
用户所在城市。
country string | 国家
tools.user_location.country
用户所在国家。
region string | 地区
tools.user_location.region
用户所在地区。
timezone number | 时区
tools.user_location.timezone
用户所在时区。
top_p number | 核采样阈值
核采样概率阈值。
usage object | Token 用量
本次请求的 token 用量，包括输入 token 数量、输入 token 的详细分解、输出 token 数量、输出 token 的详细分解，以及总共使用的 token 数。如果使用了工具，还会输出使用的工具类型和次数，以及工具的使用详情。
input_tokens integer | 输入 token 数
usage.input_tokens
输入消耗的 token 数量。
input_tokens_details object | 输入明细
usage.input_tokens_details
输入 token 用量明细。
cached_tokens integer | 缓存 token
usage.input_tokens_details.cached_tokens
命中缓存的 token 数量。
audio_cached_tokens integer | 音频缓存 Token 数
usage.input_tokens_details.audio_cached_tokens
缓存命中的音频输入内容所消耗的 token 数量。仅在隐式缓存模式且命中音频缓存时返回；开启显式缓存时该字段不返回。
audio_tokens integer | 音频 token
usage.input_tokens_details.audio_tokens
音频输入消耗的 token 数量。
output_tokens integer | 输出 token 数
usage.output_tokens
输出消耗的 token 数量。
output_tokens_details object | 输出明细
usage.output_tokens_details
输出 token 用量明细。
reasoning_tokens integer | 思考 token
usage.output_tokens_details.reasoning_tokens
深度思考消耗的 token 数量。
total_tokens integer | 总 token 数
usage.total_tokens
本次请求消耗的 token 总数。
tool_usage object | 工具用量
usage.tool_usage
工具调用用量统计。
doubao_app integer | 豆包次数
usage.tool_usage.doubao_app
豆包助手工具调用次数。
knowledge_search integer | 知识库次数
usage.tool_usage.knowledge_search
知识库搜索工具调用次数。
mcp integer | MCP 次数
usage.tool_usage.mcp
MCP 工具调用次数。
web_search integer | 搜索次数
usage.tool_usage.web_search
联网搜索工具调用次数。
tool_usage_details object | 工具明细
usage.tool_usage_details
工具调用用量明细。
doubao_app object | 豆包明细
usage.tool_usage_details.doubao_app
豆包助手工具用量明细。
knowledge_search object | 知识库明细
usage.tool_usage_details.knowledge_search
知识库搜索工具用量明细。
mcp object | MCP 明细
usage.tool_usage_details.mcp
MCP 工具用量明细。
web_search object | 搜索明细
usage.tool_usage_details.web_search
联网搜索工具用量明细。