Responses API
本文说明火山引擎模型在 AI Gateway 中的 Responses API 调用方式。对于火山文本生成、视觉理解、结构化输出和工具调用等新接入场景，建议优先使用 Responses API，而不是 Chat API。
一、请求地址
POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v3/responses
请求头：
Authorization: Bearer <API_KEY>
Content-Type: application/json
二、为什么优先使用 Responses API
Responses API 覆盖能力更完整，适合承载文本、多模态输入、工具调用和后续高级能力。Chat API 更适合存量 OpenAI Chat Completions 代码兼容。
| 能力 | Chat API | Responses API |
|---|
| 文本生成 | 支持 | 支持 |
| 视觉理解 | 支持 | 支持 |
| 结构化输出 | beta 阶段 | beta 阶段 |
| 函数调用 Function Calling | 支持 | 支持 |
| 联网搜索 Web Search | 不支持 | 支持 |
| 图像处理 Image Process | 不支持 | 支持 |
| 私域知识库搜索 Knowledge Search | 不支持 | 支持 |
| 云部署 MCP | 不支持 | 支持 |
| 上下文缓存 | 不支持 | 支持，具体模型版本以模型广场为准 |
选择建议：
- 新业务默认使用 Responses API。
- 已有 Chat Completions 代码可以继续使用 Chat API，后续逐步迁移。
- 需要联网搜索、图像处理、知识库检索、MCP 或上下文缓存时，必须使用 Responses API。
- 如果模型广场详情页没有 Responses 示例，请以模型详情页为准。
三、基础文本生成
curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2.0-lite",
"input": "请总结 AI Gateway 的三个核心能力。",
"max_output_tokens": 512
}'
Python 示例：
from openai import OpenAI
client = OpenAI(
base_url="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v3",
api_key="<your-api-key>",
)
response = client.responses.create(
model="doubao-seed-2.0-lite",
input="请总结 AI Gateway 的三个核心能力。",
max_output_tokens=512,
)
print(response.output_text)
四、请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|
model
model | string | 是 | 模型名称。以模型广场详情页为准，例如 doubao-seed-2.0-lite
doubao-seed-2.0-lite 。 |
input
input | string / array | 是 | 输入内容，可以是字符串，也可以是多轮、多模态数组。 |
instructions
instructions | string | 否 | 系统指令，类似 Chat API 中的 system
system 消息。 |
stream
stream | boolean | 否 | 是否流式输出。 |
temperature
temperature | number | 否 | 采样温度。 |
top_p
top_p | number | 否 | 核采样参数。 |
max_output_tokens
max_output_tokens | integer | 否 | 最大输出 Token 数。 |
response_format
response_format | object | 否 | 结构化输出配置。 |
tools
tools | array | 否 | 工具定义。 |
tool_choice
tool_choice | string / object | 否 | 工具选择策略。 |
parallel_tool_calls
parallel_tool_calls | boolean | 否 | 是否允许并行工具调用。是否支持取决于模型能力。 |
metadata
metadata | object | 否 | 业务自定义元数据。 |
previous_response_id
previous_response_id | string | 否 | 用于衔接上一轮响应。是否支持取决于模型和网关能力。 |
store
store | boolean | 否 | 是否存储响应。企业场景应按合规要求设置。 |
字符串输入
{
"model": "doubao-seed-2.0-lite",
"input": "请把下面这句话翻译成英文：AI Gateway 支持统一模型治理。",
"max_output_tokens": 512
}
多轮输入
{
"model": "doubao-seed-2.0-pro",
"instructions": "你是企业知识库助手，回答要简洁准确。",
"input": [
{
"role": "user",
"content": "AI Gateway 支持哪些能力？"
},
{
"role": "assistant",
"content": "支持统一模型接入、API Key 管理、路由、用量统计等能力。"
},
{
"role": "user",
"content": "请补充 BYOK 和权限管理。"
}
]
}
视觉理解输入
支持视觉输入的模型可以在
input
input
中传入文本和图片。
curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-1.6-vision",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "请识别图片中的主要内容，并输出 JSON。"
},
{
"type": "input_image",
"image_url": "https://example.com/demo.png"
}
]
}
],
"max_output_tokens": 1024
}'
注意：
- 图片 URL 需要能被模型服务访问，不要使用本地路径。
- 图片数量、大小和格式限制以模型详情页为准。
- 视觉理解任务也建议优先使用 Responses API。
六、流式输出
curl -N -X POST "$AI_GATEWAY_VOLC_BASE_URL/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2.0-pro",
"input": "请分步骤说明如何接入 AI Gateway。",
"stream": true,
"max_output_tokens": 1024
}'
流式返回通常为 SSE 事件。客户端需要按事件类型读取增量文本、工具调用和结束事件。
七、结构化输出
结构化输出仍处于 beta 阶段。需要稳定 JSON 时，可以使用
response_format
response_format
，同时在
instructions
instructions
中明确只输出 JSON。
curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seed-2.0-pro",
"instructions": "你只输出合法 JSON，不要输出 Markdown。",
"input": "抽取工单信息：客户反馈 API 调用 429，影响生产报表。字段包括 priority、category、summary。",
"response_format": {
"type": "json_object"
},
"max_output_tokens": 512
}'
建议业务侧仍进行 JSON 解析和 Schema 校验。
八、工具调用
Responses API 支持函数调用，适合查询订单、检索知识库、调用内部服务等场景。
{
"model": "doubao-seed-2.0-pro",
"input": "查询订单 202606150001 的物流状态。",
"tools": [
{
"type": "function",
"name": "get_order_status",
"description": "根据订单号查询物流状态",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号"
}
},
"required": ["order_id"]
}
}
],
"tool_choice": "auto"
}
基本处理流程：
- 客户端发送用户问题和工具定义。
- 模型返回工具调用意图和参数。
- 业务系统执行真实工具。
- 将工具结果回传给模型。
- 模型基于工具结果生成最终回答。
九、高级能力说明
Responses API 是火山后续高级能力的推荐承载接口。以下能力需以模型广场和接入点展示为准：
| 能力 | 说明 |
|---|
| Web Search | 联网搜索，适合需要实时网页信息的问答。 |
| Image Process | 图像处理，适合图片编辑、分析或多模态处理任务。 |
| Knowledge Search | 私域知识库搜索，适合企业内部知识问答。 |
| MCP | 云部署 MCP 工具，适合统一接入外部工具能力。 |
| Context Cache | 上下文缓存，适合重复长上下文、多轮长会话等场景。 |
如果业务需要这些能力，请优先选择 Responses API，并以模型详情页示例为准。
