视频生成 API（豆包 Seedance）

最近更新：2026 年 10 月 23 日（Asia/Shanghai）
关联：帮助中心 · 大模型 API · 图像生成 · 完整参考

词元探索为 Seedance 提供两套接入协议：

Seedance 官方协议：参数最全，支持多模态参考、2.5 编辑/延长、素材库引用和签名回调，新项目优先使用；
视频兼容协议：兼容已有 OpenAI 视频客户端，支持 prompt、images、seconds、metadata 等通用字段。

两套协议共用同一个 API Key、账户额度和计费体系，但请求字段、响应结构和任务状态不同。创建、查询和状态判断必须使用同一套协议，不要混用。

所有请求的 API 网关为 https://ai.afp.net。示例使用以下环境变量：

bash

export CIYUAN_BASE_URL="https://ai.afp.net"
export CIYUAN_API_KEY="sk-xxxxxxxx"    # 控制台「令牌管理」创建

鉴权统一使用请求头 Authorization: Bearer sk-xxx。查询、下载和素材操作必须使用同一账号下的令牌。

保管好 API Key

API Key 是付费凭证。只放在服务端环境变量或密钥管理系统中，不要写入前端、截图、日志或公开仓库。

1. 模型与端点

1.1 模型

模型 ID	说明
`doubao-seedance-2-5-260628`	Seedance 2.5，质量优先；支持 4～30 秒与全模态参考/编辑
`doubao-seedance-2-0-260128`	Seedance 2.0 标准版；支持 4～15 秒
`doubao-seedance-2-0-fast-260128`	Seedance 2.0 Fast，速度优先；一般仅 480p/720p 档
`doubao-seedance-2-0-mini-260615`	Seedance 2.0 Mini，轻量低成本；一般仅 480p/720p 档

模型是否对当前令牌开放，取决于令牌分组与渠道配置。调用前先查：

bash

curl "$CIYUAN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

返回列表里没有的模型 ID 不要调用。价格与可用分辨率以控制台「模型广场 / 定价」为准。

1.2 端点总览

协议	创建任务	查询任务	下载结果	主要请求字段
Seedance 官方（推荐）	`POST /api/v3/contents/generations/tasks`	`GET /api/v3/contents/generations/tasks/{task_id}`	`content.video_url`，或 `GET /v1/videos/{task_id}/content`	`content`、整数 `duration`、`ratio`
视频兼容	`POST /v1/video/generations`（也支持 OpenAI Videos 风格 `POST /v1/videos`）	`GET /v1/video/generations/{task_id}`（OpenAI Videos 风格用 `GET /v1/videos/{id}`）	`GET /v1/videos/{task_id}/content`	`prompt`、`images`、字符串 `seconds`、`metadata`

官方协议还提供任务列表与删除：

text

GET    /api/v3/contents/generations/tasks?page_num=1&page_size=10
DELETE /api/v3/contents/generations/tasks/{task_id}

列表支持 filter.status、filter.model、filter.service_tier 和重复传入的 filter.task_ids；page_num、page_size 取值范围为 1～500（默认 1 / 10）。删除排队中的任务会取消任务，删除已结束的任务只清理记录；任务运行中返回 409 task_cannot_be_cancelled。

两套协议的端点和字段不能混用

官方端点只接受 content 等官方字段；视频兼容端点只接受 prompt / images / seconds / metadata 等字段。把 content 直接发到视频兼容端点、或把 prompt 发到官方端点，都不会按你期望的语义工作。两套协议的响应结构和状态枚举也不同，不要用同一套解析代码硬套。

2. Seedance 官方协议

2.1 创建任务

以下示例生成 4 秒、480p、16:9、无音频的视频，适合先验证链路：

bash

curl "$CIYUAN_BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261023-001" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "一只橘猫在窗边看雨，镜头缓慢推进，电影感光影"}
    ],
    "duration": 4,
    "resolution": "480p",
    "ratio": "16:9",
    "generate_audio": false
  }'

创建成功只表示平台已接收任务，返回公开任务 ID：

json

{"id": "task_xxxxxxxxx"}

任务 ID 由平台生成，不是上游任务 ID，不要拼到上游地址上使用。
Idempotency-Key 用于避免客户端超时重试造成重复任务和重复扣费：同一次业务提交复用同一个值，新的生成意图使用新值。相同 Key 配不同请求会返回 409 idempotency_conflict。
官方创建请求正文上限 64 MiB（约 64 MB）；大素材请使用素材库或公网 HTTPS URL。
旧前缀 /doubao/api/v3/contents/generations/tasks 仍作为兼容入口保留，新项目请使用 /api/v3/contents/generations/tasks，不要在两套前缀之间混用查询。

2.2 查询任务

bash

curl "$CIYUAN_BASE_URL/api/v3/contents/generations/tasks/task_xxxxxxxxx" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

状态	含义	处理
`queued`	已接收，等待生成	继续轮询
`running`	上游正在生成	继续轮询
`succeeded`	生成成功	读取 `content.video_url`
`failed`	失败	读取 `error`，调整后重试
`cancelled`	已取消	停止轮询
`expired`	任务记录已过期	重新提交

成功响应示例：

json

{
  "id": "task_xxxxxxxxx",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "video_asset_id": "asset_xxxxxxxxx"
  },
  "usage": {"completion_tokens": 38830, "total_tokens": 38830},
  "created_at": 1787827200,
  "updated_at": 1787827300
}

最终费用按 usage.total_tokens 结算。
平台开启结果归档后，content.video_asset_id 表示结果已归档到当前账号的素材库；归档可能比生成终态稍晚完成，未立即出现时稍后重新查询即可。
失败任务在后台确认后会执行异步退款，但提交成功不等于视频生成成功，仍以任务状态为准。

2.3 content 类型与素材角色

content 是有序数组，按顺序描述提示词和参考素材：

`type`	可接受来源	可用 `role`
`text`	UTF-8 文本	无
`image_url`	公网 https、图片 data URL、`asset://` 素材	`first_frame`、`last_frame`、`reference_image`
`video_url`	公网 https、`asset://` 素材（不支持 Base64）	`reference_video`
`audio_url`	公网 https、音频 data URL、`asset://` 素材	`reference_audio`
`draft_task`	当前账号可访问的 `task_xxx`	无

json

{"type":"image_url","image_url":{"url":"https://example.com/first-frame.png"},"role":"first_frame"}

role 与 type 位于同一层级；一个元素只能表达一种内容类型。
asset:// 只能引用当前用户拥有且状态有效的素材；未开启素材引用能力时返回 asset input is not enabled。
官方端点会拒绝未知顶层字段和未知 content 字段，返回 400 invalid_request，字段名必须与文档一致。

2.4 生成参数

参数	必填	说明
`model`	是	使用第 1 节的模型 ID
`content`	是	有序内容数组；至少包含一个内容元素
`duration`	否	2.0：`-1` 或 4～15；2.5：`-1` 或 4～30
`resolution`	否	如 `480p`、`720p`；更高规格取决于模型与渠道
`ratio`	否	`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`
`generate_audio`	否	是否生成音频
`omni_reference_task_type`	否	仅 2.5：`auto`、`reference`、`edit`、`extend`
`callback_url`	否	任务终态回调地址；需平台开启回调能力且为公网 http(s) 地址
`return_last_frame`	否	返回末帧；平台开启结果归档后，成功响应中可能出现 `last_frame_url` / `last_frame_asset_id`
`execution_expires_after`	否	任务执行过期时间，单位秒，范围 3600～259200
`seed` / `watermark` / `camera_fixed`	否	随机种子 / 水印 / 固定镜头
`draft` / `frames` / `tools` / `output_format` / `service_tier` / `priority` / `safety_identifier`	否	进阶参数，是否生效取决于模型与渠道

平台会在扣费和提交上游前校验时长、比例与 2.5 任务类型组合；不支持的组合返回 400 unsupported_parameter_combination。
ratio 只能传标准值；生成成功后上游返回的实际比例可能是 427:240 这样的分数，请按字符串保存，不要强制拉伸成 16:9。
分辨率、模型能力与计费档位以控制台模型说明和账单为准。

2.5 视频参考与编辑（Seedance 2.5）

用 omni_reference_task_type 声明全模态参考子任务（2.5 首帧任务显式传 ratio 时必须是 adaptive），不存在 edit: true 字段：

场景	`omni_reference_task_type`	参数要求
参考动作/风格/镜头重新生成	`reference`	至少一个参考素材；常规 `ratio`、`duration`
修改参考视频画面或声音	`edit`	至少一个 `reference_video`；`ratio=adaptive`；`duration=-1`
延长参考视频	`extend`	至少一个 `reference_video`；`ratio=adaptive`
由模型自动判断	`auto` 或不传	含参考视频时平台要求 `adaptive` 与 `-1`

bash

curl "$CIYUAN_BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "把参考视频中人物的外套改成红色，保留原有动作、运镜和声音"},
      {"type": "video_url", "video_url": {"url": "https://example.com/source.mp4"}, "role": "reference_video"}
    ],
    "duration": -1,
    "ratio": "adaptive",
    "omni_reference_task_type": "edit"
  }'

需要固定输出比例或时长时请显式传 reference；提示词应写清修改对象、修改内容，以及必须保留的动作、镜头和声音。

2.6 查询、列表与删除

查询单个任务见 §2.2。列表和删除示例：

bash

curl "$CIYUAN_BASE_URL/api/v3/contents/generations/tasks?page_num=1&page_size=10&filter.status=succeeded" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

curl -X DELETE "$CIYUAN_BASE_URL/api/v3/contents/generations/tasks/task_xxxxxxxxx" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

列表返回 {"items": [...], "total": N}，按 created_at 倒序排列。
可用的 filter.status 与任务状态一致：queued、running、succeeded、failed、cancelled、expired。
删除成功返回 204 No Content：排队中的任务会被取消；已结束的任务会先删除上游任务，再软删平台记录；运行中返回 409 task_cannot_be_cancelled，已取消返回 409 task_already_cancelled。
任务 ID 只对创建它的账号可见，不能查询或删除其他用户的任务。

2.7 下载结果

任务成功后优先读取 content.video_url。上游地址可能有时效，建议尽快下载或转存；也可以用同一令牌让平台代理下载：

bash

curl -L "$CIYUAN_BASE_URL/v1/videos/<task_id>/content" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -o output.mp4

该端点支持 Range，可断点续传；仅在任务成功（官方 succeeded / OpenAI Videos 风格 completed）后调用。

2.8 签名回调

创建官方任务时传入 callback_url（需平台开启回调能力），平台会在任务进入终态（succeeded / failed / cancelled / expired）后向该地址发送 HTTP POST：

Header	用途
`X-Seedance-Event-Id`	事件唯一 ID，接收端应按此字段去重
`X-Seedance-Timestamp`	签名时间戳（Unix 秒）
`X-Seedance-Signature`	`v1=<hex>` 格式的 HMAC-SHA256 签名

签名原文为 timestamp + "." + raw_body。当前使用创建任务时的 API Key 作为签名密钥。必须对收到的原始请求体做验签，不要重新序列化 JSON 后再计算。

import crypto from 'node:crypto'

export function verifySeedanceWebhook(rawBody, headers, signingSecret) {
  const timestamp = headers['x-seedance-timestamp']
  const received = headers['x-seedance-signature']
  const expected = 'v1=' + crypto
    .createHmac('sha256', signingSecret)
    .update(timestamp + '.' + rawBody)
    .digest('hex')

  return typeof received === 'string' &&
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
}

回调正文包含 id、type、created_at 和 data；type 为 content_generation.task.{status}，data 为任务快照，字段与官方任务查询响应相近；归档相关字段可能只在查询时补齐。
平台采用至少一次投递语义；请按 X-Seedance-Event-Id 幂等处理，并在验签、持久化后尽快返回 2xx。
不需要事件通知时，使用轮询即可；轮询与回调可以同时开启。

3. 视频兼容协议

视频兼容协议面向已有 OpenAI 视频客户端或统一任务封装。它是平台额外提供的兼容层，不是 Seedance 官方协议。

3.1 端点与选择

操作	旧兼容入口	OpenAI Videos 风格
创建任务	`POST /v1/video/generations`	`POST /v1/videos`
查询任务	`GET /v1/video/generations/{task_id}`	`GET /v1/videos/{id}`
下载结果	`GET /v1/videos/{task_id}/content`	同左

两个入口的响应结构不同（见 §3.4），请固定使用一种入口创建和查询，不要在一个流程里混用。只有 OpenAI Videos 风格入口使用 queued / in_progress / completed / failed，其中 completed 对应官方协议的 succeeded；旧兼容入口查询返回的是平台内部状态（如 IN_PROGRESS / SUCCESS / FAILURE），不要按 completed 判断终态。

3.2 创建任务

bash

curl "$CIYUAN_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "海边日出，镜头缓慢推进，海浪轻拍礁石，电影感",
    "seconds": "4",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": false
    }
  }'

创建成功响应示例（旧兼容入口）：

json

{
  "id": "task_xxxxxxxxx",
  "task_id": "task_xxxxxxxxx",
  "status": "queued",
  "model": "doubao-seedance-2-5-260628",
  "created_at": 1787827200
}

如果使用 OpenAI Videos 风格入口，创建响应为视频对象（没有 task_id）：

json

{
  "id": "task_xxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0,
  "created_at": 1787827200
}

创建成功只表示任务已接收，响应中不会包含视频地址。

3.3 请求参数

字段	说明
`model`	必填，模型 ID
`prompt`	必填，提示词
`images`	参考图 URL 数组。OpenAI Videos 风格路径只接受 `images`，不要传单张 `image`
`image`	旧兼容入口支持的单张图片 URL（内部会转成 `images`）；新代码建议统一使用 `images`
`seconds`	字符串时长，如 `"4"`、`"-1"`；与 `duration` 同时出现时优先
`duration`	整数时长。OpenAI Videos 风格入口可替代 `seconds`；旧兼容入口只读取 `seconds`，`duration` 会被忽略
`metadata`	透传官方参数：`content`、`resolution`、`ratio`、`generate_audio`、`omni_reference_task_type` 等

resolution、ratio、generate_audio 等参数必须放在 metadata 里，放在顶层会被忽略。
参考图、视频或音频放在 metadata.content，不要放 text；提示词统一写在 prompt。需要首帧 role 时，用 metadata.content 显式写 image_url + role: "first_frame"。
兼容协议不支持二进制文件上传，素材必须是公网 URL；需要复用素材时请使用官方协议 + 素材库。
顶层 content 不会让兼容端点返回参数错误，而是被忽略。需要多模态参考时，请放 metadata.content 或改用官方协议。

3.4 查询状态与下载

OpenAI Videos 风格入口返回视频对象，状态为 queued → in_progress → completed（或 failed）：

bash

curl "$CIYUAN_BASE_URL/v1/videos/task_xxxxxxxxx" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

json

{
  "id": "task_xxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "completed",
  "progress": 100,
  "created_at": 1787827200,
  "completed_at": 1787827300
}

旧兼容入口返回通用任务结构，结果地址在 data.result_url（字段可能不存在，以下载端点为准）：

bash

curl "$CIYUAN_BASE_URL/v1/video/generations/task_xxxxxxxxx" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

json

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxx",
    "status": "IN_PROGRESS",
    "progress": "60%"
  }
}

结果地址不要从查询响应里找

/v1/videos/{task_id} 的响应不包含 metadata.url、task_id 或视频地址；旧兼容入口的结果地址在 data.result_url，该字段可能不存在。请统一使用 GET /v1/videos/{task_id}/content 下载。

bash

curl -L "$CIYUAN_BASE_URL/v1/videos/task_xxxxxxxxx/content" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -o output.mp4

该端点支持 Range，可断点续传；下载需使用创建任务时的同一账号下的令牌（同账号的任意有效令牌均可）。

3.5 选择建议

新项目、需要首尾帧、参考音视频、2.5 编辑/延长或素材库复用时，使用 Seedance 官方协议。
已有 OpenAI 视频工具、只需要文生视频/图生视频时，使用视频兼容协议；确认某个参数没有生效时，改用官方协议。
无论选择哪套协议，生产系统都应保存 task_xxx、模型、关键生成参数和错误信息，便于核对状态、计费与重试。

4. 素材库（官方 Assets API）

素材库用于把参考图、参考视频、参考音频先导入平台，再用 asset://<素材 ID> 在官方协议任务中反复引用，适合同一个素材多次使用、或上游无法直接拉取外链的场景。

素材和分组均归属于当前用户，其他用户无法查看、修改、删除或通过 asset:// 引用你的素材。

素材库使用火山 Assets API 的 Action 风格：所有操作都 POST 到固定路径，Action 和 Version 放在查询参数中。不要把 Action 拼成普通 REST 路径（如 /api/v3/assets/CreateAsset），否则会返回 404。

text

POST https://ai.afp.net/api/v3/assets?Action=<Action>&Version=2024-01-01
Authorization: Bearer sk-xxx
Content-Type: application/json

当前兼容 12 个 Action：

分类	Action
分组	`CreateAssetGroup`、`ListAssetGroups`、`GetAssetGroup`、`UpdateAssetGroup`、`DeleteAssetGroup`
素材	`CreateAsset`、`ListAssets`、`GetAsset`、`UpdateAsset`、`DeleteAsset`
真人校验	`CreateVisualValidateSession`、`GetVisualValidateResult`

Version 必须是 2024-01-01；Action 不支持返回 InvalidAction，版本不对返回 InvalidVersion。响应统一包在 ResponseMetadata 中，业务数据在 Result，错误在 ResponseMetadata.Error。真人校验能力当前未对接上游，参数齐全时返回 OperationDenied.CapabilityNotSupported。

4.1 创建分组并导入素材

bash

curl "$CIYUAN_BASE_URL/api/v3/assets?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name":"项目素材","GroupType":"AIGC","ProjectName":"default"}'

curl "$CIYUAN_BASE_URL/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"<上一步返回的分组 ID>",
    "Name":"首帧",
    "AssetType":"Image",
    "URL":"https://example.com/first-frame.png",
    "ProjectName":"default"
  }'

CreateAssetGroup 响应示例：

json

{
  "ResponseMetadata": {"RequestId": "req-xxxxxxxx", "Action": "CreateAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {"Id": "group-xxxxxxxx"}
}

CreateAsset 返回 Result.Id（素材 ID）。
AssetType 只能是 Image、Video、Audio，且必须与 URL 实际媒体类型一致。
GroupType 当前只支持 AIGC；ProjectName 省略时为 default，最长 64 字节（UTF-8）。
URL 必须是平台可访问的公网 http(s) 地址；平台会做 SSRF 校验，localhost 和内网地址会被拒绝。

4.2 在生成任务中引用素材

素材导入后，在官方协议的 content 中用 asset://<素材 ID> 代替 URL：

json

{"type":"image_url","image_url":{"url":"asset://asset_xxxxxxxx"},"role":"first_frame"}

asset:// 需要平台开启素材引用能力；未开启时返回 asset input is not enabled，此时改用公网 http(s) URL。
素材类型必须与 content 项匹配（图片对 image_url、视频对 video_url、音频对 audio_url）。
引用素材的任务必须使用导入素材时的同一账号令牌。

4.3 管理素材（REST / 控制台）

除 Action 接口外，平台还提供内部 REST 接口，控制台和自动化工具使用：

text

POST   /api/v3/assets                              上传文件或按公网 URL 导入
GET    /api/v3/assets                              分页、搜索并筛选素材
GET    /api/v3/assets/{asset_id}                   素材详情
PATCH  /api/v3/assets/{asset_id}                   重命名或调整分组
DELETE /api/v3/assets/{asset_id}                   删除素材
GET    /api/v3/assets/{asset_id}/content           下载 / 探测文件（支持 Range）
HEAD   /api/v3/assets/{asset_id}/content           探测文件
POST   /api/v3/assets/{asset_id}/prepare           为模型准备/注册上游素材（请求体需带 model）
POST   /api/v3/assets/from-task                    将任务结果归档为素材

POST   /api/v3/asset-groups                        创建分组
GET    /api/v3/asset-groups                        列出分组
GET    /api/v3/asset-groups/{group_id}             分组详情
PATCH  /api/v3/asset-groups/{group_id}             重命名分组
DELETE /api/v3/asset-groups/{group_id}             删除分组

旧版路径 /api/media/assets、/api/media/asset-groups 仍然保留。

REST 接口同时接受控制台登录态和 API Key；自动化程序请使用 Authorization: Bearer sk-xxx。
/api/media/assets 列表支持 page_num、page_size、q、kind 和 group_id 参数；上传接口支持 multipart 文件或 url 公网导入。
控制台「素材库」支持上传、预览、下载、复制 asset:// 引用、编辑名称/分组和删除；列表可按名称、类型、分组筛选。
单文件上限 512 MB；平台会校验真实 MIME 类型并保存 SHA-256。
素材库权限分为查看、上传、管理、删除和归档；无权限时按钮不可见或请求返回 403。

4.4 保留期、隔离与上游绑定

分组记录长期保留，直到显式删除；DeleteAssetGroup 要求组内没有未过期素材，否则返回 OperationDenied.AssetGroupNotEmpty。
平台素材默认保留 7 天，可由部署方配置为长期保留。素材管理接口或控制台中的 expires_at 是 Unix 秒时间戳；到期后素材不再出现在列表中，也不能继续用于生成任务。到期清理只删除平台元数据，底层对象由对象存储（S3 / Tencent COS 兼容）的生命周期规则回收。
素材和分组按用户 + ProjectName 隔离，其他用户不可查询或复用；默认项目名为 default。
平台素材只保存在词元探索，不同步到上游。任务选路时先检查候选渠道是否支持所需的图片/视频/音频能力，选中渠道后再为该次任务按需注册临时上游素材。
上游绑定默认是单次使用，任务结束后上游可自行删除；即使配置复用，TTL 也不会超过上游保留期。仅支持拉取 URL 的上游会直接使用平台短效 URL。因此素材不会预先绑定某个上游，多渠道之间可以自由切换。
虚拟素材、私域真人、真人认证、更新/删除等能力由管理员按渠道配置；当前上游不支持私域真人素材，相关 Action 会返回 OperationDenied.CapabilityNotSupported，而不是 404。
GetAsset / ListAssets 返回的 URL 是平台签发的临时地址（默认 1 小时），不能当作永久外链保存。
被进行中任务引用的素材不能删除，会返回 OperationDenied.AssetInUse。

5. 异步流程、轮询与计费

提交只代表任务入队。推荐流程：

提交并保存返回的任务 ID 与完整请求参数（建议官方协议同时带 Idempotency-Key）。
每 5 秒查询一次，逐步退避到 15～30 秒；不要高频轮询。
进入成功终态（官方 succeeded / OpenAI Videos 风格 completed）后下载；failed 读取 error 后停止重试。
状态变为 expired 表示记录已过期（上游记录可能已不可查），需要重新提交；结果地址有有效期，成功后尽快下载。

Python 轮询示例（官方协议）：

python

import os, time, requests

BASE = os.environ["CIYUAN_BASE_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['CIYUAN_API_KEY']}"}

created = requests.post(f"{BASE}/api/v3/contents/generations/tasks", headers=HEADERS, json={
    "model": "doubao-seedance-2-5-260628",
    "content": [{"type": "text", "text": "一只橘猫在窗边看雨，镜头缓慢推进"}],
    "duration": 4, "resolution": "480p", "ratio": "16:9", "generate_audio": False,
})
created.raise_for_status()
task_id = created.json()["id"]
print("task:", task_id)

delay = 5
while True:
    info = requests.get(
        f"{BASE}/api/v3/contents/generations/tasks/{task_id}", headers=HEADERS
    ).json()
    status = info.get("status")
    print("status:", status)
    if status == "succeeded":
        url = info["content"]["video_url"]
        break
    if status in ("failed", "cancelled", "expired"):
        raise RuntimeError(info.get("error") or status)
    time.sleep(delay)
    delay = min(delay * 1.5, 30)

video = requests.get(url, timeout=120)
video.raise_for_status()
open("output.mp4", "wb").write(video.content)
print("saved output.mp4")

计费按上游返回的 usage.total_tokens 和模型、输入类型、分辨率计算；提交时可能预扣，失败后异步退款。最终以控制台账单为准。

6. 常见错误与排查

错误	常见原因	处理
`401 Unauthorized`	Key 无效、过期或缺少请求头	检查 Bearer 与 Key 状态
`No available channel for model`	模型未开放、渠道未启用、分组无权限	先查 `/v1/models`
`503 channel_not_available`	官方协议找不到 Seedance 兼容渠道	检查渠道配置与分组
`400 invalid_request`	`content` 缺失、JSON 错误、未知字段、`asset input is not enabled`	检查字段名与类型
`400 unsupported_parameter_combination`	时长、比例、任务类型组合不支持	按 2.4 / 2.5 调整
`403 OperationDenied.CapabilityNotSupported`	素材库整体未开启（Action 请求）	联系管理员开启素材库能力
`400 OperationDenied.CapabilityNotSupported`	当前上游不支持该素材/能力（如私域真人）	改用支持的素材类型或渠道
`404 not_found`	官方任务 API 未开启，或素材库 REST 路由未开启	确认平台已开启对应能力
`413 asset_too_large`	上传文件超过 512 MB	压缩素材或改用公网 URL
`asset_not_found` / `asset_not_active`（REST 管理接口）	素材已删除、归属他人或尚不可用	回到素材库确认并重新复制引用
`invalid_asset` / `asset_not_supported`（任务引用素材）	`asset://` 类型不匹配、素材不可用或当前渠道不支持	检查素材归属/类型，或改用支持该能力的渠道
`409 task_cannot_be_cancelled`	运行中的任务不能取消	等待终态或停止轮询
一直 `queued`	上游排队或渠道切换	继续轮询，超过业务超时再重试
任务 `failed`	参数、内容审核或上游异常	保存 `error`，调整后重新提交
结果地址不可用	任务未完成或地址过期	确认成功状态；尽快下载或用 content 端点代理
回调签名不一致	请求体被重新序列化、密钥错误或时间戳未使用原始值	使用原始 body + timestamp 计算 HMAC，并检查 `v1=` 前缀

官方协议和视频兼容怎么选？

需要首尾帧、参考音视频、2.5 编辑/延长、素材库或签名回调时用官方协议；已有 OpenAI 视频工具、只需要文生/图生视频时用兼容协议。两套协议的端点与字段不能混用。

上一页：图像生成 · 返回：帮助中心

视频生成 API（豆包 Seedance） ​

1. 模型与端点 ​

1.1 模型 ​

1.2 端点总览 ​

2. Seedance 官方协议 ​

2.1 创建任务 ​

2.2 查询任务 ​

2.3 content 类型与素材角色 ​

2.4 生成参数 ​

2.5 视频参考与编辑（Seedance 2.5） ​

2.6 查询、列表与删除 ​

2.7 下载结果 ​

2.8 签名回调 ​

3. 视频兼容协议 ​

3.1 端点与选择 ​

3.2 创建任务 ​

3.3 请求参数 ​

3.4 查询状态与下载 ​

3.5 选择建议 ​

4. 素材库（官方 Assets API） ​

4.1 创建分组并导入素材 ​

4.2 在生成任务中引用素材 ​

4.3 管理素材（REST / 控制台） ​

4.4 保留期、隔离与上游绑定 ​

5. 异步流程、轮询与计费 ​

6. 常见错误与排查 ​

视频生成 API（豆包 Seedance）

1. 模型与端点

1.1 模型

1.2 端点总览

2. Seedance 官方协议

2.1 创建任务

2.2 查询任务

2.3 content 类型与素材角色

2.4 生成参数

2.5 视频参考与编辑（Seedance 2.5）

2.6 查询、列表与删除

2.7 下载结果

2.8 签名回调

3. 视频兼容协议

3.1 端点与选择

3.2 创建任务

3.3 请求参数

3.4 查询状态与下载

3.5 选择建议

4. 素材库（官方 Assets API）

4.1 创建分组并导入素材

4.2 在生成任务中引用素材

4.3 管理素材（REST / 控制台）

4.4 保留期、隔离与上游绑定

5. 异步流程、轮询与计费

6. 常见错误与排查