视频生成接口
异步提交，轮询取片。所有接口都在 /v1 下，鉴权走 Bearer。
鉴权
每个请求带一个 Bearer Key。Key 在控制台里创建，可以限制它每天能提交的任务数和允许的时长。
Authorization: Bearer your_api_key
缺 Key 或 Key 无效返回 401；Key 被禁用或过期返回 403。
提交任务
POST/v1/videos/generations
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
model必填 | string | 模型名，见 模型列表。不认识的名字直接拒绝，不会回落到默认模型。 |
prompt必填 | string | 提示词，1 到 12000 字符（上限以 GET /v1/models 返回的 max_prompt_chars 为准）。发送时原样带上，不做改写。 |
ratio | string | 画幅比例，可选 21:9、16:9、4:3、1:1、3:4、9:16；不传按 16:9 处理。 |
duration | integer | 时长（秒），必须落在这个模型允许的范围里，否则返回 422。 |
返回
返回
{
"id": "video_9f3c1a2b4d5e6f70",
"status": "queued",
"duration": 10,
"model": "seedance-2.0-fast"
}
拿到 id 之后轮询查询接口。任务由调度接管，期间不需要保持连接。
查询状态
GET/v1/videos/{task_id}
| 字段 | 说明 |
|---|---|
id | 任务 ID。 |
status | queued 排队中，running 生成中，completed 已完成，failed 失败。 |
model | 本次用的模型。 |
prompt | 提交时的提示词。 |
ratio | 画幅比例。 |
duration | 时长（秒）。 |
created_at | 创建时间，Unix 时间戳。 |
elapsed | 已耗时（秒），完成后是总耗时。 |
video_url | 仅 completed 出现。转成 H.264 的直链。 |
progress_message | 仅生成中出现。一句进度说明。 |
eta_seconds | 仅生成中出现。预计剩余秒数。 |
eta_human | 上一条的可读形式，例如「约 120 分钟」。 |
error | 仅 failed 出现。失败原因。 |
failure_code | 失败分类，便于程序判断。 |
模型列表
GET/v1/models
公开接口，不需要鉴权。返回每个模型支持的时长与单任务最长等待时间。
返回
{
"default_model": "seedance-2.0-fast",
"max_prompt_chars": 12000,
"supported_durations": [5, 10, 15],
"models": [
{ "id": "seedance-2.0-fast", "label": "Seedance 2.0 Fast", "durations": [5, 10, 15], "max_wait_seconds": 600 },
{ "id": "seedance-2.0-mini", "label": "Seedance 2.0 Mini", "durations": [5, 10, 15], "max_wait_seconds": 600 }
]
}
结果示例
下面这条是 10 秒档的真实返回：video_cf5561f4532cc6c8，转码后的 H.264 直链可以直接下载。
错误码
| HTTP | 含义 | 怎么处理 |
|---|---|---|
| 401 | Key 缺失或无效 | 检查 Authorization 头。 |
| 403 | Key 被禁用或已过期 | 换一个 Key，或者联系我们开通。 |
| 422 | 参数不合法 | 看返回里的 detail。模型与时长组合不对会走到这里。 |
| 429 | 超出该 Key 的每日额度 | 降低提交频率，或者提升额度。 |
| 503 | 服务暂时不可用 | 稍后重试，也可以看 /health 判断。 |
失败任务的 failure_code 取值：quota_exhausted、content_rejected、duration_unsupported、service_busy、generation_failed。
注意事项
- 时长越界在入口被拒。两条线都支持 5 / 10 / 15 秒，传别的数字直接 422，系统不会替你换组合。
- 内容审核在提交时进行，被拒时
error里带的是判定原因。 - 高峰时段任务较多，系统会自动排队处理，不占用你的重试次数。
- 成片统一转成 H.264 直链，不需要再处理格式。