创建视频生成任务 API

本文介绍创建视频生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片及文本信息生成视频，待生成完成后，您可以按条件查询任务并获取生成的视频。

模型能力

Doubao Seedance 2.5（有声视频 / 无声视频）
多模态参考生视频：输入参考图片（0~30 张）+ 参考视频（0~10 个）+ 参考音频（0~10 个）+ 文本提示词（可选）生成 1 个目标视频。支持仅传入音频，支持生成全新视频、编辑视频、延长视频，支持 30 秒视频连贯直出。
图生视频-首尾帧：输入首帧图片 + 尾帧图片 + 文本提示词（可选）生成 1 个目标视频。
图生视频-首帧：输入首帧图片 + 文本提示词（可选）生成 1 个目标视频。
文生视频：输入文本提示词生成 1 个目标视频。

注意图生视频 - 首帧、图生视频 - 首尾帧、多模态参考生视频（包括参考图、视频、音频）为 3 种互斥场景，不可混用。多模态参考生视频可通过提示词指定参考图片作为首帧 / 尾帧，间接实现「首尾帧 + 多模态参考」效果。若需严格保障首尾帧和指定图片一致，优先使用图生视频 - 首尾帧（配置 role 为 first_frame / last_frame）。

任务类型与特殊限制

Seedance 2.5 会根据参数 content.role 取值和提示词意图，将请求判定为 文生视频、参考生视频、视频编辑、视频延长、首帧/首尾帧生视频 这 5 种任务类型。

若任务类型为 视频编辑、视频延长、首帧/首尾帧生视频，模型对宽高比和时长参数有特殊限制，违反限制将触发异步报错。
若任务类型为 文生视频、参考生视频，模型对宽高比和时长参数无特殊限制；但需避免在参考生视频任务的提示词中出现与视频编辑、延长相关的词语，防止模型误判触发报错。

任务分类	任务触发条件（两级判定）	特殊限制
视频编辑	1. `content.role` 需设置为 `reference_image` / `reference_video` / `reference_audio` 2. 提示词触发关键词（包含其一即可）：编辑视频、增加/加上、删除/去掉、修改/替换/改成	- 宽高比：仅支持 `ratio` 为 `adaptive`，自动保持与待编辑视频一致，不支持另行设置 - 时长：仅支持 `duration` 为 `-1`，自动保持与待编辑视频时长基本一致，不支持自定义
视频延长	1. `content.role` 需设置为 `reference_image` / `reference_video` / `reference_audio` 2. 提示词触发关键词（包含其一即可）：向前/向后延长、延续、续写	- 宽高比：仅支持 `ratio` 为 `adaptive`，自动保持与待延长视频宽高比一致，不支持自定义
首帧/首尾帧生视频	`content.role` 需设置为 `first_frame` / `last_frame`	- 宽高比：仅支持 `ratio` 为 `adaptive`，模型自动匹配宽高比，不支持自定义

请求参数

请求信息

项	值
请求方法	POST
官方请求地址	https://ai-tokenhub.com/api/v3/contents/generations/tasks
Content-Type	application/json
鉴权方式	API Key 鉴权（Bearer Token）
任务数据保留期	7 天（从任务创建时间开始计算）

请求头

字段名	必填	说明
Authorization	✓	格式: `Bearer $YOUR_API_KEY`，其中 `$YOUR_API_KEY` 为您在天枢平台获取的长效 API 密钥
Content-Type	✓	固定值: `application/json`

请求体

model `string` 必选

您需要调用的模型的 ID（Model ID）。Seedance 2.5 的 Model ID 为 doubao-seedance-2-5-260628。

content `object[]` 必选

输入给模型、生成视频的信息，支持文本、图片、音频、视频、样片任务 ID 等多种类型的元素。

支持的输入组合：

文本
文本（可选）+ 图片
文本（可选）+ 视频
文本（可选）+ 音频（仅 Seedance 2.5 支持单独传入音频）
文本（可选）+ 图片 + 音频
文本（可选）+ 图片 + 视频
文本（可选）+ 视频 + 音频
文本（可选）+ 图片 + 视频 + 音频
样片任务 ID：样片指使用 Seedance 模型成功生成的样片视频，模型可基于样片生成高质量正式视频

信息类型

文本信息 object

输入给模型的提示词信息。

content.type string 必选：输入内容的类型，此处应为 text
content.text string 必选：输入给模型的文本提示词，描述期望生成的视频。

说明

提示词语言支持：所有模型均支持中英文提示词；Seedance 2.5 额外支持西班牙语、印度尼西亚语、葡萄牙语、日语、马来语、泰语、阿拉伯语、越南语、韩语。
提示词字数建议：中文提示词不超过 500 字，英文提示词不超过 1000 词。字数过多易导致信息分散，模型可能忽略细节、仅关注重点，进而造成视频缺失部分元素。
更多使用技巧：提示词的详细使用技巧，请参见 Seedance 提示词指南。

图片信息 object

输入给模型的图片信息。

属性：

content.type string 必选：输入内容的类型，此处应为 image_url。
content.image_url object 必选：输入给模型的图片对象。
content.image_url.url string 必选：图片 URL、图片 Base64 编码、素材 ID。
- 图片 URL：填入图片的公网 URL。
- Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式: data:image/<图片格式>;base64,<Base64编码>，注意 <图片格式> 需小写，如 data:image/png;base64,<Base64 image>。
- 素材 ID：用于视频生成的预置素材及虚拟人像的 ID，遵循格式：asset://<ASSET_ID>。详情见素材库使用指南。
传入单张图片要求
- 格式：jpeg、png、webp、bmp、tiff、gif、heic、heif
- 宽高比（宽/高）：[0.4, 2.5]
- 宽高长度（px）：[300, 6000]
- 大小：单张图片小于 30 MB。请求体大小不超过 64 MB。大文件请勿使用 Base64 编码。
图片数量：
- 图生视频-首帧：1 张
- 图生视频-首尾帧：2 张
- Seedance 2.5 多模态参考生视频：1-30 张
content.role string 条件必填：图片的位置或用途。

注意
图生视频-首帧、图生视频-首尾帧、多模态参考生视频（包括参考图、视频、音频）为 3 种互斥场景，不可混用。
多模态参考生视频可通过提示词指定参考图图片作为首帧/尾帧，间接实现"首尾帧+多模态参考"效果。若需严格保障首尾帧和指定图片一致，优先使用图生视频-首尾帧（配置 role 为 first_frame / last_frame）。

图生视频-首帧_字段 role 取值：需要传入 1 个 image_url 对象，字段 role 为 first_frame 或不填。

图生视频-首尾帧_字段 role 取值：需要传入 2 个 image_url 对象，且字段 role 必填。

首帧图片对应的字段 role 为：first_frame
尾帧图片对应的字段 role 为：last_frame

图生视频-参考图_字段 role 取值：必填，每张参考图对应的字段 role 均为：reference_image

说明

传入的首尾帧图片可相同。首尾帧图片的宽高比不一致时，以首帧图片为主，尾帧图片会自动裁剪适配。

视频信息 object

输入给模型的视频信息。

属性：

content.type string 必选：输入内容的类型，此处应为 video_url。
content.video_url object 必选：输入给模型的视频对象。
content.video_url.url string 必选：视频 URL、素材 ID。

视频 URL：

填入视频的公网 URL。
传入单个视频要求
- 视频格式：mp4、mov，支持编码格式见下表。
- 分辨率：480p、720p、1080p、4k
- 时长：非视频编辑任务单个视频时长 [2, 30] s；视频编辑任务单个视频时长 [4, 30] s。最多传入 10 个参考视频，所有视频总时长不超过 30 s。
- 尺寸：
  - 宽高比（宽/高）：[0.4, 2.5]
  - 宽高长度（px）：[300, 6000]
  - 总像素数：[614×664=407696, 3326×2494=8295044]，即宽和高的乘积符合 [407696, 8295044] 的区间要求。
- 大小：单个视频不超过 200 MB。
- 帧率（FPS）：[24, 60]

容器格式

容器格式	常用文件扩展名	MIME	支持编码
MP4	mp4	video/mp4	视频：H.264/AVC、H.265/HEVC；音频：AAC、MP3
QuickTime	mov	video/quicktime	视频：H.264/AVC、H.265/HEVC；音频：AAC、MP3、PCM

content.role string 条件必填：视频的位置或用途。当前仅支持 reference_video（参考视频）。

音频信息 object

输入给模型的音频信息。

说明：Seedance 2.5 支持仅传入音频，无需搭配图片 / 视频；也可配合图片 / 视频一起传入。

属性：

content.type string 必选：输入内容的类型，此处应为 audio_url。
content.audio_url object 必选：输入给模型的音频对象。
content.audio_url.url string 必选：音频 URL、音频 Base64 编码、素材 ID。

音频 URL：填入音频的公网 URL。
Base64 编码：将本地文件转换为 Base64 编码字符串，然后提交给大模型。遵循格式: data:audio/<音频格式>;base64,<Base64编码>，注意 <音频格式> 需小写，如 data:audio/wav;base64,<base64 audio>。
素材 ID：用于视频生成的虚拟人的音频素材 ID，遵循格式：asset://<ASSET_ID>。

传入单个音频要求

格式：wav、mp3
时长：单个音频时长 [2, 30] s，最多传入 10 段参考音频，所有音频总时长不超过 30 s。
大小：单个音频不超过 15 MB，请求体大小不超过 64 MB。大文件请勿使用 Base64 编码。

content.role string 条件必填：音频的位置或用途。当前仅支持 reference_audio（参考音频）。

样片信息 object

样片信息。基于样片任务 ID，生成正式视频。

属性：

content.type string 必选：输入内容的类型，此处应为 draft_task。
content.draft_task object 必选：输入给模型的样片任务对象。
content.draft_task.id string 必选：样片任务 ID，填写开启样片模式（draft: true）后创建任务所返回的 id，请勿误填 upstreamTaskId。
说明
- 使用分为两步：Step 1 调用本接口并设置 "draft": true 生成 Draft 视频；Step 2 若确认 Draft 视频符合预期，可基于 Step 1 返回的 Draft 视频任务 ID 调用本接口生成正式视频。
- 基于 Draft 视频生成正式视频时，部分参数由模型自动复用、部分参数禁止重复传入、部分参数可重新指定，详见 Seedance 2.5 样片模式说明。

callback_url `string`

填写本次生成任务结果的回调通知地址。当视频生成任务有状态变化时，将向此地址推送 POST 请求。

回调请求内容结构与查询任务 API 的返回体一致。

回调返回的 status 包括以下状态：

queued：排队中
running：任务运行中
succeeded：任务成功（如发送失败，即 5 秒内没有接收到成功发送的信息，回调三次）
failed：任务失败（如发送失败，即 5 秒内没有接收到成功发送的信息，回调三次）
expired：任务超时，即任务处于运行中或排队中状态超过过期时间。可通过 execution_expires_after 字段设置过期时间。

return_last_frame `boolean`

默认值: false

true：返回生成视频的尾帧图像。设置为 true 后，可通过查询视频生成任务接口获取视频的尾帧图像。尾帧图像的格式为 jpeg，宽高像素值与生成的视频保持一致，无水印。使用该参数可实现多个连续视频：以上一个生成视频的尾帧作为下一个视频任务的首帧，快速生成多个连续视频。
false：不返回生成视频的尾帧图像。

draft `boolean`

默认值: false

控制是否开启样片模式。用于先生成一段低成本的预览视频，确认场景结构、镜头调度、主体动作与提示词意图符合预期后，再基于该样片生成正式视频。

true：开启样片模式，生成一段预览视频（Draft 视频），消耗 token 数较正式视频更少，使用成本更低。
false：关闭样片模式，正常生成一段视频。

说明

开启样片模式后，仅支持生成 480p 分辨率的 Draft 视频（使用其他分辨率会报错）。
样片模式下的参数限制与计费方式，详见 Seedance 2.5 样片模式说明。

execution_expires_after `integer`

默认值: 172800

任务超时阈值。指定任务提交后的过期时间（单位：秒），从 created_at 时间戳开始计算。默认值 172800 秒，即 48 小时。取值范围：[3600, 259200]。

不论使用哪种 service tier，都建议根据业务场景设置合适的超时时间。超过该时间后任务会被自动终止，并标记为 expired 状态。

generate_audio `boolean`

默认值: true

控制生成的视频是否包含与画面同步的声音。

true：模型输出的视频包含同步声音。模型会基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说："你记住，以后不可以用手指指月亮。"
false：模型输出的视频为无声视频。

注意：生成的有声视频均为单声道，和传入的音频声道数无关。

output_format `string`

默认值: mp4

输出视频的格式。Seedance 2.5 独有参数。

mp4：通用格式，兼容性最好，采用标准色彩精度，可在网页、移动端、各类播放器及分发平台直接播放。
mov：面向专业场景的高色彩精度格式，更好地保持画面色彩与亮度一致性，适用于调色、抠像、合成等对色彩还原要求高的专业后期加工。推荐在视频编辑、视频延长场景使用 mov 格式作为输入和输出。

mov 格式播放兼容性

mov 格式采用专业编码（H.264 视频编码 + yuv444p 色度采样 + PCM 音频编码），部分播放器可能不兼容。以下为常见的支持播放 mov 格式的播放器：

播放器	macOS	Windows
IINA	✓	✕
VLC	✓	✓
mpv	✓	✓
ffplay	✓	✓

tools `object[]`

配置模型要调用的工具。

属性：

tools.type string：指定使用的工具类型。
- web_search：联网搜索工具。开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等）。可提升生成视频的时效性，但也会增加一定的时延。

说明

实际搜索次数可通过查询视频生成任务 API 返回的 usage.tool_usage.web_search 字段获取，如果为 0 表示未搜索。

safety_identifier `string`

终端用户的唯一标识符，用于协助平台检测您的应用中可能违反火山方舟使用政策的用户。

该标识符为英文字符串，需保证对单个用户固定且唯一，长度不超过 64 个字符。推荐传入对用户名、用户 ID 或邮箱进行哈希处理后生成的字符串，避免泄露用户隐私信息。

priority `integer`

默认值: 0

设置当前请求的执行优先级，决定其在队列中的排序位置。取值范围：[0, 9]，数值越大，优先级越高。

默认情况下，请求将按 FIFO（First In, First Out，先进先出）顺序执行。设置较高优先级后，该请求将插队到同一 Endpoint（推理接入点）下所有低优先级请求之前。

说明

相同优先级的请求之间仍按 FIFO 排序
优先级仅影响排队顺序，不会中断正在执行中（status=running）的任务
优先级仅在同一 Endpoint 内生效，不影响其他 Endpoint 的任务

omni_reference_task_type `string`

默认值: auto

任务类型引导。Seedance 2.5 的多模态参考生视频任务包括参考生视频、视频编辑和视频延长 3 类子任务。不同任务类型对参数有特殊限制，为减少任务创建后异步报错的情况，可通过本参数指定子任务类型，以提前校验对应限制。

默认情况下，即 omni_reference_task_type=auto：模型根据输入素材和提示词自动判定任务类型，再校验参数取值。如果参数与实际任务类型不兼容，任务将触发异步报错。
显式指定任务类型，即 omni_reference_task_type 为 reference、edit 或 extend：接口在提交任务时提前校验对应任务的特殊参数限制。不符合要求时，接口立即报错，任务不会创建。

可选值：

auto：由模型根据输入素材和提示词自动判定任务类型。
reference：参考生视频任务，即基于参考图片、参考视频或参考音频生成新视频。设置 reference 时，ratio 或 duration 无特殊限制。
edit：视频编辑任务，即对原视频的画面或音频进行编辑操作。设置 edit 时，content 中必须至少包含一个 reference_video，且视频时长必须为 4–30 秒；ratio 必须为 adaptive；duration 必须为 -1。
extend：视频延长任务，即对原视频向前或向后延长。设置 extend 时，content 中必须至少包含一个 reference_video；ratio 必须为 adaptive。

注意：实际处理任务时，模型仍会进一步结合提示词判断任务类型。若实际判定的任务类型和指定的不一致，仍会触发异步报错。建议遵循各任务类型的提示词写法，降低报错概率。

resolution `string`

默认值: 720p

视频分辨率。Seedance 2.5 可选值：

480p
720p
1080p

1080p 输出说明

Seedance 2.5 输出的 1080p 视频采用 10bit 位深与 H.265/HEVC 编码。相较于一般的 8bit 位深，10bit 位深能够保留更丰富的色彩层次与更平滑的渐变过渡。H.265/HEVC 编码在少数播放环境中可能不兼容，如遇问题，建议升级系统、更换设备，或使用 VLC、MPV、QuickTime Player 等播放器查看。

ratio `string`

默认值: adaptive

生成视频的宽高比例。枚举值：

16:9
4:3
1:1
3:4
9:16
21:9
adaptive：根据任务类型和输入内容自动适配宽高比

Seedance 2.5 adaptive 适配规则

任务类型	适配规则
文生视频	支持在可选宽高比中自行设置，或由模型根据 prompt 自动选择。支持 `adaptive` 或指定宽高比。
首帧/首尾帧生视频	自动保持输出视频和首帧图片的宽高比一致，默认且仅支持 `adaptive`。
多模态参考生视频（视频编辑/延长）	自动保持输出视频和待编辑/待延长视频的宽高比一致，不支持另行设置，默认且仅支持 `adaptive`。
多模态参考生视频（参考生视频）	支持在可选宽高比中自行设置，或由模型根据 prompt 自动选择。支持 `adaptive` 或指定宽高比。

不同宽高比对应的宽高像素值（Seedance 2.5）

分辨率	宽高比	宽高像素值
480p	16:9	854×480
	4:3	752×560
	1:1	640×640
	3:4	560×752
	9:16	480×854
	21:9	992×432
720p	16:9	1280×720
	4:3	1112×834
	1:1	960×960
	3:4	834×1112
	9:16	720×1280
	21:9	1470×630
1080p	16:9	1920×1080
	4:3	1664×1248
	1:1	1440×1440
	3:4	1248×1664
	9:16	1080×1920
	21:9	2206×946

duration `integer`

默认值: -1

如果您希望生成整数秒的视频，建议指定 duration。

生成视频时长，仅支持整数，单位：秒。

Seedance 2.5：取值范围 [4, 30]；或设置为 -1（智能选择，模型在有效范围内自主选择合适的视频长度）

注意：Seedance 2.5 在 视频编辑任务 中的限制条件：
仅支持配置 duration 为 -1，不支持指定具体输出时长。
传入的待编辑视频时长需在 [4, 30] s 内，否则将触发报错。

duration 适配规则（duration = -1）

任务类型	取值规则
视频编辑任务	自动保持输出视频和输入视频的时长基本一致（输出时长可能为非整数秒，且可能略短于输入视频，误差约 0.4 秒），不支持另行设置。
其他任务类型	模型在 duration 的有效取值范围内，自主选择合适的视频长度（整数秒）。

duration 返回值说明

通过查询视频生成任务 API 接口返回的 duration 值为视频的时长约数（整数秒），与实际的视频时长可能不同。具体返回规则如下：

计算公式：接口返回的 duration = 实际总帧数 / 24（向下取整）
举例：若最终生成视频为 133 帧，视频实际时长为 133 / 24 = 5.54 秒；向下取整后，duration 最终返回值为 5

watermark `boolean`

默认值: false

生成视频是否包含水印。

true：生成视频右下角会展示 AI 生成 水印。
false：生成视频不含水印。

响应参数

id `string`

视频生成任务 ID。仅保存 7 天（从 created_at 时间戳开始计算），超时后将自动清除。

设置 "draft": true：为 Draft 视频任务 ID。
设置 "draft": false：为正常视频任务 ID。

创建视频生成任务为 异步接口，获取 id 后需要通过 查询视频生成任务 API 来查询任务状态。任务成功后会输出生成视频的 video_url。

豆包语音合成大模型

豆包语音识别大模型

seedance –2.0系列

seedance –2.5

真人/虚拟素材库

创建视频生成任务 API

模型能力

任务类型与特殊限制

请求参数

请求信息

请求头

请求体

model `string` 必选

content `object[]` 必选

信息类型

callback_url `string`

return_last_frame `boolean`

draft `boolean`

execution_expires_after `integer`

generate_audio `boolean`

output_format `string`

tools `object[]`

safety_identifier `string`

priority `integer`

omni_reference_task_type `string`

resolution `string`

ratio `string`

duration `integer`

watermark `boolean`

响应参数

id `string`

创建视频生成任务 API ​

模型能力 ​

任务类型与特殊限制 ​

请求参数 ​

请求信息 ​

请求头 ​

请求体 ​

model string 必选 ​

content object[] 必选 ​

信息类型 ​

callback_url string ​

return_last_frame boolean ​

draft boolean ​

execution_expires_after integer ​

generate_audio boolean ​

output_format string ​

tools object[] ​

safety_identifier string ​

priority integer ​

omni_reference_task_type string ​

resolution string ​

ratio string ​

duration integer ​

watermark boolean ​

响应参数 ​

id string ​

创建视频生成任务 API

模型能力

任务类型与特殊限制

请求参数

请求信息

请求头

请求体

model `string` 必选

content `object[]` 必选

信息类型

callback_url `string`

return_last_frame `boolean`

draft `boolean`

execution_expires_after `integer`

generate_audio `boolean`

output_format `string`

tools `object[]`

safety_identifier `string`

priority `integer`

omni_reference_task_type `string`

resolution `string`

ratio `string`

duration `integer`

watermark `boolean`

响应参数

id `string`