文本生成(Responses)
/api/v1/responsesHeader Parameters
使用 Bearer Token 认证。 格式: Authorization: Bearer sk-xxxxxx
Request Body
application/json
模型名称， 示例输入： gpt-5.3-chat gpt-5.3-codex
模型输入，支持以下格式：
string：纯文本，如 "你好"。
array：消息数组，按对话顺序排列。
作为系统指令插入到上下文的起始位置。使用 previous_response_id 时，上一轮指定的 instructions 不会传入本轮上下文。
上一个响应的唯一 ID，当前响应id有效期为7天。使用此参数可创建多轮对话，服务端会自动检索并组合该轮次的输入与输出作为上下文。当同时提供 input 消息数组和 previous_response_id 时，input 中的新消息会追加到历史上下文之后。不能与 conversation 同时使用。
当前响应所属的会话（参考Conversations API）。会话中的历史项会自动作为上下文传入本次请求，本次请求的输入和输出也会在响应完成后自动添加到会话中。不能与 previous_response_id 同时使用。
是否开启流式输出。默认值为 false，设置为 true 时，模型响应数据将实时流式返回给客户端。
是否储存本次会话生成的模型响应。默认值为 true
false：不储存，对话内容不能被 previous_response_id 和后续 API 使用。
true：储存，当前模型响应可被 previous_response_id 和后续 API 使用。
模型在生成响应时可调用的工具数组。支持内置工具和自定义 function 工具，可混合使用。
为了获得最佳回复效果，建议同时开启 code_interpreter、web_search 和 web_extractor 工具。
web_search
联网搜索工具，允许模型搜索互联网上的最新信息。相关文档：联网搜索
属性
type string （必选）
固定为web_search。
使用示例：[{"type": "web_search"}]
web_extractor
网页抽取工具，允许模型访问并提取网页内容。当前必须配合web_search工具一起使用。qwen3-max、qwen3-max-2026-01-23需要同时开启思考模式。相关文档：网页抓取
属性
code_interpreter
代码解释器工具，允许模型执行代码并返回结果，支持数据分析。qwen3-max、qwen3-max-2026-01-23需要同时开启思考模式。相关文档：代码解释器
属性
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://dashscope.aliyuncs.com/api/v1/mcps/amap-maps/sse", "headers": { "Authorization": "Bearer " } } 自定义工具 function
自定义函数工具，允许模型调用您定义的函数。当模型判断需要调用工具时，响应会返回 function_call 类型的输出。相关文档：Function Calling
属性
type string （必选）
必须设置为function。
name string （必选）
工具名称。仅允许字母、数字、下划线（_）和短划线（-），最长 64 个 Token。
description string （必选）
工具描述信息，帮助模型判断何时以及如何调用该工具。
parameters object （可选）
工具的参数描述，需要是一个合法的 JSON Schema。若parameters参数为空，表示该工具没有入参（如时间查询工具）。
为提高工具调用的准确性，建议传入 parameters。 使用示例：
[{ "type": "function", "name": "get_weather", "description": "获取指定城市的天气信息", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称" } }, "required": ["city"] } }]
控制模型如何选择和调用工具。此参数支持两种赋值格式：字符串模式和对象模式。
采样温度，控制模型生成文本的多样性。
temperature越高，生成的文本更多样，反之，生成的文本更确定。
取值范围： [0, 2)
temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。
核采样的概率阈值，控制模型生成文本的多样性。
top_p越高，生成的文本更多样。反之，生成的文本更确定。
取值范围：（0,1.0]
temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。
是否开启思考模式。开启后，模型会在回复前进行思考，思考内容将通过 reasoning 类型的输出项返回。开启思考模式时，建议开启内置工具，以在处理复杂任务时获得最佳的模型效果。
可选值：
true：开启
false：不开启
控制模型的思考强度。模型会在回复前进行思考，思考内容将通过 reasoning 类型的输出项返回。
思考强度档位，默认值为 medium。
none：关闭思考，直接回答
minimal：最小化思考，最快速响应
low：轻度思考，侧重快速响应
medium（默认值）：中度思考，平衡速度与思考深度
high：深度思考，侧重处理复杂专业问题
reasoning.effort 的优先级高于 enable_thinking，建议优先使用 reasoning.effort，enable_thinking 后续将不再支持。
Response Body
application/json
成功
TypeScript Definitions
Use the response body type in TypeScript.
本次调用的唯一标识符。
本次请求的 Unix 时间戳（秒）。
对象类型，固定为 response。
响应生成的状态。枚举值：
completed：生成完成
failed：生成失败
in_progress：生成中
cancelled：已取消
queued：请求排队中
incomplete：生成不完整
用于生成响应的模型 ID。
模型生成的输出项数组。数组中的元素类型和顺序取决于模型的响应。
输出项类型。枚举值：
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 工具时返回。包含知识库的检索查询和结果。
输出项的唯一标识符。所有类型的输出项都包含此字段。
消息角色，固定为 assistant。仅当 type 为 message 时存在。
输出项状态。可选值：completed（完成）、in_progress（生成中）。当 type 不为reasoning时存在。
工具或函数名称。当 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）。
工具调用的参数，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 服务中被调用函数的参数对象。
函数调用的唯一标识符。仅当 type 为 function_call 时存在。在返回函数调用结果时，需要通过此 ID 关联请求与响应。
消息内容数组。仅当 type 为 message 时存在。
内容类型，固定为 output_text。
模型生成的文本内容。
文本注释数组。通常为空数组。
推理摘要数组。仅当 type 为 reasoning 时存在。每个元素包含 type（值为 summary_text）和 text（摘要文本）字段。
搜索动作信息。仅当 type 为 web_search_call 时存在。
搜索查询关键词。
搜索类型，固定为 search。
搜索来源列表。每个元素包含 type和 url字段。
模型生成并执行的代码。仅当 type 为 code_interpreter_call 时存在。
代码执行输出数组。仅当 type 为 code_interpreter_call 时存在。每个元素包含 type（值为 logs）和 logs（代码执行日志）字段。
代码解释器容器标识符。仅当 type 为 code_interpreter_call 时存在。用于关联同一会话中的多次代码执行。
抽取目标描述，说明需要从网页中提取哪些信息。仅当 type 为 web_extractor_call 时存在。
工具调用的输出结果，字符串格式。
当 type 为 web_extractor_call 时为网页抽取的内容摘要
当 type 为 web_search_image_call 或 image_search_call 时为 JSON 字符串，包含图片搜索结果数组，每个元素包含 title（图片标题）、url（图片 URL）和 index（序号）字段
当 type 为 mcp_call 时为 MCP 服务返回的 JSON 字符串结果。
被抽取的网页 URL 列表。仅当 type 为 web_extractor_call 时存在。
MCP 服务标签。仅当 type 为 mcp_call 时存在。标识本次调用所使用的 MCP 服务。
知识库检索使用的查询列表。仅当 type 为 file_search_call 时存在。数组元素为字符串，表示模型生成的搜索查询词。
知识库检索结果数组。仅当 type 为 file_search_call 时存在。
匹配文档的文件 ID。
匹配文档的文件名。
匹配相关度评分，取值范围 0-1，值越大表示相关度越高。
匹配到的文档内容片段。
本次请求的 Token 消耗信息。
模型输出的 Token 数。
输入的 Token 数。
消耗的总 Token 数，为 input_tokens 与 output_tokens 的总和。
使用Qwen-VL 模型时输出Token的细粒度分类。
命中缓存的 Token 数。
输出 Token 的细粒度分类。
思考过程 Token 数。
输入的 Token 数。
模型输出的 Token 数。
消耗的总 Token 数，为 input_tokens 与 output_tokens 的总和。
固定为response_api。
工具使用统计信息。当使用内置工具时，包含各工具的调用次数。
示例：{"web_search": {"count": 1}}
当模型生成响应失败时返回的错误对象。成功时为 null。
回显请求中 tools 参数的完整内容，结构与请求体中的 tools 参数相同。
回显请求中 tool_choice 参数的值，枚举值为 auto、none、required。
curl -X POST "https://api.aa.com.cn/api/v1/responses" \ -H "Authorization: string" \ -H "Content-Type: application/json" \ -d '{ "model": "string", "input": "string" }'{
"id": "string",
"created_at": 0,
"object": "string",
"status": "string",
"model": "string",
"output": [
{
"type": "string",
"id": "string",
"role": "string",
"status": "string",
"name": "string",
"arguments": "string",
"call_id": "string",
"content": [
{
"type": "string",
"text": "string",
"annotations": "string"
}
],
"summary": [
"string"
],
"action": {
"query": "string",
"type": "string",
"sources": "string"
},
"code": "string",
"outputs": [
"string"
],
"container_id": "string",
"goal": "string",
"output": "string",
"urls": [
"string"
],
"server_label": "string",
"queries": [
"string"
],
"results": [
{
"file_id": "string",
"filename": "string",
"score": 0,
"text": "string"
}
]
}
],
"usage": {
"output_tokens": 0,
"input_tokens": 0,
"total_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens_details": {
"reasoning_tokens": 0
},
"x_details": {
"input_tokens": 0,
"output_tokens": 0,
"total_tokens": 0,
"x_billing_type": "string"
},
"x_tools": {}
},
"error ": {},
"tools": [
"string"
],
"tool_choice": "string"
}