快速开始
| API 根地址 | — |
| 认证方式 | Bearer Token,请求头携带 Authorization: Bearer YOUR_API_KEY(可在「密钥管理」中查看) |
| 数据格式 | 请求与响应均为 application/json,字符编码 UTF-8 |
| 接口协议 | 智能对话为同步的 OpenAI 兼容协议,单次请求直接返回结果;视频生成为异步任务式:先创建任务拿到任务 ID,再轮询查询获取视频地址 |
调用流程#
POST /v3/contents/generations/tasks提交生成参数,立即返回任务
id(不是视频本身)GET /v3/.../tasks/{id}建议提交后 20~30 秒首查,之后每 10~20 秒查一次
succeeded 后,从 content.video_url 下载视频,链接 24 小时过期,请及时转存创建视频生成任务
/v3/contents/generations/tasks
支持模型#
| 模型 ID | 说明 | 分辨率 | 时长范围 |
|---|---|---|---|
doubao-seedance-2-5-260628 | Seedance 2.5,最新旗舰,支持 30 秒长片、视频编辑与延长 | 480p / 720p / 1080p | 4~30 秒 或 -1(智能选时长) |
doubao-seedance-2-0-260128 | Seedance 2.0 标准版 | 480p / 720p / 1080p | 4~15 秒 |
doubao-seedance-2-0-fast-260128 | Seedance 2.0 Fast 极速版,出片更快 | 480p / 720p | 4~15 秒 |
doubao-seedance-2-0-mini-260615 | Seedance 2.0 Mini 轻量版,价格更低 | 480p / 720p | 4~15 秒 |
请求参数#
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 必填 | - | 模型 ID,见上表 |
content | array | 必填 | - | 输入内容数组,由 text / image_url / video_url / audio_url 组成,决定生成模式(见下方) |
resolution | string | 可选 | 720p | 分辨率档位:480p / 720p / 1080p(1080p 仅 2.5 与 2.0 标准版支持),同档位全比例同价 |
ratio | string | 可选 | 16:9 | 宽高比:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive(按输入素材自动适配,图生视频推荐) |
duration | int | 可选 | 5 | 视频时长(整数秒)。2.5 支持 4~30,2.0 系支持 4~15;2.5 可传 -1 由模型智能选择时长(按实际产出计费,建议显式指定) |
generate_audio | bool | 可选 | true | 是否生成与画面同步的音频(人声/音效/配乐,单声道)。不需要声音请显式传 false |
watermark | bool | 可选 | false | 是否在画面右下角添加「AI 生成」水印 |
seed | int | 可选 | -1 | 随机种子,取值 [-1, 2³²-1]。相同 seed 生成相似(不保证完全一致)的结果,可用于复现风格 |
return_last_frame | bool | 可选 | false | 是否返回视频尾帧 PNG(无水印),可用作下一段任务的首帧,实现多段视频接力 |
execution_expires_after | int | 可选 | 172800 | 任务过期阈值(秒),超时任务标记为 expired,取值 [3600, 259200] |
output_format | string | 可选 | mp4 | 仅 2.5:mp4(通用)/ mov(色彩还原更好,适合后期,部分播放器不兼容) |
omni_reference_task_type | string | 可选 | auto | 仅 2.5:auto / edit(视频编辑)/ extend(视频延长),显式指定可在提交时前置校验参数 |
生成模式#
由 content 数组的组合决定,三种图生场景互斥。
| 模式 | content 组成 | role 取值 |
|---|---|---|
| 文生视频 | 1 个 text(提示词) | - |
| 图生视频 - 首帧 | text(可选)+ 1 个 image_url | first_frame 或不填 |
| 图生视频 - 首尾帧 | text(可选)+ 2 个 image_url | 必填 first_frame / last_frame |
| 多模态参考生视频 | text + 参考素材(2.0 系:最多 9 图 + 3 视频 + 3 音频,且至少含 1 图或 1 视频;2.5:最多 30 图 + 10 视频 + 10 音频,音频可单独使用) | reference_image / reference_video / reference_audio |
| 视频编辑(仅 2.5) | text(须含「增加/删除/修改/替换」等编辑意图词,用 @视频1 指代素材)+ 至少 1 个 video_url(时长 4~30 秒) | reference_video,需 ratio=adaptive、duration=-1 |
| 视频延长(仅 2.5) | text(须含「向后延长/续写/延续」等意图词)+ 至少 1 个 video_url | reference_video,需 ratio=adaptive |
data:image/png;base64,...),格式 jpeg/png/webp/bmp/tiff 等,单张 < 30MB,宽高比 (0.4, 2.5),边长 (300, 6000)px;参考音频支持 wav/mp3,单段 2~15 秒。不支持含真人人脸的输入素材。不支持 Seedance 1.x 的
frames、camera_fixed 参数,传入会被忽略或报错。请求示例#
① 文生视频
curl -X POST {{BASE}}/v3/contents/generations/tasks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "无人机航拍视角飞越秋天的山谷,金黄色的森林和蜿蜒的河流,电影感"}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}'
② 首尾帧图生视频
{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "画面从第一帧平滑过渡到最后一帧,镜头缓慢推进"},
{"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
],
"resolution": "720p",
"ratio": "adaptive",
"duration": 5
}
③ 多模态参考生视频
{
"model": "doubao-seedance-2-5-260628",
"content": [
{"type": "text", "text": "以参考图的角色和风格,生成角色在雨夜街头行走的镜头"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}
创建成功响应
仅返回任务 ID,需再轮询查询接口获取视频。
{
"id": "cgt-20260606160057-xxxxx"
}
查询视频生成任务
/v3/contents/generations/tasks/{task_id}
任务状态机#
轮询建议:视频生成是分钟级任务(720p 5 秒约 90~150 秒),首次查询建议在提交后 20~30 秒,之后每 10~20 秒查询一次;超过 10 分钟未到终态可视为异常。
任务成功响应示例
{
"id": "cgt-20260606160057-xxxxx",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"content": {
"video_url": "https://xxx.tos-cn-beijing.volces.com/xxx.mp4?X-Tos-Expires=86400..."
},
"usage": { "completion_tokens": 108900, "total_tokens": 108900 },
"created_at": 1780732857,
"updated_at": 1780732991,
"seed": 97151,
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}
content.video_url(不在顶层),为签名直链,24 小时过期,请在任务成功后立即下载转存;下载直链时不要携带 Authorization 头。传入
duration: -1 或 ratio: adaptive 时,实际时长与比例以响应中的 duration / ratio 字段为准。Python 完整示例(创建 → 轮询 → 下载)#
import time, requests
BASE = "{{BASE}}/v3/contents/generations/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
# 1. 创建任务
task_id = requests.post(BASE, json={
"model": "doubao-seedance-2-0-260128",
"content": [{"type": "text", "text": "海浪拍打礁石,夕阳把海面染成金色,慢镜头"}],
"resolution": "720p", "ratio": "16:9", "duration": 5
}, headers=HEADERS, timeout=60).json()["id"]
# 2. 轮询直到终态
while True:
time.sleep(20)
task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
if task.get("status") in ("succeeded", "failed", "expired"):
break
# 3. 下载视频(24 小时过期,成功后立即转存)
if task["status"] == "succeeded":
video = requests.get(task["content"]["video_url"], stream=True, timeout=300)
with open(f"{task_id}.mp4", "wb") as f:
for chunk in video.iter_content(1 << 20):
f.write(chunk)
账户接口
查询账户信息
/v1/me
返回当前 API Key 的账户信息:
{
"code": 0,
"data": {
"client_name": "客户名称",
"balance": 95.50, // 账户余额(元)
"total_recharge": 100.00, // 累计充值(元)
"total_consumed": 4.50, // 累计消费(元)
"status": 1,
"created_at": "2026-01-01 12:00:00"
}
}
查询调用记录
/v1/usage?page=1&page_size=20
可选筛选参数:date_from / date_to(格式 YYYY-MM-DD)、status(pending / running / succeeded / failed)。返回分页的调用记录列表(含任务 ID、模型、状态、费用、时间)。
计费说明
平台与火山方舟官方保持一致,按 token 计费,单价单位为 元 / 百万 token。计费公式:
费用 = token 用量 ÷ 1,000,000 × 单价(元/百万token)
token 用量按官方公式估算:token ≈(输入视频时长 + 输出视频时长)× 宽 × 高 × 帧率 ÷ 1024(帧率默认 24)。分辨率档位对应的标准像素面积如下:
| 分辨率 | 标准尺寸(宽×高) | 分辨率 | 标准尺寸(宽×高) |
|---|---|---|---|
| 480p | 854 × 480 | 1080p | 1920 × 1080 |
| 720p | 1280 × 720 | 2K / 4K | 2560 × 1440 / 3840 × 2160 |
同一模型「含视频输入」与「不含视频输入」为两档不同单价,各分辨率的具体单价以「模型广场」价格表为准。
usage.completion_tokens(见「查询任务」响应)× 单价快照重新结算,多退少补——预估高于实际退回差额,低于实际补扣差额。任务失败 / 过期不产生视频费用,预扣押金全额退回。实际扣费金额可在「调用记录」中查询。对话计费规则#
智能对话按输入 / 输出 token 分别计价,单价单位同为 元 / 百万 token:
费用 = 输入 token × 输入单价 + 输出 token × 输出单价
提交请求时按「输入内容估算 token + max_tokens」预扣押金(余额不足直接拒绝请求),响应完成后按真实 usage(prompt_tokens / completion_tokens)结算,多退少补;上游请求失败自动全额退回预扣款。客户分组折扣自动生效,各模型输入 / 输出单价见「模型广场」。
错误码说明
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 400 | 请求参数错误(如模型不支持该分辨率、duration 超出范围、非法 ratio) | 根据返回的 msg 修正参数,参数错误不扣费 |
| 401 | API Key 无效或已被禁用 | 检查 Authorization 头,或到「密钥管理」确认 Key 状态 |
| 402 | 账户余额不足 | 到「财务管理」提交充值申请 |
| 404 | 任务不存在 | 确认任务 ID 是否正确、是否属于当前 API Key |
| 502 | 上游服务请求失败 | 稍后重试,持续失败请联系平台客服 |
| 503 | 当前无可用通道 | 平台通道繁忙,请稍后重试 |
智能对话(Chat Completions)
对话模型采用 OpenAI 兼容协议,同步返回:单次 HTTP 请求内直接拿到完整回答,无需轮询。可直接使用 OpenAI / DeepSeek 等通用 SDK,仅需将 base_url 指向平台根地址(—)+ /v1。视频生成仍为异步任务协议,见上方章节。
/v1/chat/completions
可用模型#
先调用模型列表接口获取当前已启用的对话模型(与「模型广场」一致,管理员可动态上下架):
/v1/models
{
"object": "list",
"data": [
{ "id": "glm-5.3", "object": "model", "created": 1781721600, "owned_by": "ai-gateway" },
{ "id": "deepseek-chat", "object": "model", "created": 1781721600, "owned_by": "ai-gateway" }
]
}
/v1/models 返回为准;各模型输入 / 输出单价见「模型广场」。请求参数#
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 必填 | - | 对话模型 ID,取值见 GET /v1/models |
messages | array | 必填 | - | 对话消息数组,每项为 {"role": "...", "content": "..."};role 支持 system / user / assistant / tool,content 为纯文本 |
stream | bool | 可选 | false | 是否以 SSE 流式返回,见下方「流式输出」 |
max_tokens | int | 可选 | 1024 | 最大生成 token 数,原值透传给上游(不限制上限),同时作为预扣费估算依据 |
temperature / top_p / stop 等 | - | 可选 | - | 其余 OpenAI 常规参数原样透传给上游模型 |
tools | array | 可选 | - | 工具调用(Function Calling),格式与 OpenAI 一致,原样透传给上游模型;模型会在响应中返回 tool_calls,由客户端执行后将结果作为 tool 角色消息回传 |
response_format | object | 可选 | - | 响应格式控制,如 {"type": "json_object"} 启用 JSON mode,原样透传给上游模型 |
functions | array | 可选 | - | 旧版函数调用接口(已被 tools 取代),原样透传给上游模型 |
tools(Function Calling)、response_format(JSON mode)、functions 等 OpenAI 标准参数,均原样透传给上游模型。同步请求受渠道超时限制,长回答建议开启
stream(流式无总时长限制),并将客户端读超时设置在 120 秒以上。响应格式#
非流式响应结构与 OpenAI 完全一致,usage 为最终结算依据:
{
"id": "chatcmpl-20261014120000-x1",
"object": "chat.completion",
"created": 1781721600,
"model": "glm-5.3",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "长沙市,湖南省省会……" },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 14, "completion_tokens": 356, "total_tokens": 370 }
}
出错时返回 OpenAI 风格错误体(HTTP 状态码非 2xx):
{
"error": {
"message": "余额不足,无法预扣本次最大可能费用",
"type": "insufficient_quota",
"param": null,
"code": null
}
}
| 状态码 | 场景与处理建议 |
|---|---|
| 400 | 缺少 model / messages、role 非法等请求参数错误 |
| 401 | API Key 无效或已被禁用,到「密钥管理」确认 Key 状态 |
| 402 | 账户余额不足,无法预扣本次最大可能费用(type 为 insufficient_quota) |
| 404 | 模型不存在或未启用(param 为 model),以 /v1/models 返回为准 |
| 429 | 上游限流,请稍后重试 |
| 502 | 上游聊天服务请求失败,预扣费自动全额退回 |
| 503 | 暂无可用聊天渠道,或该模型未配置有效售价 |
流式输出#
请求体中传 "stream": true,响应为标准 text/event-stream(SSE),分片结构与 OpenAI 一致,以 data: [DONE] 结束,OpenAI SDK 流式模式可直接消费。建议同时传 "stream_options": {"include_usage": true},结束前会额外收到一个含 usage 的分片,平台按其精确结算;若整个流中未收到 usage,则按预扣金额作为最终费用,不做差额退补。
data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[{"index":0,"delta":{"role":"assistant","content":"长"},"finish_reason":null}]}
data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[{"index":0,"delta":{"content":"沙"},"finish_reason":null}]}
data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":52,"total_tokens":66}}
data: [DONE]
请求示例#
① cURL(同步非流式)
curl -X POST {{BASE}}/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "你是一个乐于助人的中文助手"},
{"role": "user", "content": "介绍长沙市的特色"}
],
"max_tokens": 4096
}'
② cURL(流式)
curl -X POST {{BASE}}/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [{"role": "user", "content": "用三句话介绍长沙市"}],
"max_tokens": 4096,
"stream": true,
"stream_options": {"include_usage": true}
}'
③ Python(OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="{{BASE}}/v1" # 指向平台网关
)
resp = client.chat.completions.create(
model="glm-5.3",
messages=[
{"role": "system", "content": "你是一个乐于助人的中文助手"},
{"role": "user", "content": "介绍长沙市的特色"}
],
max_tokens=4096
)
print(resp.choices[0].message.content)
print(resp.usage) # 输入 / 输出 token 用量,即最终结算依据
使用 DeepSeek SDK、LangChain 等其他框架同理:base_url 指向平台、api_key 换成平台密钥即可。
④ cURL(工具调用 / Function Calling)
curl -X POST {{BASE}}/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [{"role": "user", "content": "北京今天天气怎么样?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的实时天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
}
}]
}'
模型会在响应的 tool_calls 中返回函数调用建议,客户端执行后将结果以 role: "tool" 的消息回传,模型据此生成最终回答。