一、概述

1.1文档说明

本文档面向调用 AI 网关 Seedance 视频生成能力的统一接口作出说明。
调用方只需持有网关颁发的 API Key，按本文档协议调用即可。

1.2接入信息

项目	说明
服务地址（Base URL）	https://example.com（以网关实际部署地址为准）
通信协议	HTTPS，请求与响应均为 JSON（UTF-8）
鉴权方式	API Key（Bearer Token），见"二、鉴权方式"
调用模式	异步任务：创建任务 → 轮询查询

1.3调用流程

1.提交任务：调用 POST/v1/video/generations，获得 task_id。

2.查询结果：调用 GET/v1/video/generations/{task_id} 轮询任务状态。

3.获取视频：任务状态变为 SUCCESS 后，从响应 data.result_url 下载视频文件。

二、鉴权方式

所有接口均需在请求头中携带网关颁发的 API Key，未携带或Key无效将返回 401。API Key
请妥善保管；如怀疑泄露，请立即禁用并重新创建。

请求头	说明
Authorization	Bearer {API_KEY}，必填。sk- 前缀可选，网关会自动剥离
Content-Type	application/json，POST 请求建议携带

📌

Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json

三、模型列表

在创建任务的 model 字段中填写下表模型 ID，网关将按模型 ID 路由到对应上游渠道。各参数的取值范围以模型实际能力为准；网关不做参数白名单校验（仅限制时长 1–3600 秒），不支持的参数或取值将由上游报错透回，具体限制以火山方舟官方文档为准。以下模型 ID 以运营开通为准。

模型 ID	说明
doubao-seedance-2-0-260128	采用模型原厂直供接口
doubao-seedance-1-5-pro	Seedance 1.5 Pro（支持 draft 草稿模式）
doubao-seedance-2-0-fast-260128	Seedance 2.0 Fast（快速版）。该模型不支持自定义分辨率参数、视频时长和视频比例。

四、创建视频生成任务

💡

POST /v1/video/generations

提交一个视频生成任务。任务异步执行，接口立即返回 task_id。

4.1请求参数

顶层参数：

参数	类型	必填	说明
model	string	是	模型 ID，见"三、模型列表"
prompt	string	是	视频内容描述（提示词），建议包含主体、动作、场景、镜头语言与风格
image	string	否	首帧图片（图生视频），http(s) URL 或 Base64 Data URI
images	array(string)	否	图片列表（多图参考 / 首尾帧等多图场景）
duration	integer	否	视频时长（秒），默认 5；网关限制 1–3600，实际取值范围以模型上游能力为准
metadata	object	否	厂商扩展参数，见下表。其余顶层字段会被网关静默丢弃

metadata 扩展参数：

参数	类型	说明
resolution	string	480p / 720p / 1080p，默认 720p（以模型能力为准）
ratio	string	16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive
seed	integer	随机种子，-1 表示随机
generate_audio	boolean	是否生成有声视频（仅支持的模型生效）
watermark	boolean	是否添加水印，默认 false
draft	boolean	草稿模式，低成本快速预览（上游仅部分模型支持）
camera_fixed	boolean	镜头是否固定
return_last_frame	boolean	是否返回尾帧图片
service_tier	string	上游服务档位
callback_url	string	任务结束回调地址（由上游火山方舟直接 POST 回调，非网关回调）

注意：resolution / ratio / seed 等厂商参数必须放入 metadata 透传；放在请求顶层会被网关静默丢弃（不报错也不生效）。单图用 image，多图用 images，网关中不存在 image_url / last_frame_url / reference_images 字段。

4.2响应说明

HTTP 200，返回任务标识与初始状态：

字段	类型	说明
task_id	string	任务 ID（网关生成的公开 ID），用于查询结果
id	string	同 task_id
object	string	固定为 "video"
status	string	初始状态，固定为 queued
model	string	实际生效的模型 ID
progress	integer	初始为 0
created_at	integer	创建时间（Unix 秒级时间戳）

💡

{
"id": "task_a1b2c3d4e5f6", "task_id": "task_a1b2c3d4e5f6",
"object": "video",
"model": "doubao-seedance-2-0-260128", "status": "queued",
"progress": 0,
"created_at": 1784534400
}

五、查询生成任务

💡

GET /v1/video/generations/{task_id}

查询任务状态与生成结果。路径参数 task_id 为创建任务时返回的任务 ID。

5.1任务状态

状态	说明
SUBMITTED	已提交
QUEUED	排队中
IN_PROGRESS	生成中
SUCCESS	生成成功，result_url 包含结果
FAILURE	生成失败，fail_reason 包含失败原因1

注：本路径直接输出上述大写内部状态，不存在 cancelled 状态；OpenAI 兼容路径 /v1/videos/{task_id} 输出小写
queued / in_progress / completed / failed，响应结构不同（见"八、附录"）。

5.2响应说明

响应外层为统一包装 {code, message, data}，code 为 "success" 时 data 为任务对象：

字段	类型	说明
data.task_id	string	任务 ID
data.status	string	任务状态，见 5.1（大写）
data.action	string	任务动作（generate 等）
data.result_url	string	视频下载地址（SUCCESS 时返回）
data.fail_reason	string	失败原因描述（FAILURE 时返回）
data.progress	string	进度，形如 "100%"
data.submit_time	integer	提交时间（Unix 秒）
data.start_time	integer	开始执行时间（Unix 秒）
data.finish_time	integer	结束时间（Unix 秒）
data.data	object	上游原始响应（含 content.video_url、resolution、ratio、duration、error等，以实际上游返回为准）

任务成功时的响应示例：

💡

{
"code": "success",
"message": "", "data": {
"task_id": "task_a1b2c3d4e5f6", "action": "generate",
"status": "SUCCESS",
"progress": "100%",
"result_url": "https://tos-xxx.volces.com/.../video.mp4?X-Tos-Signature=...", "submit_time": 1784534400,
"start_time": 1784534402,
"finish_time": 1784534496,
"data": {
"content": { "video_url": "https://tos-xxx.volces.com/.../video.mp4?..." }, "resolution": "1080p",
"ratio": "16:9",
"duration": 5
}
}
}

六、错误码

任务接口的错误响应为顶层结构（非 {error:{...}} 包裹）：

💡

{
"code": "invalid_request",
"message": "model is required",
"data": null
}

常见错误：

HTTP	code	说明
400	invalid_request	请求参数缺失或不合法
400	invalid_seconds / invalid_size	时长 / 尺寸参数不合法
401	（非 JSON code）	返回 {success:false, message:...}，API Key 缺失或无效
404	task_not_exist	任务不存在或不属于当前 API Key
429	保留原 code）	分组上游负载饱和，message 提示限流，请退避重试
500	gen_relay_info_failed 等	网关内部或渠道错误（如 get_channel_failed / do_request_failed / build_request_failed），请联系网关团队

重试建议：429 与 5xx 可按指数退避重试（如 2s / 4s / 8s，最多 3 次）；4xx 为请求本身问题，修复前请勿重试。

七、调用示例

7.1cURL

创建任务：

📌

curl -X POST "https://example.com/v1/video/generations"
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"
-H "Content-Type: application/json"
-d '{
"model": "doubao-seedance-2-0-260128",
"prompt": "一只金毛犬在阳光下的草地上奔跑，慢动作，电影感", "duration": 5,
"metadata": { "resolution": "1080p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'

轮询查询：

📌

curl "https://example.com/v1/video/generations/task_a1b2c3d4e5f6"
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

7.2Python

📌

import time import requests

BASE_URL = "https://example.com" API_KEY = "sk-xxxxxxxxxxxxxxxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
#1. 创建任务
resp = requests.post( f"{BASE_URL}/v1/video/generations", headers=HEADERS,
json={
"model": "doubao-seedance-2-0-260128",
"prompt": "一只金毛犬在阳光下的草地上奔跑，慢动作，电影感", "duration": 5,
"metadata": {"resolution": "1080p", "ratio": "16:9"},
},
timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]

#2. 轮询任务结果
for _ in range(120): # 每 5 秒一次，最长 600 秒
r = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30)
r.raise_for_status() data = r.json()["data"]
if data["status"] == "SUCCESS":
print("视频地址:", data["result_url"]) break
if data["status"] == "FAILURE":
raise RuntimeError(f"任务失败: {data.get('fail_reason')}") time.sleep(5)
else:
raise TimeoutError("等待超时")

7.3Node.js

📌

const BASE_URL = "https://example.com"; const API_KEY = "sk-xxxxxxxxxxxxxxxx";
const headers = {
Authorization: Bearer ${API_KEY}, "Content-Type": "application/json",
};

// 1. 创建任务
const createResp = await fetch(${BASE_URL}/v1/video/generations, { method: "POST",
headers,
body: JSON.stringify({
model: "doubao-seedance-2-0-260128",
prompt: "一只金毛犬在阳光下的草地上奔跑，慢动作，电影感", duration: 5,
metadata: { resolution: "1080p", ratio: "16:9" },
}),
});
if (!createResp.ok) throw new Error(await createResp.text()); const { task_id } = await createResp.json();

// 2. 轮询任务结果
for (let i = 0; i < 120; i++) {
const r = await fetch(${BASE_URL}/v1/video/generations/${task_id}, { headers }); const { data } = await r.json();
if (data.status === "SUCCESS") {
console.log("视频地址:", data.result_url); break;
}
if (data.status === "FAILURE") {
throw new Error(任务失败: ${data.fail_reason});
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}

八、附录：注意事项

▪内容合规：prompt与输入图片需符合公司内容安全规范；命中上游内容安全策略的任务将以
FAILURE 结束，fail_reason 包含上游错误信息。

▪结果时效：result_url 的时效取决于网关持久化配置——未开启持久化时为火山方舟 TOS 签名
URL（有效期由上游决定，请及时转存）；

▪参数透传：metadata 中的参数原样转发，网关不做白名单校验；不支持的参数或取值将由上游报错并透回。

▪兼容接口：网关同时提供 OpenAI 兼容端点 POST /v1/videos、GET /v1/videos/{task_id}（状态为 queued / in_progress / completed / failed，响应结构不同），如需使用请向网关团队索取对应文档。

Seedance 视频生成 API 调用文档（OpenAI 兼容格式）

一、概述#

1.1文档说明#

1.2接入信息#

1.3调用流程#

二、鉴权方式#

三、模型列表#

四、创建视频生成任务#

4.1请求参数#

4.2响应说明#

五、查询生成任务#

5.1任务状态#

5.2响应说明#

六、错误码#

七、调用示例#

7.1cURL#

7.2Python#

7.3Node.js#

八、附录：注意事项#