跳转到正文
阅读设置
Seedance 原生协议
POST/api/v3/contents/generations/tasks

创建视频任务 ​

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.0doubao-seedance-2-0-2601284–15 秒480p、720p、1080p、4kmp4
Seedance 2.0 Fastdoubao-seedance-2-0-fast-2601284–15 秒480p、720pmp4
Seedance 2.0 Minidoubao-seedance-2-0-mini-2606154–15 秒480p、720pmp4
Seedance 2.5doubao-seedance-2-5-2606284–30 秒480p、720p、1080pmp4、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

请求字段 ​

字段类型必填说明
modelstring是模型 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。
contentarray<object>是文本提示词和参考素材
content[].typestring是text、image_url、video_url 或 audio_url
content[].textstring条件文本提示词
content[].image_url.urlstring条件图片 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.urlstring条件视频 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.urlstring条件音频 URL,使用 wav 或 mp3,单个不超过 15 MB。
2.0 系列单段时长 2~15 秒、最多 3 段,总时长不超过 15 秒;
2.5 单段时长 2~30 秒、最多 10 段,总时长不超过 30 秒。
content[].rolestring条件reference_image、reference_video、reference_audio、first_frame 或 last_frame
generate_audioboolean否是否生成音频
resolutionstring否480p、720p、1080p;2.0 标准版还支持 4k
ratiostring否21:9、16:9、4:3、1:1、3:4、9:16;2.5 还支持 adaptive
durationinteger否2.0:4–15 秒,不支持 -1;2.5 普通任务和首帧/首尾帧任务:4–30 秒或 -1;2.5 视频编辑必须为 -1,视频延长支持 4–30 秒或 -1
output_formatstring否仅 2.5 支持设置;可选 mp4、mov。2.0 输出格式固定为 mp4
watermarkboolean否是否添加“AI生成”水印
return_last_frameboolean否是否返回视频尾帧图
draftboolean否样片模式(仅 Seedance 2.5 支持)
omni_reference_task_typestring否2.5:auto、reference、edit、extend
toolsarray否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) ​

bash
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) ​

json
{
  "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。

json
{
  "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。

json
{
  "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。以下按明确比例和时长生成文生视频样片。

json
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "黄昏的海边,一只橘猫沿沙滩缓慢奔跑,镜头平稳跟随"
    }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5,
  "draft": true
}

创建响应 ​


json
{
  "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_audioratio、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.0Seedance 2.5
resolution标准版支持 480p、720p、1080p、4k;Fast/Mini 支持 480p、720p480p、720p、1080p
ratio21:9、16:9、4:3、1:1、3:4、9:16上述比例及 adaptive
duration4–15 秒,不支持 -1普通任务、首帧/首尾帧和视频延长支持 4–30 秒或 -1;视频编辑必须为 -1
output_format固定 mp4mp4 或 mov
watermarktrue / falsetrue / 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) ​

联网搜索仅适用于纯文本输入:

json
{
  "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 轮询示例 ​

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、调用地址和扩展行为仍以本文为准。