Responses API
Responses API 是 OpenAI 兼容的新一代响应接口，用于统一承载文本、多模态输入、结构化输出和工具调用。阿里云百炼部分模型支持 Responses API；在 AI Gateway 中调用时仍使用 AI Gateway 的网关地址和 API Key。
如果模型广场详情页没有展示 Responses 示例，建议优先使用 Chat Completions。
一、请求地址
POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/responses
请求头：
Authorization: Bearer <API_KEY>
Content-Type: application/json
二、基础请求示例
curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen/qwen3.7-max",
"input": "请总结 AI Gateway 的三个核心能力。"
}'
Python 示例：
from openai import OpenAI
client = OpenAI(
base_url="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1",
api_key="<your-api-key>",
)
response = client.responses.create(
model="qwen/qwen3.7-max",
input="请总结 AI Gateway 的三个核心能力。",
)
print(response.output_text)
三、请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|
model
model | string | 是 | 模型名称。以模型广场详情页复制的模型标识为准。 |
input
input | string / array | 是 | 用户输入。可以是简单字符串，也可以是多轮、多模态内容数组。 |
instructions
instructions | string | 否 | 类似 Chat Completions 中的 system
system 指令，用于设置模型行为。 |
stream
stream | boolean | 否 | 是否开启流式输出。 |
temperature
temperature | number | 否 | 采样温度。值越高输出越随机。 |
top_p
top_p | number | 否 | 核采样参数。 |
max_output_tokens
max_output_tokens | integer | 否 | 最大输出 Token 数。Responses API 使用该字段控制输出长度。 |
metadata
metadata | object | 否 | 业务自定义元数据。可用于审计、追踪或统计。 |
response_format
response_format | object | 否 | 结构化输出配置。是否支持取决于模型。 |
tools
tools | array | 否 | 工具定义列表。 |
tool_choice
tool_choice | string / object | 否 | 工具选择策略。 |
parallel_tool_calls
parallel_tool_calls | boolean | 否 | 是否允许并行工具调用。是否支持取决于模型。 |
previous_response_id
previous_response_id | string | 否 | 用于衔接上一轮 Responses 响应。是否支持取决于网关和模型能力。 |
store
store | boolean | 否 | 是否存储响应。企业场景通常按合规策略设置。 |
字符串输入
适合单轮文本任务。
{
"model": "qwen/qwen3.7-max",
"input": "把下面这句话翻译成英文：AI Gateway 支持统一模型治理。"
}
多轮输入
{
"model": "qwen/qwen3.7-max",
"input": [
{
"role": "user",
"content": "AI Gateway 支持哪些能力？"
},
{
"role": "assistant",
"content": "支持统一模型接入、API Key 管理、路由、用量统计等能力。"
},
{
"role": "user",
"content": "请把这些能力整理成表格。"
}
]
}
多模态输入
支持多模态的模型可以在
content
content
中传入文本和图片。
{
"model": "qwen/qwen3.6-plus",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "请识别图片中的主要对象，并输出 JSON。"
},
{
"type": "input_image",
"image_url": "https://example.com/image.png"
}
]
}
]
}
多模态字段是否支持、图片数量和大小限制，以模型详情页为准。
五、流式输出
curl -N -X POST "$AI_GATEWAY_OPENAI_BASE_URL/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen/qwen3.7-max",
"input": "请分步骤说明 AI Gateway 的接入流程。",
"stream": true,
"max_output_tokens": 1024
}'
客户端需要按 SSE 事件逐段读取输出。不同 SDK 对 Responses 流式事件的封装不同，建议在业务代码中单独封装解析逻辑。
六、结构化输出
{
"model": "qwen/qwen3.7-max",
"instructions": "你只输出合法 JSON，不要输出 Markdown。",
"input": "抽取工单信息：客户反馈 API 调用 429，影响生产环境。",
"response_format": {
"type": "json_object"
}
}
建议业务侧仍进行 JSON Schema 校验，避免模型输出不符合预期导致下游报错。
七、工具调用
{
"model": "qwen/qwen3.7-max",
"input": "查询客户 c_1001 最近 7 天的模型调用费用。",
"tools": [
{
"type": "function",
"name": "query_customer_cost",
"description": "查询客户模型调用费用",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string"
},
"days": {
"type": "integer"
}
},
"required": ["customer_id", "days"]
}
}
],
"tool_choice": "auto"
}
工具调用的基本流程与 Chat Completions 类似：模型先返回工具调用意图，业务系统执行工具，再把工具结果回传给模型生成最终回答。
八、响应解析
Responses API 的响应结构与 Chat Completions 不同。SDK 中通常可以直接读取
output_text
output_text
；原始 JSON 中则需要遍历
output
output
。
示例结构：
{
"id": "resp_xxx",
"object": "response",
"model": "qwen/qwen3.7-max",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "AI Gateway 的核心能力包括统一接入、路由治理和用量统计。"
}
]
}
],
"usage": {
"input_tokens": 32,
"output_tokens": 24,
"total_tokens": 56
}
}
字段说明：
| 字段 | 说明 |
|---|
id
id | 响应 ID。用于多轮衔接或问题排查。 |
output
output | 输出内容数组，可能包含文本、工具调用等不同类型。 |
output_text
output_text | SDK 封装的纯文本输出快捷字段。 |
usage.input_tokens
usage.input_tokens | 输入 Token 数。 |
usage.output_tokens
usage.output_tokens | 输出 Token 数。 |
usage.total_tokens
usage.total_tokens | 总 Token 数。 |
九、与 Chat Completions 的选择建议
| 场景 | 推荐接口 |
|---|
| 已有 OpenAI Chat Completions 代码 | Chat Completions |
| 需要最大兼容性 | Chat Completions |
| 需要统一文本、多模态和工具能力 | Responses |
需要使用 SDK 新能力，例如 client.responses.create
client.responses.create | Responses |
| 模型详情页没有 Responses 示例 | Chat Completions |
