Chat API 兼容调用

本文说明火山 Doubao 文本、代码、角色、翻译和视觉理解模型的 Chat API / Chat Completions 兼容调用方式。

新接入业务建议优先使用 Responses API。Chat API 主要用于以下场景：

已经基于 OpenAI Chat Completions 写好业务代码，希望最小改造迁移到 AI Gateway。
业务暂时只需要文本生成、视觉理解、基础结构化输出或函数调用。
目标模型详情页暂未展示 Responses 示例。

如果需要联网搜索、图像处理、私域知识库搜索、MCP、上下文缓存等能力，请使用 Responses API。

一、文本、代码、翻译和角色模型

文本类模型可以使用 Chat Completions 接口，但不作为火山新业务的首选接口。

POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v3/chat/completions

基础调用

curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed-2.0-pro", "messages": [ { "role": "system", "content": "你是一个专业、准确、简洁的企业 AI 助手。" }, { "role": "user", "content": "请用三点总结 AI Gateway 的价值。" } ], "temperature": 0.7, "top_p": 0.8, "max_tokens": 1024, "stream": false }'

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>", ) completion = client.chat.completions.create( model="doubao-seed-2.0-pro", messages=[ {"role": "system", "content": "你是一个专业、准确、简洁的企业 AI 助手。"}, {"role": "user", "content": "请用三点总结 AI Gateway 的价值。"}, ], temperature=0.7, top_p=0.8, max_tokens=1024, ) print(completion.choices[0].message.content)

请求字段

字段	类型	必填	说明
`model` model	string	是	模型名称，例如 `doubao-seed-2.0-pro` doubao-seed-2.0-pro 。以模型广场详情页为准。
`messages` messages	array	是	对话消息列表。每条消息包含 `role` role 和 `content` content 。
`stream` stream	boolean	否	是否开启流式输出。
`stream_options` stream_options	object	否	流式配置。常用 `include_usage` include_usage ，用于在流式响应末尾返回用量。
`temperature` temperature	number	否	采样温度。越高越发散，越低越稳定。
`top_p` top_p	number	否	核采样参数。通常不要同时大幅调整 `temperature` temperature 和 `top_p` top_p 。
`max_tokens` max_tokens	integer	否	最大输出 Token 数。
`stop` stop	string / array	否	停止生成字符串。
`presence_penalty` presence_penalty	number	否	话题重复惩罚。
`frequency_penalty` frequency_penalty	number	否	词频重复惩罚。
`response_format` response_format	object	否	结构化输出配置。用于要求模型输出 JSON。
`tools` tools	array	否	工具定义。用于函数调用。
`tool_choice` tool_choice	string / object	否	工具选择策略，例如 `auto` auto 、 `none` none 或指定工具。
`parallel_tool_calls` parallel_tool_calls	boolean	否	是否允许并行工具调用，取决于模型能力。
`seed` seed	integer	否	随机种子。用于提高同参数下的可复现性，取决于模型能力。
`user` user	string	否	终端用户标识，便于业务审计和追踪。

使用建议：

代码生成、SQL 生成、翻译等确定性任务建议使用较低
```
temperature
```
temperature
，例如
```
0
```
0
到
```
0.3
```
0.3
。
创意写作、营销文案等任务可适当提高
```
temperature
```
temperature
。
生产环境建议明确设置
```
max_tokens
```
max_tokens
，避免生成过长导致成本和延迟不可控。
```
tools
```
tools
、
```
response_format
```
response_format
、
```
seed
```
seed
等高级字段不是所有模型都支持，接入前应以模型详情页和实际测试为准。

流式输出

curl -N -X POST "$AI_GATEWAY_VOLC_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed-2.0-pro", "messages": [ { "role": "user", "content": "请分步骤说明如何接入 AI Gateway。" } ], "stream": true, "stream_options": { "include_usage": true } }'

流式响应通常以 SSE 事件返回。客户端需要逐行读取

data:

data:

内容，并在收到结束事件后关闭连接。

结构化输出

需要业务系统稳定解析结果时，可以使用

response_format

response_format

。

curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed-2.0-pro", "messages": [ { "role": "system", "content": "你只输出合法 JSON，不要输出 Markdown。" }, { "role": "user", "content": "抽取工单信息：客户反馈模型调用 429，影响生产报表。" } ], "response_format": { "type": "json_object" } }'

建议业务侧仍进行 JSON 解析和 Schema 校验。

工具调用

{ "model": "doubao-seed-2.0-pro", "messages": [ { "role": "user", "content": "查询订单 202606150001 的物流状态。" } ], "tools": [ { "type": "function", "function": { "name": "get_order_status", "description": "根据订单号查询物流状态", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号" } }, "required": ["order_id"] } } } ], "tool_choice": "auto" }

工具调用的典型流程：

客户端发送用户问题和工具定义。
模型返回工具调用意图和参数。
业务系统执行真实工具。
将工具结果作为
```
tool
```
tool
消息回传给模型。
模型基于工具结果生成最终回答。

二、视觉理解模型

适用模型：

```
doubao-seed-1.6-vision
```
doubao-seed-1.6-vision
```
doubao-1.5-vision-pro
```
doubao-1.5-vision-pro

视觉理解模型仍使用 Chat Completions 接口，在

messages.content

messages.content

中传入文本和图片。

curl -X POST "$AI_GATEWAY_VOLC_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seed-1.6-vision", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "请识别图片中的主要内容，并输出 JSON：主体、颜色、场景、是否包含文字。" }, { "type": "image_url", "image_url": { "url": "https://example.com/demo.png" } } ] } ], "response_format": { "type": "json_object" } }'

多图对比示例：

{ "model": "doubao-1.5-vision-pro", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "请比较两张图片中的商品差异。"}, {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}}, {"type": "image_url", "image_url": {"url": "https://example.com/b.png"}} ] } ] }

注意：

图片 URL 需要模型服务可访问，不能使用本地路径。
图片数量、大小、格式限制以模型详情页为准。
多图输入会增加 Token、费用和延迟，生产环境建议压缩图片并控制数量。

联系我们