Seedance 1.0 API 模型解析指南
快速结论
- 通过 model 可选 fast/quality 两个 1.0 Pro 版本，覆盖速度优先与质量优先需求。
- 统一入口 POST /v1/videos/generations，支持首帧、尾帧与参考图控制（按版本限制）。
- 支持异步任务流程，提交后返回任务 ID，再通过任务状态接口轮询结果。
核心能力
- 双版本策略：速度与质量分层：同一接口可选择 doubao-seedance-1-0-pro-fast 或 quality，便于按业务时延目标切换。
- 首帧/尾帧/参考图精细控制：通过 image_urls 或 image_with_roles 控制视频起止画面与风格参考，提升镜头可控性。
- 标准化异步任务交付：返回 generation.task 对象并提供状态流转，适合接入队列与批处理工作流。
适用场景
- 需要在较短时延内完成短视频生成并快速迭代提示词。
- 需要通过首帧/尾帧或参考图增强镜头连续性与风格一致性。
- 需要标准化异步任务状态管理来接入服务端生产流程。
不适用场景
- 需要超过 12 秒的单段视频输出时，应改用支持更长时长的模型。
- 需要强实时同步返回（非异步任务）时，不适合该接口形态。
运行特性
- 统一调用 POST /v1/videos/generations，返回任务对象（generation.task）而非直接视频文件。
- 支持 image_urls 或 image_with_roles，两者互斥，且角色图每种仅支持一张。
- quality 版本支持 last_frame；fast 版本不支持首尾帧同时使用。
- 使用 reference 角色图时，分辨率存在 1080p 限制，需按文档约束降级。
最小请求示例
{
"model": "doubao-seedance-1-0-pro-fast",
"prompt": "海滩日落，金色阳光照在海面上，海浪轻轻拍打沙滩",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
最小响应示例
{
"id": "task_vid_xxxxxxxx",
"object": "generation.task",
"model": "doubao-seedance-1-0-pro-fast",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
关键参数
| 参数 | 类型 | 必填 | 默认值 | 范围 | 说明 |
|---|
| model | string | 是 | doubao-seedance-1-0-pro-fast | doubao-seedance-1-0-pro-fast | doubao-seedance-1-0-pro-quality |
| prompt | string | 是 | - | - | 视频内容描述，建议明确场景、动作与风格。 |
| duration | integer | 否 | 5 | 2-12 | 视频时长（秒）。 |
| aspect_ratio | string | 否 | 16:9 | 16:9 | 9:16 |
| resolution | string | 否 | 720p | 480p | 720p |
| image_urls | string[] | 否 | - | - | 首帧图像 URL 数组；仅支持 URL，不支持 base64；与 image_with_roles 互斥。 |
| image_with_roles | array | 否 | - | - | 带角色图像数组（first_frame/last_frame/reference）；每种角色仅支持一张。 |
| metadata.seed | integer | 否 | - | -1 ~ 2^32-1 | 种子值，用于控制生成随机性。 |
常见错误
| HTTP | Code | 触发条件 | 修复建议 | 重试策略 |
|---|
| 400 | invalid_request_error | model、prompt 或时长/比例等参数缺失或格式不合法。 | 按文档校验必填字段与取值范围，重点检查 duration、aspect_ratio、resolution。 | 修正参数后重试。 |
| 401 | authentication_error | Authorization 缺失、格式错误或 API Key 无效。 | 确认 Bearer Token 与 API Key 权限。 | 修复鉴权后重试。 |
| 429 | rate_limit_exceeded | 请求频率、并发或当前额度命中上游限流策略。 | 先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。 | 建议 1s/2s/4s + 抖动；连续触发时再收紧提交节奏。 |
FAQ
- fast 和 quality 怎么选？
fast 适合快速预览与高频迭代；quality 适合对细节质量和画面稳定性要求更高的生产场景。
- 为什么我设置 1080p 失败？
使用 reference 角色图时不支持 1080p，请改为 720p 或调整图像控制方式。
- 首尾帧都能在 fast 里用吗？
不能。last_frame 仅 quality 版本支持，fast 版本不支持首尾帧同时使用。
- 图像视频模型报错：invalid apitype: -1
这类错误通常说明接口走错了。图像和视频模型一般不走 chat 接口，而是按对应文档发起 HTTP 任务请求，并通过任务状态接口轮询结果。排查时建议先看用户的实际请求代码、请求地址和请求体。
- 用户进行生成图片/视频的任务时出现任务失败，但是扣款
先让用户提供任务日志或截图，重点看是否出现了输入或输出 token 统计。如果有这类 token 记录，大概率是用户把图片/视频模型走成了 chat 接口；这不是正确用法。图片和视频模型通常是异步任务接口，需要通过 HTTP 请求先提交任务，再拿到任务 ID 轮询状态，详细以对应文档为准。
相关 API
