外观
视频生成 API（豆包 Seedance）
最近更新：2026 年 10 月 17 日（Asia/Shanghai）
全文路径中的 API 网关地址为 https://ai.afp.net（与控制台一致）。环境变量示例使用 CIYUAN_BASE_URL / CIYUAN_API_KEY。
视频生成是异步任务：提交 → 拿到任务 ID → 轮询状态 → 完成后下载。查询与下载须使用同一账号下的令牌。
1. 模型
| 模型 ID | 说明 |
|---|---|
doubao-seedance-2-5-260628 | Seedance 2.5 |
doubao-seedance-2-0-260128 | Seedance 2.0 标准版 |
doubao-seedance-2-0-fast-260128 | Fast（更快，分辨率上限较低） |
doubao-seedance-2-0-mini-260615 | Mini（更轻量，分辨率上限较低） |
价格、可用时长与分辨率上限以控制台「模型广场 / 定价」为准。2.0 Fast / Mini 一般最高 720p；标准版与 2.5 支持更高规格时以模型说明为准。
2. 选择接入格式
| 格式 | 提交 | 查询 / 下载 | 适用 |
|---|---|---|---|
| 统一视频协议（OpenAI Video 风格） | POST /v1/videos | GET /v1/videos/{id}；GET /v1/videos/{id}/content | 希望统一对接多家视频模型 |
| 豆包原生（火山方舟风格） | POST /doubao/api/v3/contents/generations/tasks | GET /doubao/api/v3/contents/generations/tasks/{id} | 需要首尾帧、参考音视频、生成音频、草稿等完整参数 |
兼容旧路径：POST /v1/video/generations + GET /v1/video/generations/{id}。新项目建议用上表两种。
鉴权一律：Authorization: Bearer sk-xxx。
3. 统一视频协议
提交（文生视频）
bash
curl "$CIYUAN_BASE_URL/v1/videos" \
-H "Authorization: Bearer $CIYUAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-fast-260128",
"prompt": "海边日出，镜头缓慢推进，海浪轻拍礁石，电影感",
"duration": 5,
"resolution": "720p",
"metadata": {"ratio": "16:9"}
}'图生视频可增加 "image": "https://example.com/first_frame.png"；多张参考图用 "images": [...]。
返回含任务 id 与 status（如 queued）。
查询
bash
curl "$CIYUAN_BASE_URL/v1/videos/<task_id>" \
-H "Authorization: Bearer $CIYUAN_API_KEY"状态常见路径：queued → in_progress → completed（或 failed）。部分响应用 succeeded 表示成功，轮询时请同时兼容。
下载
bash
curl -L "$CIYUAN_BASE_URL/v1/videos/<task_id>/content" \
-H "Authorization: Bearer $CIYUAN_API_KEY" \
-o output.mp4支持 Range 头，可分段或断点续传。
Python 轮询示例
python
import os, time, requests
BASE = os.environ["CIYUAN_BASE_URL"]
H = {"Authorization": f"Bearer {os.environ['CIYUAN_API_KEY']}"}
task = requests.post(f"{BASE}/v1/videos", headers=H, json={
"model": "doubao-seedance-2-0-mini-260615",
"prompt": "一只柴犬在雪地里打滚，慢动作",
"duration": 5,
"resolution": "720p",
}).json()
task_id = task["id"]
print("任务已提交：", task_id)
while True:
info = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H).json()
status = info.get("status")
print("状态：", status, info.get("progress", ""))
if status in ("completed", "succeeded"):
break
if status == "failed":
raise RuntimeError(info.get("error"))
time.sleep(10)
with requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=H, stream=True) as r:
r.raise_for_status()
with open("output.mp4", "wb") as f:
for chunk in r.iter_content(1 << 20):
f.write(chunk)
print("已保存 output.mp4")4. 豆包原生格式（参数最全）
提交
bash
curl "$CIYUAN_BASE_URL/doubao/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $CIYUAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "小女孩在麦田里奔跑，风吹动麦浪，夕阳逆光"},
{"type": "image_url", "image_url": {"url": "https://example.com/first_frame.png"}, "role": "first_frame"}
],
"duration": 5,
"resolution": "1080p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}'返回：{"id": "task_xxxxxxxx"}。
查询
bash
curl "$CIYUAN_BASE_URL/doubao/api/v3/contents/generations/tasks/task_xxxxxxxx" \
-H "Authorization: Bearer $CIYUAN_API_KEY"成功示例字段：status: "succeeded"、content.video_url、duration、resolution。失败：status: "failed" 与 error。
常用参数
| 字段 | 说明 |
|---|---|
model | 必填，Seedance 模型 ID |
content | 必填数组：text、image_url（role 如 first_frame / last_frame / reference_image）、video_url、audio_url、draft_task |
duration | 秒；-1 表示自动；范围视模型 |
resolution | 如 480p / 720p / 1080p |
ratio | 如 16:9、9:16、1:1、adaptive |
generate_audio | 是否生成音频（视模型） |
seed / camera_fixed / watermark / return_last_frame | 随机种子 / 固定镜头 / 水印 / 返回尾帧 |
draft | 草稿模式；之后可用 draft_task 基于草稿出正式片 |
callback_url | 可选完成回调 |
部分版本也提供不带 /doubao 前缀的 /api/v3/contents/generations/tasks，方便改火山方舟 SDK 的 Base URL；带 /doubao 前缀的兼容性通常更好。
5. 注意事项
- 生成常需几十秒到数分钟；轮询间隔建议 5～15 秒，勿高频打查询。
- 上游视频链接常有时效，请尽快下载或转存。
- 统一协议字段如何映射到厂商参数由平台插件负责；某参数未生效时，改用豆包原生格式。
- 计费可能按次、按秒，并随分辨率、时长、是否生成音频变化——以控制台为准。
6. 本页 FAQ
提交成功但一直查不到结果？
继续耐心轮询；长时间停在 queued 可能是上游排队。failed 时读 error.message。务必用同一账号令牌与平台返回的任务 ID。
统一协议和豆包原生选哪个？
简单文生/图生视频用统一协议即可；需要首尾帧、音频、草稿等完整能力时用豆包原生。
能否同步等待直到出片？
接口设计为异步。请自行轮询或配置 callback_url（若开启）。