通过兼容 OpenAI 格式的 Responses API 调用千问模型,查看输入输出参数说明及调用示例。
相较于OpenAI Chat Completions API 的优势:
本 API 在接口设计上兼容 OpenAI,以降低开发者迁移成本,但在参数、功能和具体行为上存在差异。
核心原则:请求将仅处理本文档明确列出的参数,任何未提及的 OpenAI 参数都会被忽略。
以下是几个关键的差异点,以帮助您快速适配:
调用时请将
Q:如何传递多轮对话的上下文?
A:在发起新一轮对话请求时,请将上一轮模型响应成功返回的
- 内置工具:内置联网搜索、网页抓取、代码解释器、文搜图、图搜图、知识库搜索等工具,可在处理复杂任务时获得更优效果,详情参考工具调用。
- 更灵活的输入:支持直接传入字符串作为模型输入,也兼容 Chat 格式的消息数组。
- 简化上下文管理:通过传递上一轮响应的
previous_response_id,无需手动构建完整的消息历史数组。 - 便捷的上下文缓存:只需在请求头中添加
x-dashscope-session-cache: enable(默认值为 disable),服务端即可自动缓存对话上下文,无需改动业务代码即可降低多轮对话的推理延迟与成本,详情参考Session 缓存。
兼容性说明与限制
本 API 在接口设计上兼容 OpenAI,以降低开发者迁移成本,但在参数、功能和具体行为上存在差异。
核心原则:请求将仅处理本文档明确列出的参数,任何未提及的 OpenAI 参数都会被忽略。
以下是几个关键的差异点,以帮助您快速适配:
- 部分参数不支持:不支持部分 OpenAI Responses API 参数,例如异步执行参数
background(当前仅支持同步调用)等。 - 思考强度控制:通过
reasoning.effort参数控制模型的思考强度,具体用法请参考相应参数的说明。
- 华北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。
请求体modelstring (必选)模型名称。
支持的模型
qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3-max、qwen3-max-2026-01-23、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.8-2.4t-a95b、qwen3.8-27b、qwen3.6-35b-a3b、qwen3.5-397b-a17b、qwen3.5-122b-a10b、qwen3.5-27b、qwen3.5-35b-a3b、qwen-plus、qwen-flash、qwen3-coder-plus、qwen3-coder-flash、qwen3.5-ocr、qwen-plus-character、qwen-flash-character、deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash、deepseek-v4-flash-0731、glm-5.2string 或 array (必选)模型输入,支持以下格式:
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;role 为 assistant 时,array 元素类型为 output_text。当前 Responses API 暂不支持传入视频或语音,您可以通过Chat Completions API或DashScope API传入。
content 数组元素 type string (必选)可选值:input_text(文本输入)、input_image(图片输入,仅 user 角色)、input_file(文件输入,仅 user 角色,支持 PDF 和图片)、output_text(助手回复,仅 assistant 角色)。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 文件(最大 10 页、100 MB)和图片文件(最大 20 MB)。目前仅 qwen3.5-ocr 支持此类型。string (可选)固定为 message。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 (可选)标注信息。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。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。object (可选)模型的思考内容。可直接将上一轮响应的 output 中的 reasoning 项传回 input,用于在多轮对话中传递思考内容。
属性 type string (必选)固定为 reasoning。id string (必选)思考内容的唯一标识,来自上一轮响应。summary array (必选)思考摘要内容。
属性 type string (必选)固定为 summary_text。text string (必选)摘要文本。string (可选)状态,可选值:in_progress、completed、incomplete。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。string (可选)作为系统指令插入到上下文的起始位置。使用 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是否储存本次会话生成的模型响应。
array (可选)模型在生成响应时可调用的工具数组。支持内置工具和自定义 function 工具,可混合使用。为了获得最佳回复效果,建议同时开启
属性 web_search联网搜索工具,允许模型搜索互联网上的最新信息。相关文档:联网搜索
属性 type string (必选)固定为web_search。使用示例:[{"type": "web_search"}]web_search工具一起使用。qwen3-max、qwen3-max-2026-01-23需要同时开启思考模式。相关文档:网页抓取
属性 type string (必选)固定为web_extractor。使用示例:[{"type": "web_search"}, {"type": "web_extractor"}]qwen3.8-max、qwen3.8-flash、qwen3-max、qwen3-max-2026-01-23、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08需要同时开启思考模式。相关文档:代码解释器
属性 type string (必选)固定为code_interpreter。使用示例:[{"type": "code_interpreter"}]
属性 type string (必选)固定为web_search_image。使用示例:[{"type": "web_search_image"}]
属性 type string (必选)固定为image_search。使用示例:[{"type": "image_search"}]
属性 type string (必选)固定为file_search。vector_store_ids array(必选)要检索的知识库 ID。当前仅支持传入一个知识库 ID。使用示例:[{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
属性 type string (必选)固定为mcp。server_protocol string (必选)与 MCP 服务的通信协议,如 "sse"server_label string (必选)服务标签,用于标识该 MCP 服务。server_description string (可选)服务描述,帮助模型理解其功能与适用场景。server_url string (必选)MCP 服务端点的 URL。headers object (可选)请求头,用于携带身份验证等信息,如 Authorization。使用示例:function_call 类型的输出。相关文档:Function Calling
属性 type string (必选)必须设置为function。namestring(必选)工具名称。仅允许字母、数字、下划线(_)和短划线(-),最长 64 个 Token。descriptionstring(必选)工具描述信息,帮助模型判断何时以及如何调用该工具。parameters object (可选)工具的参数描述,需要是一个合法的 JSON Schema。若parameters参数为空,表示该工具没有入参(如时间查询工具)。
为提高工具调用的准确性,建议传入 使用示例:string or object (可选)默认值为 auto控制模型如何选择和调用工具。此参数支持两种赋值格式:字符串模式和对象模式。字符串模式
属性 mode string (必选)
array(必选)一个包含工具定义的列表,模型将被允许调用这些工具。string (必选)允许的工具配置类型,固定为 allowed_tools。float(可选)采样温度,控制模型生成文本的多样性。temperature越高,生成的文本更多样,反之,生成的文本更确定。取值范围: [0, 2)temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述。top_pfloat(可选)核采样的概率阈值,控制模型生成文本的多样性。top_p越高,生成的文本更多样。反之,生成的文本更确定。取值范围:(0,1.0]temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述。enable_thinking boolean (可选)是否开启思考模式。开启后,模型会在回复前进行思考,思考内容将通过 reasoning 类型的输出项返回。开启思考模式时,建议开启内置工具,以在处理复杂任务时获得最佳的模型效果。可选值:
该参数非OpenAI标准参数。Python SDK 通过reasoning object (可选)控制模型的思考强度。模型会在回复前进行思考,思考内容将通过 reasoning 类型的输出项返回。
属性 effort string (可选):思考强度档位,默认值为 xhigh。支持 none、minimal、low、medium、high、xhigh、max 共 7 个递增档位。降低该值可加快响应速度并减少推理 Token 的消耗。仅华北2(北京)和新加坡支持 ocr_options object (可选)OCR 定制任务参数。仅适用于 qwen3.5-ocr 模型。通过此参数可调用内置的 OCR 任务(如信息抽取、文字定位等),定制任务结果通过响应中的 ocr_result 字段返回。该参数非 OpenAI 标准参数。Python SDK 通过max_output_tokens integer(可选)
incomplete。 |
Python |
Response 响应对象(非流式输出)idstring本次响应的唯一标识符,为 UUID 格式的字符串,有效期为7天。可用于 previous_response_id 参数以创建多轮对话。created_at integer本次请求的 Unix 时间戳(秒)。object string对象类型,固定为 response。status string响应生成的状态。枚举值:
string用于生成响应的模型 ID。output array模型生成的输出项数组。数组中的元素类型和顺序取决于模型的响应。
数组元素属性 type string输出项类型。枚举值:
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 内容:
string函数调用的唯一标识符。仅当 type 为 function_call 时存在。在返回函数调用结果时,需要通过此 ID 关联请求与响应。content array消息内容数组。仅当 type 为 message 时存在。
数组元素属性 type string内容类型,固定为 output_text。text string模型生成的文本内容。annotations array文本注释数组。通常为空数组。array推理摘要数组。仅当 type 为 reasoning 时存在。每个元素包含 type(值为 summary_text)和 text(摘要文本)字段。action object搜索动作信息。仅当 type 为 web_search_call 时存在。
属性 query string搜索查询关键词。type string搜索类型,固定为 search。sources array搜索来源列表。每个元素包含 type和 url字段。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工具调用的输出结果,字符串格式。
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匹配到的文档内容片段。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 数。详情请参见上下文缓存。object输出 Token 的细粒度分类。
属性 reasoning_tokens integer思考过程 Token 数。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 的细粒度分类。多模态输入时返回,目前仅区分 text_tokens 与 image_tokens,不返回视频/音频 Token 拆分。
属性 text_tokens integer文本输入的 Token 数。image_tokens integer图像输入的 Token 数。object输出 Token 的细粒度分类。比顶级 output_tokens_details 多 text_tokens 字段(多模态输入时返回)。
属性 reasoning_tokens integer思考过程 Token 数。text_tokens integer文本输出的 Token 数。多模态输入时返回。object内置工具调用统计。使用内置工具(如 web_search)时返回,与顶级 x_tools 字段内容相同。
属性 web_search object联网搜索调用统计。
属性 count integer本次响应中联网搜索的调用次数。object输入 Token 的缓存详情。启用 Session 缓存后返回;含图像输入但未命中缓存时可能返回空对象。
属性 cached_tokens integer命中缓存的 Token 数。cache_creation_input_tokens integer本次请求新创建缓存的 Token 数。cache_creation object缓存创建详情。
属性 ephemeral_5m_input_tokens integer5 分钟临时缓存新创建的 Token 数。string缓存类型,固定为ephemeral。object工具使用统计信息。当使用内置工具时,包含各工具的调用次数。示例:{"web_search": {"count": 1}}object当模型生成响应失败时返回的错误对象。成功时为 null。tools array回显请求中 tools 参数的完整内容,结构与请求体中的 tools 参数相同。tool_choice string回显请求中 tool_choice 参数的值,枚举值为 auto、none、required。 |
Response 响应 chunk 对象(流式输出)流式输出返回一系列 JSON 对象。每个对象包含type 字段标识事件类型,sequence_number 字段标识事件顺序。response.completed 事件标志着流式传输的结束。type string事件类型标识符。枚举值:
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 对象相同)。object内容块对象。出现在 response.content_part.added 和 response.content_part.done 事件中。
属性 type string内容块类型,固定为 output_text。text string文本内容。在 added 事件中为空字符串,在 done 事件中为完整文本。annotations array文本注释数组。通常为空数组。logprobs object | nullToken 的对数概率信息。当前固定返回 null。string增量文本内容。出现在 response.output_text.delta 事件中,包含本次新增的文本片段。客户端应将所有 delta 拼接以获得完整文本。text string完整文本内容。出现在 response.output_text.done 事件中,包含该内容块的完整文本,可用于校验 delta 拼接结果。item_id string输出项的唯一标识符。用于关联同一输出项的相关事件。output_index integer输出项在 output 数组中的索引位置。content_index integer内容块在 content 数组中的索引位置。 |
常见问题
Q:如何传递多轮对话的上下文?
A:在发起新一轮对话请求时,请将上一轮模型响应成功返回的id作为 previous_response_id 参数传入。
Q:为什么响应示例中的某些字段未在本文说明?
A:如果使用OpenAI的官方SDK,它可能会根据其自身的模型结构输出一些额外的字段(通常为null)。这些字段是OpenAI协议本身定义的,我们的服务当前不支持,所以它们为空值。只需关注本文档中描述的字段即可。