通过兼容 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% 缓冲区),超出部分将自动触发截断,不会报错中断。
新加坡
SDK 调用配置的base_url:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
华北2(北京)
SDK 调用配置的base_url:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
美国(弗吉尼亚)
SDK 调用配置的base_url:https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
德国(法兰克福)
SDK 调用配置的base_url:https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
中国香港
SDK 调用配置的base_url:https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
日本(东京)
SDK 调用配置的base_url:https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
HTTP 请求地址:POST https://{WorkspaceId}.ap-northeast-1.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 - 中国香港地域:从
https://cn-hongkong.dashscope.aliyuncs.com迁移至https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。
重要OpenAI兼容-Responses API 的旧版URL路径 /api/v2/apps/protocols/compatible-mode/v1/responses 已经停止维护,将不再保证功能可用性,请尽快迁移至新版路径 /compatible-mode/v1/responses。
请求体model 模型名称。 支持的模型
重要非列表中阿里云百炼直供文本生成模型仅支持基础兼容能力,Agent 能力(内置工具等)受限。 input 模型输入,支持以下格式:
array 输入项类型 EasyInputMessage 通过 role 区分消息类型,通过content传递消息内容。 属性 role 消息角色,可选值: content 消息内容,支持以下格式:
array 元素类型 以下类型之一: input_text 文本输入。 属性 type 固定为 text 输入模型的文本内容。 input_image 图片输入,仅 属性 type 固定为 image_url 图片的公网 URL 或 Base64 编码。Base64 请传入完整的 Data URI,例如: input_file 文件输入,仅 属性 type 固定为 file_url PDF 文件的公网 URL,文件最大 100 MB。 PDF 的页数上限取决于 input_audio 音频输入,仅适用于 属性 type 固定为 format 音频格式,例如 audio_url 音频的公网 URL。与 data 包含 MIME 类型前缀和 Base64 编码音频的完整 Data URI,例如: use_multichannel 是否对音频进行空间音频解析,默认 input_video 视频输入,仅适用于 属性 type 固定为 video_url 视频的公网 URL。 fps 抽帧频率,表示每秒抽取的帧数,例如 output_text 助手回复,仅 属性 type 固定为 text 助手回复的文本内容。 音视频输入沿用普通文本响应格式和流式事件,流式文本使用 type 固定为 ResponseOutputMessage 模型的输出消息对象。可直接将上一轮响应的 output 中的 message 项传回 input,用于多轮对话场景。与 EasyInputMessage 的区别在于它携带了完整的输出结构(含 id、status 和结构化 content)。 属性 type 固定为 id 输出消息的唯一标识,来自上一轮响应。 role 固定为 status 消息状态,可选值: content 内容数组,元素为 output_text 类型对象。 属性 type 固定为 text 回复文本。 annotations 标注信息。 Function Call 模型决定调用外部工具时生成的结构化指令。 属性 type 固定为 id Function Call 的唯一标识,来自上一轮响应。 name 工具函数名称。 arguments 工具调用参数,JSON 字符串格式。 call_id 工具调用的标识符,需与模型返回的 status 状态,可选值: Function Call Output 工具调用的输出结果。在消息列表中必须紧跟对应的 属性 type 固定为 id Function Call Output 的唯一标识。 call_id 工具调用的标识符,需与模型返回的 output 工具函数的执行结果。纯文本结果传入 string;需要模型理解工具产出的图片时传入 array,一个 output 中可包含多张图片。图片 URL 作为 string 传入时按普通文本处理,不会被解析为图片。 array 元素类型 以下类型之一,不支持 input_text 文本结果。 属性 type 固定为 text 文本内容。 input_image 图片结果。 属性 type 固定为 image_url 图片的公网 URL 或 Base64 编码。Base64 请传入完整的 Data URI,例如: status 状态,可选值: Reasoning 模型的思考内容。可直接将上一轮响应的 output 中的 reasoning 项传回 input,用于在多轮对话中传递思考内容。 属性 type 固定为 id 思考内容的唯一标识,来自上一轮响应。 summary 思考摘要内容。 属性 type 固定为 text 摘要文本。 status 状态,可选值: Web Search Call 搜索调用对象。可直接将上一轮响应的 output 中的 web_search_call 项传回 input,用于在多轮对话中传递搜索结果上下文。 属性 type 固定为 id 搜索调用的唯一标识,来自上一轮响应。 status 搜索状态,可选值: action 搜索信息。仅支持 属性 type 搜索类型,固定为 queries 搜索查询词列表,元素类型为 string。 sources 搜索结果来源列表。 属性 type 来源类型,固定为 url 来源 URL。 instructions 作为系统指令插入到上下文的起始位置。使用 previous_response_id 上一个响应的唯一 ID,当前响应 conversation 当前响应所属的会话(参考Conversations API)。会话中的历史项会自动作为上下文传入本次请求,本次请求的输入和输出也会在响应完成后自动添加到会话中。不能与 stream 是否开启流式输出。设置为 store 是否储存本次会话生成的模型响应。
tools 模型在生成响应时可调用的工具数组。支持内置工具和自定义 function 工具,可混合使用。
属性 web_search 联网搜索工具,允许模型搜索互联网上的最新信息。相关文档:联网搜索 属性 type 固定为 使用示例: 网页抽取工具,允许模型访问并提取网页内容。当前必须配合 属性 type 固定为 使用示例: 代码解释器工具,允许模型执行代码并返回结果,支持数据分析。 属性 type 固定为 使用示例: 根据文本描述搜索图片。相关文档:文搜图 属性 type 固定为 使用示例: 根据图片搜索相似或相关图片,输入中需要包含图片的URL。相关文档:图搜图 属性 type 固定为 使用示例: 在已上传或关联的知识库中搜索。相关文档:知识检索 属性 type 固定为 vector_store_ids 要检索的知识库 ID。当前仅支持传入一个知识库 ID。 使用示例: 通过 MCP(Model Context Protocol)调用外部服务,相关文档:MCP 属性 type 固定为 server_protocol 与 MCP 服务的通信协议,如 server_label 服务标签,用于标识该 MCP 服务。 server_description 服务描述,帮助模型理解其功能与适用场景。 server_url MCP 服务端点的 URL。 headers 请求头,用于携带身份验证等信息,如 使用示例: 自定义函数工具,允许模型调用您定义的函数。当模型判断需要调用工具时,响应会返回 属性 type 必须设置为 name 工具名称。仅允许字母、数字、下划线( description 工具描述信息,帮助模型判断何时以及如何调用该工具。 parameters 工具的参数描述,需要是一个合法的 JSON Schema。若
使用示例: tool_choice 控制模型如何选择和调用工具。此参数支持两种赋值格式:字符串模式和对象模式。 字符串模式
为模型设定可用的工具范围,仅限在预定义的工具列表中进行选择和调用。 属性 mode
tools 一个包含工具定义的列表,模型将被允许调用这些工具。 type 允许的工具配置类型,固定为 parallel_tool_calls 是否开启并行工具调用。相关文档:并行工具调用
可选值:
temperature 采样温度,控制模型生成文本的多样性。 temperature越高,生成的文本更多样,反之,生成的文本更确定。 取值范围: [0, 2) temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述。 top_p 核采样的概率阈值,控制模型生成文本的多样性。 top_p越高,生成的文本更多样。反之,生成的文本更确定。 取值范围:(0,1.0] temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。更多说明,请参见概述。 enable_thinking 是否开启思考模式。开启后,模型会在回复前进行思考,思考内容将通过 可选值:
不同模型的默认值:支持的模型
reasoning 控制模型的思考强度。模型会在回复前进行思考,思考内容将通过 属性 effort 支持
ocr_options OCR 定制任务参数。仅适用于 解析 PDF 文件时,
max_output_tokens 限制生成输出的 Token 数量。
上述型号的最小值为16。生成的 Token 数达到所设置的上限时,生成将提前停止,状态为 | 基础调用流式输出多轮对话调用内置工具自定义 Function Call工具返回多模态结果文档理解Session 缓存在请求 Header 中设置 自动生效的隐式缓存另见上下文缓存。 |
Response 响应对象(非流式输出)id 本次响应的唯一标识符,为 UUID 格式的字符串,有效期为7天。可用于 created_at 本次请求的 Unix 时间戳(秒)。 object 对象类型,固定为 status 响应生成的状态。枚举值:
model 用于生成响应的模型 ID。 output 模型生成的输出项数组。数组中的元素类型和顺序取决于模型的响应。 数组元素属性 type 输出项类型。枚举值:
id 输出项的唯一标识符。所有类型的输出项都包含此字段。 role 消息角色,固定为 status 输出项状态。可选值: name 工具或函数名称。当 对于 对于 arguments 工具调用的参数,JSON 字符串格式。当
call_id 函数调用的唯一标识符。仅当 content 消息内容数组。仅当 数组元素属性 type 内容类型,固定为 text 模型生成的文本内容。 annotations 文本注释数组。通常为空数组。 summary 推理摘要数组。仅当 action 搜索动作信息。仅当 属性 query 搜索查询关键词。 type 搜索类型,固定为 sources 搜索来源列表。每个元素包含 code 模型生成并执行的代码。仅当 outputs 代码执行输出数组。仅当 container_id 代码解释器容器标识符。仅当 goal 抽取目标描述,说明需要从网页中提取哪些信息。仅当 output 工具调用的输出结果,字符串格式。
urls 被抽取的网页 URL 列表。仅当 server_label MCP 服务标签。仅当 queries 知识库检索使用的查询列表。仅当 results 知识库检索结果数组。仅当 数组元素属性 file_id 匹配文档的文件 ID。 filename 匹配文档的文件名。 score 匹配相关度评分,取值范围 0-1,值越大表示相关度越高。 text 匹配到的文档内容片段。 usage 本次请求的 Token 消耗信息。 属性 input_tokens 输入的 Token 数。补充说明 output_tokens 模型输出的 Token 数。 total_tokens 消耗的总 Token 数,为 input_tokens 与 output_tokens 的总和。 input_tokens_details 输入 Token 的细粒度分类。 属性 cached_tokens 命中缓存的 Token 数。详情请参见上下文缓存。 output_tokens_details 输出 Token 的细粒度分类。 属性 reasoning_tokens 思考过程 Token 数。 x_details 本次请求的计费明细数组。比顶级 属性 input_tokens 输入的 Token 数。补充说明 output_tokens 模型输出的 Token 数。 total_tokens 消耗的总 Token 数,为 input_tokens 与 output_tokens 的总和。 x_billing_type 固定为 image_tokens 图像输入的 Token 数。包含图像输入时返回,等同于 input_tokens_details 输入 Token 的细粒度分类,返回字段取决于模型和输入模态。 属性 text_tokens 文本输入的 Token 数。 image_tokens 图像输入的 Token 数。 audio_tokens 音频输入的 Token 数,完整路径为 output_tokens_details 输出 Token 的细粒度分类。比顶级 属性 reasoning_tokens 思考过程 Token 数。 text_tokens 文本输出的 Token 数。多模态输入时返回。 plugins 内置工具调用统计。使用内置工具(如 属性 web_search 联网搜索调用统计。 属性 count 本次响应中联网搜索的调用次数。 input_tokens_details 输入 Token 的缓存详情。启用 Session 缓存后返回;含图像输入但未命中缓存时可能返回空对象。 属性 cached_tokens 命中缓存的 Token 数。 cache_creation_input_tokens 本次请求新创建缓存的 Token 数。 cache_creation 缓存创建详情。 属性 ephemeral_5m_input_tokens 5 分钟临时缓存新创建的 Token 数。 cache_type 缓存类型,固定为 x_tools 工具使用统计信息。当使用内置工具时,包含各工具的调用次数。 示例: error 当模型生成响应失败时返回的错误对象。成功时为 tools 回显请求中 tool_choice 回显请求中 | |
Response 响应 chunk 对象(流式输出)流式输出返回一系列 JSON 对象。每个对象包含 type 事件类型标识符。枚举值:
sequence_number 事件序列号,从 0 开始递增。用于确保客户端按正确顺序处理事件。 response 响应对象。出现在 item 输出项对象。出现在 属性 id 输出项的唯一标识符(如 type 输出项类型。枚举值: role 消息角色,固定为 status 生成状态。在 content 消息内容数组。在 part 内容块对象。出现在 属性 type 内容块类型,固定为 text 文本内容。在 annotations 文本注释数组。通常为空数组。 logprobs Token 的对数概率信息。当前固定返回 delta 增量文本内容。出现在 text 完整文本内容。出现在 item_id 输出项的唯一标识符。用于关联同一输出项的相关事件。 output_index 输出项在 content_index 内容块在 | |
常见问题
Q:如何传递多轮对话的上下文?A:在发起新一轮对话请求时,请将上一轮模型响应成功返回的id作为 previous_response_id 参数传入。
A:如果使用OpenAI的官方SDK,它可能会根据其自身的模型结构输出一些额外的字段(通常为null)。这些字段是OpenAI协议本身定义的,我们的服务当前不支持,所以它们为空值。只需关注本文档中描述的字段即可。