Skip to main content
OpenAI兼容-Responses

创建响应

通过兼容 OpenAI 格式的 Responses API 调用千问模型,查看输入输出参数说明及调用示例。

相较于OpenAI Chat Completions API 的优势:
  • 内置工具:内置联网搜索、网页抓取、代码解释器、文搜图、图搜图、知识库搜索等工具,可在处理复杂任务时获得更优效果,详情参考工具调用
  • 更灵活的输入:支持直接传入字符串作为模型输入,也兼容 Chat 格式的消息数组。
  • 简化上下文管理:通过传递上一轮响应的 previous_response_id,无需手动构建完整的消息历史数组。
  • 便捷的上下文缓存:只需在请求头中添加 x-dashscope-session-cache: enable(默认值为 disable),服务端即可自动缓存对话上下文,无需改动业务代码即可降低多轮对话的推理延迟与成本,详情参考Session 缓存

兼容性说明与限制

本 API 在接口设计上兼容 OpenAI,以降低开发者迁移成本,但在参数、功能和具体行为上存在差异。 核心原则:请求将仅处理本文档明确列出的参数,任何未提及的 OpenAI 参数都会被忽略。 以下是几个关键的差异点,以帮助您快速适配:
  • 部分参数不支持:不支持部分 OpenAI Responses API 参数,例如异步执行参数background(当前仅支持同步调用)等。
  • 思考强度控制:通过 reasoning.effort 参数控制模型的思考强度,具体用法请参考相应参数的说明。
  • 华北2(北京)
  • 新加坡
  • 美国(弗吉尼亚)
  • 德国(法兰克福)
  • 日本(东京)
SDK 调用配置的base_urlhttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1HTTP 请求地址:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
调用时请将{WorkspaceId}替换为真实的业务空间ID
阿里云百炼为华北2(北京)、新加坡地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议迁移至新域名:
  • 华北2(北京)地域:从 https://dashscope.aliyuncs.com 迁移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域:从 https://dashscope-intl.aliyuncs.com 迁移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。
OpenAI兼容-Responses API 的旧版URL路径 /api/v2/apps/protocols/compatible-mode/v1/responses 即将停止维护,请尽快迁移至新版路径 /compatible-mode/v1/responses

请求体

model string (必选)模型名称。
  • 华北2(北京)
  • 新加坡
  • 美国(弗吉尼亚)
  • 德国(法兰克福)
  • 日本(东京)
qwen3.8-maxqwen3.8-flashqwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08qwen3-maxqwen3-max-2026-01-23qwen3.7-plusqwen3.7-plus-2026-05-26qwen3.6-plusqwen3.6-plus-2026-04-02qwen3.5-plusqwen3.5-plus-2026-04-20qwen3.5-plus-2026-02-15qwen3.7-flashqwen3.7-flash-2026-07-15qwen3.6-flashqwen3.6-flash-2026-04-16qwen3.5-flashqwen3.5-flash-2026-02-23qwen3.8-2.4t-a95bqwen3.8-27bqwen3.6-35b-a3bqwen3.5-397b-a17bqwen3.5-122b-a10bqwen3.5-27bqwen3.5-35b-a3bqwen-plusqwen-flashqwen3-coder-plusqwen3-coder-flashqwen3.5-ocrqwen-plus-characterqwen-flash-characterdeepseek-v4-prodeepseek-v4-pro-0813deepseek-v4-flashdeepseek-v4-flash-0731glm-5.2
input string 或 array (必选)模型输入,支持以下格式:
  • string:纯文本,如 "你好"
  • array:消息数组,按对话顺序排列。
EasyInputMessage object通过 role 区分消息类型,通过content传递消息内容。
role string (必选)消息角色,可选值:userassistantsystemdevelopercontent string 或 array (必选)消息内容。若输入为纯文本,则为 string 类型;若输入为结构化内容数组,则为 array 类型。role 为 system/developer 时,array 元素类型为 input_text;role 为 user 时,array 元素类型为 input_textinput_imageinput_file;role 为 assistant 时,array 元素类型为 output_text
当前 Responses API 暂不支持传入视频或语音,您可以通过Chat Completions APIDashScope API传入。
type string (必选)可选值:input_text(文本输入)、input_image(图片输入,仅 user 角色)、input_file(文件输入,仅 user 角色,支持 PDF 和图片)、output_text(助手回复,仅 assistant 角色)。text string文本内容。当 type 为 input_textoutput_text 时必填。image_url string支持 URL 或者 Base64 编码,当 type 为 input_image 时必填。Base64 请传入完整的 Data URI,例如:data:image/png;base64,iVBORw0K...file_url string文件的公网 URL。当 type 为 input_file 时必填。支持 PDF 文件(最大 10 页、100 MB)和图片文件(最大 20 MB)。目前仅 qwen3.5-ocr 支持此类型。
type string (可选)固定为 message
ResponseOutputMessage object (可选)模型的输出消息对象。可直接将上一轮响应的 output 中的 message 项传回 input,用于多轮对话场景。与 EasyInputMessage 的区别在于它携带了完整的输出结构(含 id、status 和结构化 content)。
type string (必选)固定为 messageid string (必选)输出消息的唯一标识,来自上一轮响应。role string (必选)固定为 assistantstatus string (必选)消息状态,可选值:in_progresscompletedincompletecontent array (必选)内容数组,元素为 output_text 类型对象。
type string (必选)固定为 output_texttext string (必选)回复文本。annotations array (可选)标注信息。
Function Call object (可选)模型决定调用外部工具时生成的结构化指令。
type string (必选)固定为 function_callid string (可选)Function Call 的唯一标识,来自上一轮响应。name string (必选)工具函数名称。arguments string (必选)工具调用参数,JSON 字符串格式。call_id string (必选)工具调用的标识符,需与模型返回的 call_id 一致。status string (可选)状态,可选值:in_progresscompletedincomplete
Function Call Output object (可选)工具调用的输出结果。在消息列表中必须紧跟对应的 function_call 消息,否则会报错。
type string (必选)固定为 function_call_outputid string (可选)Function Call Output 的唯一标识。call_id string (必选)工具调用的标识符,需与模型返回的 call_id 一致。output string (必选)工具函数的执行结果。status string (可选)状态,可选值:in_progresscompletedincomplete
Reasoning object (可选)模型的思考内容。可直接将上一轮响应的 output 中的 reasoning 项传回 input,用于在多轮对话中传递思考内容。
type string (必选)固定为 reasoningid string (必选)思考内容的唯一标识,来自上一轮响应。summary array (必选)思考摘要内容。
type string (必选)固定为 summary_texttext string (必选)摘要文本。
status string (可选)状态,可选值:in_progresscompletedincomplete
Web Search Call object (可选)搜索调用对象。可直接将上一轮响应的 output 中的 web_search_call 项传回 input,用于在多轮对话中传递搜索结果上下文。
type string (必选)固定为 web_search_callid string (必选)搜索调用的唯一标识,来自上一轮响应。status string (必选)搜索状态,可选值:in_progresssearchingcompletedfailedaction object (必选)搜索信息。仅支持 search 类型。
type string (必选)搜索类型,固定为 searchqueries array (可选)搜索查询词列表,元素类型为 string。sources array (可选)搜索结果来源列表。
type string (必选)来源类型,固定为 urlurl string (必选)来源 URL。
instructionsstring (可选)作为系统指令插入到上下文的起始位置。使用 previous_response_id 时,上一轮指定的 instructions 不会传入本轮上下文。previous_response_id string (可选)上一个响应的唯一 ID,当前响应id有效期为7天。使用此参数可创建多轮对话,服务端会自动检索并组合该轮次的输入与输出作为上下文。当同时提供 input 消息数组和 previous_response_id 时,input 中的新消息会追加到历史上下文之后。不能与 conversation 同时使用。conversation string (可选)当前响应所属的会话(参考Conversations API)。会话中的历史项会自动作为上下文传入本次请求,本次请求的输入和输出也会在响应完成后自动添加到会话中。不能与 previous_response_id 同时使用。stream boolean (可选)默认值为 false是否开启流式输出。设置为 true 时,模型响应数据将实时流式返回给客户端。store boolean (可选)默认值为 true是否储存本次会话生成的模型响应。
  • false:不储存,对话内容不能被 previous_response_id 和后续 API 使用。
  • true:储存,当前模型响应可被 previous_response_id 和后续 API 使用。
tools array (可选)模型在生成响应时可调用的工具数组。支持内置工具和自定义 function 工具,可混合使用。
为了获得最佳回复效果,建议同时开启 code_interpreterweb_searchweb_extractor 工具。
web_search联网搜索工具,允许模型搜索互联网上的最新信息。相关文档:联网搜索
type string (必选)固定为web_search使用示例:[{"type": "web_search"}]
web_extractor网页抽取工具,允许模型访问并提取网页内容。当前必须配合web_search工具一起使用。qwen3-maxqwen3-max-2026-01-23需要同时开启思考模式。相关文档:网页抓取
type string (必选)固定为web_extractor使用示例:[{"type": "web_search"}, {"type": "web_extractor"}]
code_interpreter代码解释器工具,允许模型执行代码并返回结果,支持数据分析。qwen3.8-maxqwen3.8-flashqwen3-maxqwen3-max-2026-01-23qwen3.7-maxqwen3.7-max-2026-05-20qwen3.7-max-2026-06-08需要同时开启思考模式。相关文档:代码解释器
type string (必选)固定为code_interpreter使用示例:[{"type": "code_interpreter"}]
web_search_image根据文本描述搜索图片。相关文档:文搜图
type string (必选)固定为web_search_image使用示例:[{"type": "web_search_image"}]
image_search根据图片搜索相似或相关图片,输入中需要包含图片的URL。相关文档:图搜图
type string (必选)固定为image_search使用示例:[{"type": "image_search"}]
file_search在已上传或关联的知识库中搜索。相关文档:知识检索
type string (必选)固定为file_searchvector_store_ids array(必选)要检索的知识库 ID。当前仅支持传入一个知识库 ID使用示例:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
MCP调用通过 MCP(Model Context Protocol)调用外部服务,相关文档:MCP
type string (必选)固定为mcpserver_protocol string (必选)与 MCP 服务的通信协议,如 "sse"server_label string (必选)服务标签,用于标识该 MCP 服务。server_description string (可选)服务描述,帮助模型理解其功能与适用场景。server_url string (必选)MCP 服务端点的 URL。headers object (可选)请求头,用于携带身份验证等信息,如 Authorization使用示例:
mcp_tool = {
    "type": "mcp",
    "server_protocol": "sse",
    "server_label": "amap-maps",
    "server_description": "高德地图MCP Server现已覆盖15大核心接口,提供全场景覆盖的地理信息服务,包括生成专属地图、导航到目的地、打车、地理编码、逆地理编码、IP定位、天气查询、骑行路径规划、步行路径规划、驾车路径规划、公交路径规划、距离测量、关键词搜索、周边搜索、详情搜索等。",
    "server_url": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/mcps/amap-maps/sse",
    "headers": {
        "Authorization": "Bearer <your-mcp-server-token>"
    }
}
自定义工具function自定义函数工具,允许模型调用您定义的函数。当模型判断需要调用工具时,响应会返回 function_call 类型的输出。相关文档:Function Calling
type string (必选)必须设置为functionnamestring(必选)工具名称。仅允许字母、数字、下划线(_)和短划线(-),最长 64 个 Token。descriptionstring(必选)工具描述信息,帮助模型判断何时以及如何调用该工具。parameters object (可选)工具的参数描述,需要是一个合法的 JSON Schema。若parameters参数为空,表示该工具没有入参(如时间查询工具)。
为提高工具调用的准确性,建议传入 parameters
使用示例:
[{
  "type": "function",
  "name": "get_weather",
  "description": "获取指定城市的天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称"
      }
    },
    "required": ["city"]
  }
}]
tool_choice string or object (可选)默认值为 auto控制模型如何选择和调用工具。此参数支持两种赋值格式:字符串模式对象模式字符串模式
  • auto:模型自动决定是否调用工具。
  • none:禁止模型调用任何工具。
  • required:强制模型调用工具(仅当 tools 列表中只有一个工具时可用)。
对象模式为模型设定可用的工具范围,仅限在预定义的工具列表中进行选择和调用。
mode string (必选)
  • auto:模型自动决定是否调用工具。
  • required:强制模型调用工具(仅当 tools 列表中只有一个工具时可用)。
tools array(必选)一个包含工具定义的列表,模型将被允许调用这些工具。
[
  { "type": "function", "name": "get_weather" }
]
typestring (必选)允许的工具配置类型,固定为 allowed_tools
temperaturefloat(可选)采样温度,控制模型生成文本的多样性。temperature越高,生成的文本更多样,反之,生成的文本更确定。取值范围: [0, 2)temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述top_pfloat(可选)核采样的概率阈值,控制模型生成文本的多样性。top_p越高,生成的文本更多样。反之,生成的文本更确定。取值范围:(0,1.0]temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述enable_thinking boolean (可选)是否开启思考模式。开启后,模型会在回复前进行思考,思考内容将通过 reasoning 类型的输出项返回。开启思考模式时,建议开启内置工具,以在处理复杂任务时获得最佳的模型效果。可选值:
  • true:开启
  • false:不开启
不同模型的默认值:支持的模型
该参数非OpenAI标准参数。Python SDK 通过 extra_body={"enable_thinking": True} 传递;Node.js SDK 和 curl 直接使用 enable_thinking: true 作为顶层参数。建议使用 reasoning.effort 替代,enable_thinking 后续将不再支持。
reasoning object (可选)控制模型的思考强度。模型会在回复前进行思考,思考内容将通过 reasoning 类型的输出项返回。
effort string (可选):思考强度档位,默认值为 xhigh支持 noneminimallowmediumhighxhighmax 共 7 个递增档位。降低该值可加快响应速度并减少推理 Token 的消耗。
华北2(北京)新加坡支持xhighmax档位。
reasoning.effort 的优先级高于 enable_thinking,建议优先使用 reasoning.effortenable_thinking 后续将不再支持。
ocr_options object (可选)OCR 定制任务参数。仅适用于 qwen3.5-ocr 模型。通过此参数可调用内置的 OCR 任务(如信息抽取、文字定位等),定制任务结果通过响应中的 ocr_result 字段返回。
该参数非 OpenAI 标准参数。Python SDK 通过 extra_body={"ocr_options": {...}} 传递;Node.js SDK 和 curl 直接使用 ocr_options 作为顶层参数。
max_output_tokens integer(可选)
  • Qwen3.8系列:模型回复内容和思维链内容之和的最大Token数。
  • 其余模型:模型回复内容的最大Token数。
最小值为16,模型输出超过此值时生成将提前停止,状态为incomplete
  • 基础调用
  • 流式输出
  • 多轮对话
  • 调用内置工具
  • 自定义 Function Call
  • 文档理解
  • Session 缓存
Python
import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.8-max",
    input="你能做些什么?"
)

# 获取模型回复
print(response.output_text)

Response 响应对象(非流式输出)

id string本次响应的唯一标识符,为 UUID 格式的字符串,有效期为7天。可用于 previous_response_id 参数以创建多轮对话。created_at integer本次请求的 Unix 时间戳(秒)。object string对象类型,固定为 responsestatus string响应生成的状态。枚举值:
  • completed:生成完成
  • failed:生成失败
  • in_progress:生成中
  • cancelled:已取消
  • queued:请求排队中
  • incomplete:生成不完整
model string用于生成响应的模型 ID。output array模型生成的输出项数组。数组中的元素类型和顺序取决于模型的响应。
type string输出项类型。枚举值:
  • message:消息类型,包含模型最终生成的回复内容。
  • reasoning:推理类型,设置 reasoning.effort(非 none)或开启思考模式时返回。推理 Token 会被计入 output_tokens_details.reasoning_tokens 中,按推理 Token 计费。
  • function_call:函数调用类型,使用自定义 function 工具时返回。需要处理函数调用并返回结果。
  • web_search_call:搜索调用类型,使用 web_search 工具时返回。
  • code_interpreter_call:代码执行类型,使用 code_interpreter 工具时返回。
  • web_extractor_call:网页抽取类型,使用 web_extractor 工具时返回。需要配合 web_search 工具一起使用。
  • web_search_image_call:文搜图调用类型,使用 web_search_image 工具时返回。包含搜索到的图片列表。
  • image_search_call:图搜图调用类型,使用 image_search 工具时返回。包含搜索到的相似图片列表。
  • mcp_call:MCP 调用类型,使用 mcp 工具时返回。包含 MCP 服务的调用结果。
  • file_search_call:知识库搜索调用类型,使用 file_search 工具时返回。包含知识库的检索查询和结果。
id string输出项的唯一标识符。所有类型的输出项都包含此字段。role string消息角色,固定为 assistant。仅当 typemessage 时存在。status string输出项状态。可选值:completed(完成)、in_progress(生成中)。当 type 不为reasoning时存在。name string工具或函数名称。当 typefunction_callweb_search_image_callimage_search_callmcp_call 时存在。对于 web_search_image_callimage_search_call,值分别固定为 "web_search_image""image_search"对于 mcp_call,值为 MCP 服务中被调用的具体函数名(如 amap-maps-maps_geo)。arguments string工具调用的参数,JSON 字符串格式。当 typefunction_callweb_search_image_callimage_search_callmcp_call 时存在。使用前需要通过 JSON.parse() 解析。不同工具类型的 arguments 内容:
  • web_search_image_call{"queries": ["搜索关键词1", "搜索关键词2"]},其中 queries 为模型根据用户输入自动生成的搜索关键词列表。
  • image_search_call{"img_idx": 0, "bbox": [0, 0, 1000, 1000]},其中 img_idx 为输入图片的索引(从 0 开始),bbox 为搜索区域的边界框坐标 [x1, y1, x2, y2],坐标范围 0-1000。
  • function_call:按用户定义的函数参数 schema 生成的参数对象。
  • mcp_call:MCP 服务中被调用函数的参数对象。
call_id string函数调用的唯一标识符。仅当 typefunction_call 时存在。在返回函数调用结果时,需要通过此 ID 关联请求与响应。content array消息内容数组。仅当 typemessage 时存在。
type string内容类型,固定为 output_texttext string模型生成的文本内容。annotations array文本注释数组。通常为空数组。
summary array推理摘要数组。仅当 typereasoning 时存在。每个元素包含 type(值为 summary_text)和 text(摘要文本)字段。action object搜索动作信息。仅当 typeweb_search_call 时存在。
query string搜索查询关键词。type string搜索类型,固定为 searchsources array搜索来源列表。每个元素包含 typeurl字段。
code string模型生成并执行的代码。仅当 typecode_interpreter_call 时存在。outputs array代码执行输出数组。仅当 typecode_interpreter_call 时存在。每个元素包含 type(值为 logs)和 logs(代码执行日志)字段。container_id string代码解释器容器标识符。仅当 typecode_interpreter_call 时存在。用于关联同一会话中的多次代码执行。goal string抽取目标描述,说明需要从网页中提取哪些信息。仅当 typeweb_extractor_call 时存在。output string工具调用的输出结果,字符串格式。
  • typeweb_extractor_call 时为网页抽取的内容摘要
  • typeweb_search_image_callimage_search_call 时为 JSON 字符串,包含图片搜索结果数组,每个元素包含 title(图片标题)、url(图片 URL)和 index(序号)字段
  • typemcp_call 时为 MCP 服务返回的 JSON 字符串结果。
urls array被抽取的网页 URL 列表。仅当 typeweb_extractor_call 时存在。server_label stringMCP 服务标签。仅当 typemcp_call 时存在。标识本次调用所使用的 MCP 服务。queries array知识库检索使用的查询列表。仅当 typefile_search_call 时存在。数组元素为字符串,表示模型生成的搜索查询词。results array知识库检索结果数组。仅当 typefile_search_call 时存在。
file_id string匹配文档的文件 ID。filename string匹配文档的文件名。score float匹配相关度评分,取值范围 0-1,值越大表示相关度越高。text string匹配到的文档内容片段。
usage object本次请求的 Token 消耗信息。
input_tokens integer输入的 Token 数。补充说明output_tokens integer模型输出的 Token 数。total_tokens integer消耗的总 Token 数,为 input_tokens 与 output_tokens 的总和。input_tokens_details object输入 Token 的细粒度分类。
cached_tokens integer命中缓存的 Token 数。详情请参见上下文缓存
output_tokens_details object输出 Token 的细粒度分类。
reasoning_tokens integer思考过程 Token 数。
x_details array本次请求的计费明细数组。比顶级 usage 字段提供更细粒度的多模态 Token 拆分。
input_tokens integer输入的 Token 数。补充说明output_tokens integer模型输出的 Token 数。total_tokens integer消耗的总 Token 数,为 input_tokens 与 output_tokens 的总和。x_billing_type string固定为response_apiimage_tokens integer图像输入的 Token 数。包含图像输入时返回,等同于 input_tokens_details.image_tokensinput_tokens_details object输入 Token 的细粒度分类。多模态输入时返回,目前仅区分 text_tokensimage_tokens,不返回视频/音频 Token 拆分。
text_tokens integer文本输入的 Token 数。image_tokens integer图像输入的 Token 数。
output_tokens_details object输出 Token 的细粒度分类。比顶级 output_tokens_detailstext_tokens 字段(多模态输入时返回)。
reasoning_tokens integer思考过程 Token 数。text_tokens integer文本输出的 Token 数。多模态输入时返回。
plugins object内置工具调用统计。使用内置工具(如 web_search)时返回,与顶级 x_tools 字段内容相同。
web_search object联网搜索调用统计。
count integer本次响应中联网搜索的调用次数。
input_tokens_details object输入 Token 的缓存详情。启用 Session 缓存后返回;含图像输入但未命中缓存时可能返回空对象。
cached_tokens integer命中缓存的 Token 数。cache_creation_input_tokens integer本次请求新创建缓存的 Token 数。cache_creation object缓存创建详情。
ephemeral_5m_input_tokens integer5 分钟临时缓存新创建的 Token 数。
cache_type string缓存类型,固定为ephemeral
x_tools object工具使用统计信息。当使用内置工具时,包含各工具的调用次数。示例:{"web_search": {"count": 1}}
error object当模型生成响应失败时返回的错误对象。成功时为 nulltools array回显请求中 tools 参数的完整内容,结构与请求体中的 tools 参数相同。tool_choice string回显请求中 tool_choice 参数的值,枚举值为 autononerequired
{
    "created_at": 1771165743,
    "id": "c9f9c06b-032d-4525-a422-ac8ab5eccxxx",
    "model": "qwen3.8-max",
    "object": "response",
    "output": [
        {
            "content": [
                {
                    "annotations": [],
                    "text": "你好!我是 Qwen3.5,阿里巴巴最新推出的通义千问大语言模型,具备强大的语言理解、逻辑推理、代码生成及多模态处理能力,旨在为用户提供精准高效的智能服务。",
                    "type": "output_text"
                }
            ],
            "id": "msg_544b2907-e88e-40d2-9a83-c30d6d1f9xxx",
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": false,
    "status": "completed",
    "tool_choice": "auto",
    "tools": [],
    "usage": {
        "input_tokens": 55,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 43,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 98,
        "x_details": [
            {
                "input_tokens": 55,
                "output_tokens": 43,
                "total_tokens": 98,
                "x_billing_type": "response_api"
            }
        ]
    }
}

Response 响应 chunk 对象(流式输出)

流式输出返回一系列 JSON 对象。每个对象包含 type 字段标识事件类型,sequence_number 字段标识事件顺序。response.completed 事件标志着流式传输的结束。type string事件类型标识符。枚举值:
  • response.created:响应创建时触发,状态为 queued
  • response.in_progress:响应开始处理时触发,状态变为 in_progress
  • response.output_item.added:新的输出项(如 message、web_extractor_call)被添加到 output 数组时触发。当 item.typeweb_extractor_call 时,表示网页抽取工具调用开始。
  • response.content_part.added:输出项的 content 数组中新增内容块时触发。
  • response.output_text.delta:增量文本生成时触发,多次触发,delta 字段包含新增文本片段。
  • response.output_text.done:文本生成完成时触发,text 字段包含完整文本。
  • response.content_part.done:内容块完成时触发,part 对象包含完整内容块。
  • response.output_item.done:输出项生成完成时触发,item 对象包含完整输出项。当 item.typeweb_extractor_call 时,表示网页抽取工具调用完成。
  • response.reasoning_text.delta:(开启思考模式时)推理摘要增量文本,delta 字段包含新增摘要片段。
  • response.reasoning_text.done:(开启思考模式时)推理摘要完成,text 字段包含完整摘要。
  • response.custom_tool_call_input.delta:自定义工具增量文本
  • response.custom_tool_call_input.done:自定义工具完成
  • response.web_search_call.in_progress / searching / completed:(使用 web_search 工具时)搜索状态变化事件。
  • response.code_interpreter_call.in_progress / interpreting / completed:(使用 code_interpreter 工具时)代码执行状态变化事件。
  • 注意:使用 web_extractor 工具时,没有专门的事件类型标识符。网页抽取工具调用通过通用的 response.output_item.addedresponse.output_item.done 事件传递,通过 item.type 字段(值为 web_extractor_call)来识别。
  • response.incomplete:响应因 max_output_tokens等限制而提前结束
  • response.mcp_call_arguments.delta / response.mcp_call_arguments.done:(使用 mcp 工具时)MCP 调用参数的增量和完成事件。
  • response.mcp_call.in_progress:MCP 服务调用中。
  • response.mcp_call.completed:(使用 mcp 工具时)MCP 服务调用完成。
  • response.file_search_call.in_progress / searching / completed:(使用 file_search 工具时)知识库搜索状态变化事件。
  • 注意:使用 web_search_imageimage_search 工具时,没有专门的中间状态事件。工具调用通过 response.output_item.added(调用开始)和 response.output_item.done(调用完成)事件传递。
  • response.completed:响应生成完成时触发,response 对象包含完整响应(含 usage)。此事件标志流式传输结束。
sequence_number integer事件序列号,从 0 开始递增。用于确保客户端按正确顺序处理事件。response object响应对象。出现在 response.createdresponse.in_progressresponse.completed 事件中。在 response.completed 事件中包含完整的响应数据(包括 outputusage),其结构与非流式响应的 Response 对象一致。item object输出项对象。出现在 response.output_item.addedresponse.output_item.done 事件中。在 added 事件中为初始骨架(content 为空数组),在 done 事件中为完整对象。
id string输出项的唯一标识符(如 msg_xxx)。type string输出项类型。枚举值:message(消息)、reasoning(推理)、web_search_call(搜索)、web_search_image_call(文搜图)、image_search_call(图搜图)、mcp_call(MCP 调用)、file_search_call(知识库搜索)。role string消息角色,固定为 assistant。仅当 type 为 message 时存在。status string生成状态。在 added 事件中为 in_progress,在 done 事件中为 completedcontent array消息内容数组。在 added 事件中为空数组 [],在 done 事件中包含完整的内容块对象(结构与 part 对象相同)。
part object内容块对象。出现在 response.content_part.addedresponse.content_part.done 事件中。
type string内容块类型,固定为 output_texttext string文本内容。在 added 事件中为空字符串,在 done 事件中为完整文本。annotations array文本注释数组。通常为空数组。logprobs object | nullToken 的对数概率信息。当前固定返回 null
delta string增量文本内容。出现在 response.output_text.delta 事件中,包含本次新增的文本片段。客户端应将所有 delta 拼接以获得完整文本。text string完整文本内容。出现在 response.output_text.done 事件中,包含该内容块的完整文本,可用于校验 delta 拼接结果。item_id string输出项的唯一标识符。用于关联同一输出项的相关事件。output_index integer输出项在 output 数组中的索引位置。content_index integer内容块在 content 数组中的索引位置。
// response.created - 响应创建
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"object":"response","status":"queued",...},"sequence_number":0,"type":"response.created"}

// response.in_progress - 响应进行中
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","status":"in_progress",...},"sequence_number":1,"type":"response.in_progress"}

// response.output_item.added - 新增输出项
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[],"role":"assistant","status":"in_progress","type":"message"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"}

// response.content_part.added - 新增内容块
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"","type":"output_text","logprobs":null},"sequence_number":3,"type":"response.content_part.added"}

// response.output_text.delta - 增量文本(多次触发)
{"content_index":0,"delta":"人工智能","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}
{"content_index":0,"delta":"(Artificial Intelligence,","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":6,"type":"response.output_text.delta"}

// response.output_text.done - 文本完成
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":53,"text":"人工智能(Artificial Intelligence,简称 AI)是指由计算机系统模拟人类智能行为的技术和科学...","type":"response.output_text.done"}

// response.content_part.done - 内容块完成
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"...完整文本...","type":"output_text","logprobs":null},"sequence_number":54,"type":"response.content_part.done"}

// response.output_item.done - 输出项完成
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[{"annotations":[],"text":"...完整文本...","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"},"output_index":0,"sequence_number":55,"type":"response.output_item.done"}

// response.completed - 响应完成(包含完整响应和 usage)
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"model":"qwen3.7-max","object":"response","output":[...],"status":"completed","usage":{"input_tokens":37,"output_tokens":243,"total_tokens":280,...}},"sequence_number":56,"type":"response.completed"}

常见问题

Q:如何传递多轮对话的上下文? A:在发起新一轮对话请求时,请将上一轮模型响应成功返回的id作为 previous_response_id 参数传入。 Q:为什么响应示例中的某些字段未在本文说明? A:如果使用OpenAI的官方SDK,它可能会根据其自身的模型结构输出一些额外的字段(通常为null)。这些字段是OpenAI协议本身定义的,我们的服务当前不支持,所以它们为空值。只需关注本文档中描述的字段即可。