API 文档 - AI网关系统

快速开始

API 根地址	`—`
认证方式	Bearer Token，请求头携带 `Authorization: Bearer YOUR_API_KEY`（可在「密钥管理」中查看）
数据格式	请求与响应均为 `application/json`，字符编码 UTF-8
接口协议	视频生成为异步任务式：先创建任务拿到任务 ID，再轮询查询获取视频地址

调用流程#

创建任务

POST /v3/contents/generations/tasks
提交生成参数，立即返回任务 id（不是视频本身）

轮询查询

GET /v3/.../tasks/{id}
建议提交后 20~30 秒首查，之后每 10~20 秒查一次

获取视频

状态变为 succeeded 后，从 content.video_url 下载视频，链接 24 小时过期，请及时转存

创建视频生成任务

POST /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`

素材说明：图片支持公网 URL、Base64（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 参数，传入会被忽略或报错。

请求示例#

① 文生视频

bash

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
  }'

② 首尾帧图生视频

json

{
  "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
}

③ 多模态参考生视频

json

{
  "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，需再轮询查询接口获取视频。

json

{
  "id": "cgt-20260606160057-xxxxx"
}

查询视频生成任务

GET /v3/contents/generations/tasks/{task_id}

任务状态机#

queued排队中 → running生成中 → succeeded成功 ✓

或进入终态： failed失败 expired过期

轮询建议：视频生成是分钟级任务（720p 5 秒约 90~150 秒），首次查询建议在提交后 20~30 秒，之后每 10~20 秒查询一次；超过 10 分钟未到终态可视为异常。

任务成功响应示例

json

{
  "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 完整示例（创建 → 轮询 → 下载）#

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)

账户接口

查询账户信息

GET /v1/me

返回当前 API Key 的账户信息：

json

{
  "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"
  }
}

查询调用记录

GET /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

同一模型「含视频输入」与「不含视频输入」为两档不同单价，各分辨率的具体单价以「模型广场」价格表为准。

计费流程：创建任务时按预估 token 用量预扣押金；任务到达终态后，以上游返回的真实 usage.completion_tokens（见「查询任务」响应）× 单价快照重新结算，多退少补——预估高于实际退回差额，低于实际补扣差额。任务失败 / 过期不产生视频费用，预扣押金全额退回。实际扣费金额可在「调用记录」中查询。

错误码说明

错误码	说明	处理建议
400	请求参数错误（如模型不支持该分辨率、duration 超出范围、非法 ratio）	根据返回的 msg 修正参数，参数错误不扣费
401	API Key 无效或已被禁用	检查 Authorization 头，或到「密钥管理」确认 Key 状态
402	账户余额不足	到「财务管理」提交充值申请
404	任务不存在	确认任务 ID 是否正确、是否属于当前 API Key
502	上游服务请求失败	稍后重试，持续失败请联系平台客服
503	当前无可用通道	平台通道繁忙，请稍后重试

OPENAI COMPATIBLE

智能对话 API

聊天模型采用 OpenAI 兼容协议，可直接使用 DeepSeek 或 OpenAI SDK。视频生成接口仍保持原有异步任务协议。

GET/v1/models

POST/v1/chat/completions

bash

curl -X POST {{BASE}}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}],"max_tokens":1024}'

设置 "stream": true 即可获得标准 SSE 流式响应。首期仅支持 system/user/assistant 纯文本消息；tools、vision 和 JSON mode 会明确返回参数错误。费用按输入与输出 token 分别计价，响应中的 usage 为最终结算依据。