Skip to main content

创建响应

通过兼容 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 参数控制模型的思考强度,具体用法请参考相应参数的说明。
  • 上下文限制:为预留内置工具调用与推理生成空间,Responses API 的最大输入上下文约为模型窗口大小的 80%(预留约 20% 缓冲区),超出部分将自动触发截断,不会报错中断。
  • 华北2(北京)
  • 新加坡
  • 美国(弗吉尼亚)
  • 德国(法兰克福)
  • 日本(东京)
  • 中国香港
SDK 调用配置的base_url:https://{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 (必选)模型名称。
qwen3.8-max、qwen3.8-max-0902、qwen3.8-flash、qwen3.8-2.4t-a95b、qwen3.8-27b、qwen3.8-omni-flash、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3.7-max-2026-05-17、qwen3.7-max-preview、qwen3.7-plus、qwen3.7-plus-2026-05-26、qwen3.6-plus、qwen3.6-plus-2026-04-02、qwen3.5-plus、qwen3.5-plus-2026-04-20、qwen3.5-plus-2026-02-15、qwen3.7-flash、qwen3.7-flash-2026-07-15、qwen3.6-flash、qwen3.6-flash-2026-04-16、qwen3.5-flash、qwen3.5-flash-2026-02-23、qwen3.6-35b-a3b、qwen3.5-397b-a17b、qwen3.5-122b-a10b、qwen3.5-27b、qwen3.5-35b-a3b、deepseek-v4.1-flash、deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash-0731、glm-5.3、glm-5.2、kimi-k3
非列表中阿里云百炼直供文本生成模型仅支持基础兼容能力,Agent 能力(内置工具等)受限。
input string 或 array (必选)模型输入,支持以下格式:
  • string:纯文本,如 "你好"。
  • array:消息数组,按对话顺序排列。
EasyInputMessage object通过 role 区分消息类型,通过content传递消息内容。
role string (必选)消息角色,可选值:user、assistant、system、developer。content string 或 array (必选)消息内容。若输入为纯文本,则为 string 类型;若输入为结构化内容数组,则为 array 类型。role 为 system/developer 时,array 元素类型为 input_text;role 为 user 时,array 元素类型为 input_text、input_image 或 input_file,qwen3.8-omni-flash 还支持下文所述的 input_audio 和 input_video;role 为 assistant 时,array 元素类型为 output_text。
type string (必选)内容类型。可选值:input_text(文本输入)、input_image(图片输入,仅 user 角色)、input_file(文件输入,仅 user 角色,支持 PDF 和图片)、output_text(助手回复,仅 assistant 角色)。qwen3.8-omni-flash 的 user 消息还支持 input_audio 和 input_video,字段说明见下文。text string文本内容。当 type 为 input_text 或 output_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 文件(最大 100 MB)和图片文件(最大 20 MB)。目前仅 qwen3.5-ocr 支持此类型。PDF 的页数上限取决于 ocr_options 中的 task:设置为 document_parsing 时最大 50 页;未设置 task 或设置为其他任务时,最大 10 页。音视频输入字段以下 input_audio、input_video 类型仅适用于 qwen3.8-omni-flash 的 user 消息。字段直接放在 content 数组元素中:
type字段说明
input_audioformat、audio_url 或 dataformat 必填,例如 wav 或 mp3。audio_url 为音频 URL,data 为包含 MIME 类型前缀和 Base64 编码音频的完整 Data URI,例如 data:audio/wav;base64,UklGR...,两者必须二选一,不能同时传入。
input_videovideo_url、fpsvideo_url 必填,传入视频 URL。fps 为可选的数字类型(number)抽帧参数,表示每秒抽取的帧数,例如 2 表示每秒抽取 2 帧,不要传字符串。
use_multichannel boolean(可选),默认 false。设为 true 时,对双通道或四通道音频进行空间音频解析;设为 false 时,按单通道音频解析。在 type="input_audio" 的 content 数组元素中传入,与 type、audio_url、format 同级。音视频输入沿用普通文本响应格式和流式事件,流式文本使用 response.output_text.delta、response.output_text.done。音视频输入、文本输出示例见Qwen3.8-Omni-Flash。
type string (可选)固定为 message。
ResponseOutputMessage object (可选)模型的输出消息对象。可直接将上一轮响应的 output 中的 message 项传回 input,用于多轮对话场景。与 EasyInputMessage 的区别在于它携带了完整的输出结构(含 id、status 和结构化 content)。
type string (必选)固定为 message。id string (必选)输出消息的唯一标识,来自上一轮响应。role string (必选)固定为 assistant。status string (必选)消息状态,可选值:in_progress、completed、incomplete。content array (必选)内容数组,元素为 output_text 类型对象。
type string (必选)固定为 output_text。text string (必选)回复文本。annotations array (可选)标注信息。
Function Call object (可选)模型决定调用外部工具时生成的结构化指令。
type string (必选)固定为 function_call。id string (可选)Function Call 的唯一标识,来自上一轮响应。name string (必选)工具函数名称。arguments string (必选)工具调用参数,JSON 字符串格式。call_id string (必选)工具调用的标识符,需与模型返回的 call_id 一致。status string (可选)状态,可选值:in_progress、completed、incomplete。
Function Call Output object (可选)工具调用的输出结果。在消息列表中必须紧跟对应的 function_call 消息,否则会报错。
type string (必选)固定为 function_call_output。id string (可选)Function Call Output 的唯一标识。call_id string (必选)工具调用的标识符,需与模型返回的 call_id 一致。output string (必选)工具函数的执行结果。status string (可选)状态,可选值:in_progress、completed、incomplete。
Reasoning object (可选)模型的思考内容。可直接将上一轮响应的 output 中的 reasoning 项传回 input,用于在多轮对话中传递思考内容。
type string (必选)固定为 reasoning。id string (必选)思考内容的唯一标识,来自上一轮响应。summary array (必选)思考摘要内容。
type string (必选)固定为 summary_text。text string (必选)摘要文本。
status string (可选)状态,可选值:in_progress、completed、incomplete。
Web Search Call object (可选)搜索调用对象。可直接将上一轮响应的 output 中的 web_search_call 项传回 input,用于在多轮对话中传递搜索结果上下文。
type string (必选)固定为 web_search_call。id string (必选)搜索调用的唯一标识,来自上一轮响应。status string (必选)搜索状态,可选值:in_progress、searching、completed、failed。action object (必选)搜索信息。仅支持 search 类型。
type string (必选)搜索类型,固定为 search。queries array (可选)搜索查询词列表,元素类型为 string。sources array (可选)搜索结果来源列表。
type string (必选)来源类型,固定为 url。url 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 工具,可混合使用。qwen3.8-omni-flash 的内置工具仅支持 web_search,同时支持自定义 function 工具。
web_search联网搜索工具,允许模型搜索互联网上的最新信息。相关文档:联网搜索
type string (必选)固定为web_search。使用示例:[{"type": "web_search"}]
web_extractor网页抽取工具,允许模型访问并提取网页内容。当前必须配合web_search工具一起使用。相关文档:网页抓取
type string (必选)固定为web_extractor。使用示例:[{"type": "web_search"}, {"type": "web_extractor"}]
code_interpreter代码解释器工具,允许模型执行代码并返回结果,支持数据分析。qwen3.8-max、qwen3.8-max-0902、qwen3.8-flash、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.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_search。vector_store_ids array(必选)要检索的知识库 ID。当前仅支持传入一个知识库 ID。使用示例:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
MCP调用通过 MCP(Model Context Protocol)调用外部服务,相关文档:MCP
type string (必选)固定为mcp。server_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 (必选)必须设置为function。namestring(必选)工具名称。仅允许字母、数字、下划线(_)和短划线(-),最长 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 (可选):思考强度档位。支持 none、minimal、low、medium、high、xhigh、max 共 7 个递增档位。降低该值可加快响应速度并减少推理 Token 的消耗。
模型默认值支持的档位其余档位的映射
qwen3.8-max、qwen3.8-max-0902、qwen3.8-flash、qwen3.8-2.4t-a95b、qwen3.8-27bxhighnone、low、medium、xhighminimal 映射为 low,high 和 max 映射为 xhigh
deepseek-v4-flash-0731、deepseek-v4-pro-0813highnone、low、high、maxminimal 映射为 low,medium 映射为 high,xhigh 映射为 max
deepseek-v4.1-flashhighnone、low、high、maxminimal 映射为 low,medium 和 xhigh 映射为 high,传入 ultra 会返回错误
glm-5.3maxlow、high、maxminimal 映射为 low,medium 映射为 high,xhigh 映射为 max
glm-5.2、deepseek-v4-prohighnone、high、maxminimal、low 和 medium 映射为 high,xhigh 映射为 max
glm-5.3 推荐使用 max 档位。
reasoning.effort 的优先级高于 enable_thinking,建议优先使用 reasoning.effort,enable_thinking 后续将不再支持。
本页所列的 Qwen3.8 系列,Qwen3.7、Qwen3.6、Qwen3.5、Qwen3-Max、DeepSeek、GLM 和 Kimi 型号通过 reasoning.effort 控制思考强度,不支持使用 thinking_budget 控制最大思考长度。
ocr_options object (可选)OCR 定制任务参数。仅适用于 qwen3.5-ocr 模型。通过此参数可调用内置的 OCR 任务(如信息抽取、文字定位等),定制任务结果通过响应中的 ocr_result 字段返回。解析 PDF 文件时,task 的取值决定支持的页数:设置为 document_parsing 时最大 50 页;未设置 task 或设置为其他任务时,最大 10 页。
该参数非 OpenAI 标准参数。Python SDK 通过 extra_body={"ocr_options": {...}} 传递;Node.js SDK 和 curl 直接使用 ocr_options 作为顶层参数。
max_output_tokens integer(可选)限制生成输出的 Token 数量。
  • Qwen3.8 系列:模型回复内容和思维链内容之和的最大Token数。
  • Qwen3.7、Qwen3.6、Qwen3.5、Qwen3-Max、DeepSeek、GLM 和 Kimi:模型回复内容的最大Token数。
上述型号的最小值为16。生成的 Token 数达到所设置的上限时,生成将提前停止,状态为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对象类型,固定为 response。status 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。仅当 type 为 message 时存在。status string输出项状态。可选值:completed(完成)、in_progress(生成中)。当 type 不为reasoning时存在。name string工具或函数名称。当 type 为 function_call、web_search_image_call、image_search_call、mcp_call 时存在。对于 web_search_image_call 和 image_search_call,值分别固定为 "web_search_image" 和 "image_search"。对于 mcp_call,值为 MCP 服务中被调用的具体函数名(如 amap-maps-maps_geo)。arguments string工具调用的参数,JSON 字符串格式。当 type 为 function_call、web_search_image_call、image_search_call、mcp_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函数调用的唯一标识符。仅当 type 为 function_call 时存在。在返回函数调用结果时,需要通过此 ID 关联请求与响应。content array消息内容数组。仅当 type 为 message 时存在。
type string内容类型,固定为 output_text。text string模型生成的文本内容。annotations array文本注释数组。通常为空数组。
summary array推理摘要数组。仅当 type 为 reasoning 时存在。每个元素包含 type(值为 summary_text)和 text(摘要文本)字段。action object搜索动作信息。仅当 type 为 web_search_call 时存在。
query string搜索查询关键词。type string搜索类型,固定为 search。sources array搜索来源列表。每个元素包含 type和 url字段。
code string模型生成并执行的代码。仅当 type 为 code_interpreter_call 时存在。outputs array代码执行输出数组。仅当 type 为 code_interpreter_call 时存在。每个元素包含 type(值为 logs)和 logs(代码执行日志)字段。container_id string代码解释器容器标识符。仅当 type 为 code_interpreter_call 时存在。用于关联同一会话中的多次代码执行。goal string抽取目标描述,说明需要从网页中提取哪些信息。仅当 type 为 web_extractor_call 时存在。output string工具调用的输出结果,字符串格式。
  • 当 type 为 web_extractor_call 时为网页抽取的内容摘要
  • 当 type 为 web_search_image_call 或 image_search_call 时为 JSON 字符串,包含图片搜索结果数组,每个元素包含 title(图片标题)、url(图片 URL)和 index(序号)字段
  • 当 type 为 mcp_call 时为 MCP 服务返回的 JSON 字符串结果。
urls array被抽取的网页 URL 列表。仅当 type 为 web_extractor_call 时存在。server_label stringMCP 服务标签。仅当 type 为 mcp_call 时存在。标识本次调用所使用的 MCP 服务。queries array知识库检索使用的查询列表。仅当 type 为 file_search_call 时存在。数组元素为字符串,表示模型生成的搜索查询词。results array知识库检索结果数组。仅当 type 为 file_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_api。image_tokens integer图像输入的 Token 数。包含图像输入时返回,等同于 input_tokens_details.image_tokens。input_tokens_details object输入 Token 的细粒度分类,返回字段取决于模型和输入模态。qwen3.8-omni-flash 的音频输入可返回 audio_tokens。
text_tokens integer文本输入的 Token 数。image_tokens integer图像输入的 Token 数。audio_tokens integer音频输入的 Token 数,完整路径为 usage.x_details[].input_tokens_details.audio_tokens。可选字段,是否返回取决于模型及输入。
output_tokens_details object输出 Token 的细粒度分类。比顶级 output_tokens_details 多 text_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当模型生成响应失败时返回的错误对象。成功时为 null。tools array回显请求中 tools 参数的完整内容,结构与请求体中的 tools 参数相同。tool_choice string回显请求中 tool_choice 参数的值,枚举值为 auto、none、required。
{
    "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.type 为 web_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.type 为 web_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.added 和 response.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_image 和 image_search 工具时,没有专门的中间状态事件。工具调用通过 response.output_item.added(调用开始)和 response.output_item.done(调用完成)事件传递。
  • response.completed:响应生成完成时触发,response 对象包含完整响应(含 usage)。此事件标志流式传输结束。
sequence_number integer事件序列号,从 0 开始递增。用于确保客户端按正确顺序处理事件。response object响应对象。出现在 response.created、response.in_progress 和 response.completed 事件中。在 response.completed 事件中包含完整的响应数据(包括 output 和 usage),其结构与非流式响应的 Response 对象一致。item object输出项对象。出现在 response.output_item.added 和 response.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 事件中为 completed。content array消息内容数组。在 added 事件中为空数组 [],在 done 事件中包含完整的内容块对象(结构与 part 对象相同)。
part object内容块对象。出现在 response.content_part.added 和 response.content_part.done 事件中。
type string内容块类型,固定为 output_text。text 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协议本身定义的,我们的服务当前不支持,所以它们为空值。只需关注本文档中描述的字段即可。
图像生成
视频生成
世界模型
3D模型生成
音频
  • 音频生成
Realtime API
  • 概述
向量与排序
决策模型
TokenPlan
模型生产