创建视频任务
Seedance 采用异步任务模式:提交创建请求后获得任务 UUID,再通过查询接口轮询任务状态并获取视频地址。
本页适用于 Seedance 2.0、Seedance2.0 fast、Seedance 2.0 mini 和 Seedance 2.5。 以下分别说明各版本的参数、素材和示例;平台任务 ID、默认参数、查询和回调规则以本页说明为准。
请求认证
Authorization:必填,使用Bearer <YOUR_API_KEY>。Content-Type:必填,使用application/json。oss-id:可选,已配置并启用的本人自定义存储库UUID;仅在服务开放自定义存储功能时使用。oss-path:可选,与oss-id配合指定存储路径前缀;不传oss-id时不生效。 最多 128 个字符,使用英文字母、数字、下划线、连字符、点及/; 不允许..、单独的点目录或空目录段,首尾/会被去除。
模型与能力
| 模型 | Model ID | 时长 | 分辨率 | 输出格式 |
|---|---|---|---|---|
| Seedance 2.0 | doubao-seedance-2-0-260128 | 4–15 秒 | 480p、720p、1080p、4k | mp4 |
| Seedance 2.0 Fast | doubao-seedance-2-0-fast-260128 | 4–15 秒 | 480p、720p | mp4 |
| Seedance 2.0 Mini | doubao-seedance-2-0-mini-260615 | 4–15 秒 | 480p、720p | mp4 |
| Seedance 2.5 | doubao-seedance-2-5-260628 | 4–30 秒 | 480p、720p、1080p | mp4、mov |
两个版本均支持文生视频、首帧/首尾帧生视频、图片或视频参考、视频编辑、视频延长、生成有声视频和水印。
2.5 另外支持最多 50 个全模态参考素材、纯音频参考、adaptive 比例、duration: -1 和 omni_reference_task_type。
模型与任务类型
Seedance 2.0 系列
- 文生视频:提交文本提示词。
- 首帧生视频:提交 1 张首帧图片,可附文本提示词。
- 首尾帧生视频:提交 1 张首帧和 1 张尾帧图片,可附文本提示词。
- 多模态参考:提交参考图片、视频、音频及可选提示词。音频参考必须搭配至少一张参考图片或一个参考视频,不能只提交音频。
Seedance 2.5
- 文生视频:提交文本提示词,显式指定输出比例和时长。
- 参考生视频:提交参考图片、视频或音频及可选提示词;允许只提交参考音频。 建议显式设置
omni_reference_task_type: "reference",并指定输出比例和时长。 - 样片模式:在支持的输入组合上设置
draft: true,使用480p生成预览; 成功样片可通过draft_task引用用于新的正式视频任务。
当前平台范围
请按控制台已开通的模型能力调用。当前平台不支持 ratio=adaptive 或 duration=-1, 因此不能直接使用火山官方的自动比例或智能时长示例。 2.5 的首帧、首尾帧、视频编辑和视频延长任务要求 adaptive,暂不在本平台支持范围内。 2.0 首帧、首尾帧仍可使用明确比例调用。各版本不要自行指定输出帧率。
创建任务
POST /api/v3/contents/generations/tasks
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID, seedance-2.0:标准版;对应 doubao-seedance-2-0-260128。 seedance-2.0-fast:快速版;对应 doubao-seedance-2-0-fast-260128。seedance-2.0-mini:轻量版;对应 doubao-seedance-2-0-mini-260615。seedance-2.5:2.5 版;对应 doubao-seedance-2-5-260628。 |
content | array<object> | 是 | 文本提示词和参考素材 |
content[].type | string | 是 | text、image_url、video_url 或 audio_url |
content[].text | string | 条件 | 文本提示词 |
content[].image_url.url | string | 条件 | 图片 URL,支持 jpeg、png、webp、bmp、tiff、gif、heic、heif。单张小于 30 MB,宽和高分别为 300~6000 px,宽高比为 0.4~2.5。 2.0 系列多模态参考最多 9 张,首帧模式为 1 张,首尾帧模式为 2 张; 2.5 参考生视频最多 30 张。 |
content[].video_url.url | string | 条件 | 视频 URL,使用 mp4 或 mov,视频编码为 H.264/AVC 或 H.265/HEVC。单个不超过 200 MB,帧率 24~60 fps,宽和高分别为 300~6000 px,宽高比为 0.4~2.5, 总像素数在 409,600~8,295,044 之间。 2.0 系列单个时长 2~15 秒、最多 3 个,总时长不超过 15 秒; 2.5 参考生视频单个时长 2~30 秒、最多 10 个,总时长不超过 30 秒。 |
content[].audio_url.url | string | 条件 | 音频 URL,使用 wav 或 mp3,单个不超过 15 MB。2.0 系列单段时长 2~15 秒、最多 3 段,总时长不超过 15 秒; 2.5 单段时长 2~30 秒、最多 10 段,总时长不超过 30 秒。 |
content[].role | string | 条件 | reference_image、reference_video、reference_audio、first_frame 或 last_frame |
generate_audio | boolean | 否 | 是否生成音频 |
resolution | string | 否 | 480p、720p、1080p;2.0 标准版还支持 4k |
ratio | string | 否 | 21:9、16:9、4:3、1:1、3:4、9:16;2.5 还支持 adaptive |
duration | integer | 否 | 2.0:4–15 秒,不支持 -1;2.5 普通任务和首帧/首尾帧任务:4–30 秒或 -1;2.5 视频编辑必须为 -1,视频延长支持 4–30 秒或 -1 |
output_format | string | 否 | 仅 2.5 支持设置;可选 mp4、mov。2.0 输出格式固定为 mp4 |
watermark | boolean | 否 | 是否添加“AI生成”水印 |
return_last_frame | boolean | 否 | 是否返回视频尾帧图 |
draft | boolean | 否 | 样片模式(仅 Seedance 2.5 支持) |
omni_reference_task_type | string | 否 | 2.5:auto、reference、edit、extend |
tools | array | 否 | 2.0 联网搜索:[{"type":"web_search"}],仅适用于纯文本输入 |
素材可通过 URL、Base64 或素材 URI 传入:图片支持三种方式,视频支持 URL 或素材 URI,音频支持 URL、Base64 或素材 URI。素材库 ID 必须写成 asset://<asset_id>,不能直接传裸 ID。提示词引用素材时,请使用“图片1”“视频1”“音频1”这类名称;序号按请求体中同类素材的出现顺序从 1 开始,不支持直接在提示词中使用 Asset ID。
输出规格
普通生成需要确定的分辨率、宽高比和时长。以下字段未传时使用模型已配置的默认值;未配置默认值时仍需显式提供,建议在请求中固定这些规格。
resolution:string,输出分辨率。支持的规格为:seedance-2.0支持480p、720p、1080p、4k;seedance-2.0-fast和seedance-2.0-mini支持480p、720p。seedance-2.5支持480p、720p、1080p;样片模式仅支持480p。素材组合与输出规格仍须所选模型支持。ratio:string,输出宽高比,可选16:9、4:3、1:1、3:4、9:16、21:9。 不支持adaptive自动比例。duration:integer,输出时长,单位秒。2.0 系列范围为 4~15 秒,2.5 为 4~30 秒。 当前平台不支持-1智能时长。
2.0/2.5 请求均使用 duration,不要提交 frames 或自行指定 framespersecond。 不能用帧数换算规则推定当前模型支持 frames。
可选生成参数
省略参数时可能使用平台配置或模型默认行为,不要把一种模型的选项和默认值直接套用到其他模型。
generate_audio:boolean,true请求生成与画面同步的音频,false请求无声视频。return_last_frame:boolean,true请求返回尾帧地址。watermark:boolean,是否请求添加水印。execution_expires_after:integer,任务执行有效期,单位秒,模型允许范围为 3600~259200。 常规接入建议省略以使用平台配置,不要将火山的 172800 秒默认值视为本平台的固定默认值。 此参数表示允许的执行时间,不是生成完成时间或产物链接有效期。priority:integer,取值 0~9,数值越大优先级越高。 仅影响同一推理队列内尚未运行任务的排序,不中断正在运行的任务,也不代表跨队列的优先保障。callback_url:string,可选的公网 HTTPS 回调地址,最长 2048 个字符。
Seedance 2.5 专属参数
以下字段仅用于 2.5,2.0 系列应省略:
omni_reference_task_type:string,参考任务类型。本平台参考生视频使用reference。 官方的edit、extend类型依赖自动比例或智能时长,当前不适用。 省略时模型会自动判定任务类型;提示词若表达编辑或延长意图,仍可能在受理后报错。draft:boolean,true开启样片模式,生成一段预览视频,用于确认场景结构、镜头调度、主体动作与 Prompt 意图是否符合预期。- 开启样片模式后,仅支持生成 480p 分辨率的 Draft 视频(使用其他分辨率会报错)。
false关闭样片模式,正常生成一段视频。
output_format:string,输出封装格式。本平台使用mp4;MOV 输出不在本文支持范围内。content[].draft_task.id:string,可引用的成功样片平台 UUID,详见样片复用。
不应提交的字段
2.0 和 2.5 创建请求均应省略 service_tier、seed、camera_fixed 和 frames。 2.0 还应省略 draft、output_format 和 omni_reference_task_type,也不能提交 draft_task 内容元素。 即使平台入口接受某个字段,也不代表目标模型接受。不要用空字符串代替省略。 任务列表的 filter.service_tier 是查询筛选参数,不应复制到创建请求体中。
空值和数据类型
JSON 字段传 null、空字符串、纯空白或字符串 "null" 时按未传处理; 0、false、空数组和空对象仍参与原有校验。布尔值和数值请使用 JSON 原生类型。 例如 duration 使用 5,不能使用 "5";generate_audio 使用 true,不能使用 "true"。
调用示例
文生视频(Seedance 2.5)
curl -X POST /api/v3/contents/generations/tasks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5-260628",
"content": [{"type": "text", "text": "一段高级、极具电影感的30秒3D动态图形序列,采用蒸汽朋克与复古微缩景观风格。"}],
"generate_audio": true,
"ratio": "16:9",
"duration": 30,
"output_format": "mp4"
}'全模态参考(Seedance 2.5)
{
"model": "doubao-seedance-2-5-260628",
"content": [
{"type": "text", "text": "全程使用视频1的第一视角构图,全程使用音频1作为背景音乐。"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/image.jpg"}},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/video.mp4"}},
{"type": "audio_url", "role": "reference_audio", "audio_url": {"url": "https://example.com/audio.mp3"}}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 11,
"omni_reference_task_type": "reference"
}首帧/首尾帧生视频
首帧任务必须在 content 中包含一个角色为 first_frame 的图片;首尾帧任务必须同时包含角色为 first_frame 和 last_frame 的图片。2.5 两类任务都必须将 ratio 设置为 adaptive。
{
"model": "doubao-seedance-2-5-260628",
"content": [
{"type": "text", "text": "镜头从首帧场景开始,平滑推进到尾帧场景。"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/first.jpg"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/last.jpg"}}
],
"ratio": "adaptive",
"duration": 10
}视频编辑与延长(Seedance 2.5)
视频编辑要求参考视频时长为 4–30 秒,并使用 ratio: "adaptive"、duration: -1、omni_reference_task_type: "edit"。视频延长使用 omni_reference_task_type: "extend",ratio 必须为 adaptive,duration 可设置为 4–30 或 -1。
{
"model": "doubao-seedance-2-5-260628",
"content": [
{"type": "text", "text": "视频编辑:删除视频1中的所有人,除了主角。"},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/source.mov"}}
],
"generate_audio": true,
"ratio": "adaptive",
"duration": -1,
"omni_reference_task_type": "edit",
"output_format": "mov"
}样片示例 (Seedance 2.5 )
样片用于预览,分辨率固定为 480p。以下按明确比例和时长生成文生视频样片。
{
"model": "doubao-seedance-2-5-260628",
"content": [
{
"type": "text",
"text": "黄昏的海边,一只橘猫沿沙滩缓慢奔跑,镜头平稳跟随"
}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5,
"draft": true
}创建响应
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}task_id 用于后续查询;当前创建响应中的 id 与 task_id 相同。
任务类型与参数约束
| 任务类型 | 触发方式 | 参数要求 |
|---|---|---|
| 文生视频 | 仅传文本提示词 | ratio、duration 无特殊限制 |
| 首帧任务 | 必须包含一个 first_frame 图片 | ratio 必须为 adaptive |
| 首尾帧任务 | 必须同时包含 first_frame 和 last_frame 图片 | ratio 必须为 adaptive |
| 参考生视频 | 至少一个 reference_image、reference_video 或 reference_audio | ratio、duration 无特殊限制 |
| 视频编辑 | reference_video 加编辑意图提示词 | ratio: "adaptive"、duration: -1;视频时长 4–30 秒 |
| 视频延长 | reference_video 加延长意图提示词 | ratio: "adaptive";duration 为 4–30 或 -1 |
使用全模态参考任务时,可通过 omni_reference_task_type 指定 auto、reference、edit 或 extend。未指定或使用 auto 时,模型会根据提示词和素材自动判断任务类型。
输出规格
| 参数 | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
resolution | 标准版支持 480p、720p、1080p、4k;Fast/Mini 支持 480p、720p | 480p、720p、1080p |
ratio | 21:9、16:9、4:3、1:1、3:4、9:16 | 上述比例及 adaptive |
duration | 4–15 秒,不支持 -1 | 普通任务、首帧/首尾帧和视频延长支持 4–30 秒或 -1;视频编辑必须为 -1 |
output_format | 固定 mp4 | mp4 或 mov |
watermark | true / false | true / false |
2.5 的视频编辑、视频延长和首帧/首尾帧任务必须使用 ratio: "adaptive"。2.0 标准版的 4K 输出采用 10bit/H.265 编码,部分播放器可能不兼容;2.5 的 1080p 同样使用 10bit/H.265。2.5 的 mov 更适用于视频编辑和视频延长,采用专业编码,部分播放器可能不兼容。watermark: true 会在视频右下角添加“AI生成”标识。
素材限制
Seedance 2.0
- 图片 0–9 张、视频 0–3 个、音频 0–3 个,总数最多 15 个。
- 不支持“文本+音频”或纯音频输入。
- 单次视频时长 4–15 秒;2.0 标准版支持 4K。
Seedance 2.5
- 图片最多 30 张、视频最多 10 个、音频最多 10 个,总数最多 50 个。
- 视频和音频参考素材总时长不超过 30 秒,支持纯音频参考。
- 视频编辑参考视频时长为 4–30 秒;支持 4–30 秒输出及
duration: -1。 - 图片支持 jpeg、png、webp、bmp、tiff、gif、heic、heif;视频支持 mp4、mov;音频支持 wav、mp3。
- 图片宽高比须为 0.4–2.5,宽高为 300–6000 px,单张不超过 30 MB。
- 视频支持 480p/720p、24–60 FPS,单个不超过 200 MB,宽高比为 0.4–2.5;普通参考视频时长 2–30 秒,编辑参考视频时长 4–30 秒。
- 音频单段时长 2–30 秒、单个不超过 15 MB;请求体大小不超过 64 MB。视频和音频参考总时长不超过 30 秒。
- 任务记录保存 7 天,视频 URL 保存 24 小时;Seedance 2.5 生成的视频 URL 最多下载 100 次。
联网搜索(Seedance 2.0)
联网搜索仅适用于纯文本输入:
{
"model": "doubao-seedance-2-0-260128",
"content": [{"type": "text", "text": "根据今天的天气生成一段城市宣传视频。"}],
"tools": [{"type": "web_search"}],
"ratio": "16:9",
"duration": 11
}实际搜索次数可在查询响应的 usage.tool_usage.web_search 中查看。
限流
官方在线推理限流参考:2.0 和 2.5 非 4K 任务企业用户最大 RPM 为 600、并发 10;个人用户最大 RPM 为 180、并发 3。2.0 标准版 4K 任务企业和个人用户最大 RPM 均为 15、最大并发均为 1。实际账户限额以服务端返回为准。
Python 轮询示例
import time
import requests
BASE = "https://openapi.yhsapi.com"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
"model": "doubao-seedance-2-5-260628",
"content": [
{
"type": "text",
"text": "一只橘猫在键盘上奔跑,镜头跟随。",
}
],
"ratio": "16:9",
"duration": 5,
"generate_audio": True,
}
task = requests.post(
f"{BASE}/api/v3/contents/generations/tasks",
headers=HEADERS,
json=payload,
timeout=30,
).json()
task_id = task.get("task_id") or task["id"]
while True:
result = requests.get(f"{BASE}/api/v3/contents/generations/tasks/{task_id}", headers=HEADERS, timeout=30).json()
if result["status"] == "succeeded":
print(result["content"]["video_url"])
break
if result["status"] == "failed":
raise RuntimeError(result.get("error"))
time.sleep(10)常见问题 [#常见问题]
为什么任务长时间处于 queued 或 running? 视频生成属于异步任务。请按约 10–30 秒间隔轮询;官方示例使用过 10 秒或 30 秒间隔,实际频率应结合账号限流设置。任务进入 succeeded 后再读取 content.video_url。
为什么视频地址无法长期访问? 视频 URL 保存 24 小时;Seedance 2.5 生成的视频 URL 最多下载 100 次,任务记录保存 7 天。任务成功后请尽快下载或转存视频。
2.0 和 2.5 如何选择? 两个版本都支持图片、视频、音频等多模态参考。需要 4K 使用 Seedance 2.0 标准版;需要单次最长 30 秒、最多 50 个参考素材、纯音频参考、duration: -1 或 mov 输出时使用 Seedance 2.5。
为什么任务会在创建后异步失败? Seedance 2.5 的全模态参考任务和首帧/首尾帧任务会在任务启动后继续校验任务类型与参数。视频编辑必须使用 ratio: "adaptive"、duration: -1,首帧/首尾帧任务必须使用 ratio: "adaptive";不满足约束时可能返回 InvalidParameter.TaskTypeConstraint。明确任务类型时可通过 omni_reference_task_type 提前校验。
duration: -1 会生成多长的视频? 对视频编辑任务,模型会尽量保持与待编辑视频相同的时长;其他 2.5 任务会在 4–30 秒范围内根据提示词和素材自动选择时长。
协议参考
火山方舟:创建视频生成任务。 官方页面涵盖多个模型版本,请按字段的“模型支持”说明选取 2.0 或 2.5 参数; 本平台的认证、任务 ID、调用地址和扩展行为仍以本文为准。

