视频生成

POST /v1/videos

异步视频生成接口。视频渲染耗时较长(通常数十秒到数分钟),因此采用提交 + 轮询模式:提交后立即返回任务 ID,再轮询取结果。

支持文生视频、图生视频(单图首帧 / 首尾帧 / 多图参考),以及参考视频、参考音频等高级用法。

Seedance 2.5

新增 doubao-seedance-2-5（720p）和 doubao-seedance-2-5-1080p（1080p），继续使用 POST /v1/videos 与 GET /v1/videos/{id}。

seconds 使用字符串："4"–"30"，或 "0" 自动时长。
最多 30 张图片、10 段视频、10 段音频，合计最多 50 项。图片可用 HTTPS 或 PNG／JPEG／WebP 的 base64 data: URL（网关自动转换）；视频／音频须 HTTPS，不支持 asset://。
image_url 为首帧；首尾帧可用 reference_image_urls 两张图配合 video_config.reference_mode="start_end"。这两种模式须用 aspect_ratio:"adaptive"（2.5 默认值），不传固定像素 size。
可直接传 mode 与 media:[{"type":"video","role":"reference_video","url":"https://..."}]，不能与旧参考字段混用。支持 TEXT_TO_VIDEO、IMAGE_TO_VIDEO、FIRST_LAST_FRAME、REFERENCE_MATERIAL、VIDEO_EDIT、VIDEO_EXTEND；视频编辑须 seconds:"0"，编辑／延长须 aspect_ratio:"adaptive"。
output_format 支持 mp4（默认）或 mov；watermark 为布尔值。generate_audio 沿用本接口默认 true。
按实际输出 token 结算。官网美元目录价：720p 无／有视频输入分别 $10.70／$6.40 每百万 token；1080p 分别 $11.70／$7.00。组织／渠道倍率按订阅配置应用。

{"model":"doubao-seedance-2-5","prompt":"日落海岸，镜头缓慢推进","seconds":"5","aspect_ratio":"16:9","generate_audio":true}

1. 提交任务:`POST /v1/videos`

1.1 请求参数

参数	类型	必填	说明
`model`	string	是	视频模型 ID。见 1.2 模型。
`prompt`	string	是	视频描述提示词，国内标准 2.0／2.5 最多 5000 字符。带参考素材时必须用 `@Image1` / `@Video1` / `@Audio1` 显式指代,见 1.4 @ 引用语法。
`seconds`	string	是	2.0 国内标准／1080p：`"4"`–`"15"`；2.5：`"4"`–`"30"` 或 `"0"` 自动；其他 2.0：`"5"`–`"15"`。均为字符串整数。
`aspect_ratio`	string	否	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`。2.0 默认 `16:9`；2.5 另支持 `adaptive` 且默认为此值。2.5 首帧／首尾帧／编辑／延长必须 `adaptive`，输出比例跟随素材；省略 `size`，不要直接照搬 2.0 固定比例图生示例。
`resolution`	string	否	分辨率。由所选模型决定(见 1.2 模型),一般无需手动传。
`size`	string	否	标准参数,像素串,支持 `1280x720` / `1920x1080` / `720x1280` / `1080x1920`,一次表达横竖版 + 分辨率(网关会按目标模型自动翻译为目标模型所需的参数形式)。`aspect_ratio` + `resolution` 是可选的进阶等价写法;两者都传时,以显式的 `aspect_ratio` / `resolution` 为准。
`image_url`	string	否	单张参考图,`https://` URL 或 base64 `data:` URL,图生视频时用作首帧;也支持 `asset://` 资产引用(此时作为人像/角色参考而非首帧,见 1.5 虚拟人像资产库)。只用 1 张图时用此字段。图片输入不增加计费 token。
`reference_image_urls`	string[]	否	多张参考图(2.0 最多 9 张；2.5 最多 30 张),用于风格/角色一致性等多图参考,每项为 URL、data URL 或 `asset://` 资产引用(见 1.5 虚拟人像资产库)。`@ImageN` 对应数组第 N 张。
`reference_video`	string	否	参考视频(与 `reference_videos` 同时传,值为数组第一个)。
`reference_videos`	string[]	否	参考视频数组(2.0 最多 3 个、总时长 ≤ 15s；2.5 最多 10 个)。注意:参考视频的内容会计入计费 token(如 5 秒参考视频约增加 108,900 tokens),但含视频输入的请求按更低的「含视频输入」档单价计费,两档单价均见控制台模型目录。
`audio_url`	string	否	参考音频(如指定人声/配音风格;与 `reference_audios` 同时传,值为数组第一个)。2.0 音频须配图片或视频；2.5 可仅用音频参考。
`reference_audios`	string[]	否	参考音频数组(2.0 最多 3 个、总时长 ≤ 15s；2.5 最多 10 个)。支持 mp3 / wav / m4a / aac / ogg / flac 等。
`video_config`	object	否	高级配置,目前支持 `reference_mode`。见 1.3 取值范围。
`generate_audio`	boolean	否	是否生成模型配乐/音效,默认 `true`。设为 `false` 输出无声视频。
`seed`	integer	否	随机种子。固定同一 `seed` 与其余参数不变时,可复现同一生成结果。
`mode`	string	否	2.5 高级模式；见下方模式与角色表。省略时由参考字段推导。
`media`	object[]	否	2.5 素材对象数组，每项含 `type`、`role`、`url`。不能与旧参考字段或 `video_config` 混用。
`output_format`	string	否	2.5：`mp4`（默认）或 `mov`。
`watermark`	boolean	否	2.5：是否加水印，默认 `false`。

视频生成需要一个有效订阅(按 token 计费,见 3. 计费说明)。无订阅会返回 402。

素材与上限：2.5 全部素材合计最多 50 项。普通素材用可直接下载的 HTTPS URL；图片也可用 data:image/png;base64,...、JPEG 或 WebP（单图解码后 ≤ 10 MiB，整个 JSON 请求 ≤ 15 MiB）。网关会转换内联图片，无需客户另行上传；参考视频／音频不接受 data:。asset:// 仍仅限海外 -hw。 分辨率：2.0／2.5 都由模型固定为 720p 或 1080p，跨档 size / resolution 返回 400；显式比例优先不能用来跨越模型分辨率档位。

1.2 模型

分为国内线路与**海外线路(-hw 后缀)**两条产品线,能力与定价相互独立。海外线路支持虚拟人像资产库(asset://),国内线路不支持。 各模型单价见控制台模型目录。

模型	输出	线路	资产库	说明
`doubao-seedance-2-5`	720p	国内	✗	4–30 秒或自动时长；支持编辑／延长、MOV、更多参考素材。
`doubao-seedance-2-5-1080p`	1080p	国内	✗	2.5 高清档；其余规则同 720p。
`doubao-seedance-2-0`	720p	国内	✗	标准清晰度。支持全能参考(图 + 视频 + 音频)与极端比例。
`doubao-seedance-2-0-1080p`	1080p	国内	✗	高清,能力同上,仅分辨率更高(渲染更慢、消耗 token 更多)。
`doubao-seedance-2-0-fast`	720p	国内	✗	快速版,生成更快、token 单价更低。
`doubao-seedance-2-0-hw`	720p	海外	✓	标准清晰度,能力同国内 720p,额外支持虚拟人像资产库。
`doubao-seedance-2-0-1080p-hw`	1080p	海外	✓	高清海外线路。
`doubao-seedance-2-0-fast-hw`	720p	海外	✓	快速版,生成更快、token 单价更低。

1.3 参数取值范围

参数	可选值 / 限制
`seconds`	2.0 国内标准／1080p：`"4"`–`"15"`；2.5：`"4"`–`"30"` 或 `"0"` 自动；其他 2.0：`"5"`–`"15"`。均为字符串整数。
`aspect_ratio`	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`。2.0 默认 `16:9`；2.5 另支持 `adaptive` 且默认为此值。2.5 首帧／首尾帧／编辑／延长必须 `adaptive`，输出比例跟随素材；省略 `size`，不要直接照搬 2.0 固定比例图生示例。
`resolution`	由模型固定：`doubao-seedance-2-0`／`doubao-seedance-2-5` 及 2.0 fast／hw 的 720p 档为 `720p`；名称含 `-1080p` 的模型为 `1080p`。不开放 480p／4K 档。
`size`	标准取值:`1280x720` / `720x1280`(720p 模型)、`1920x1080` / `1080x1920`(1080p 模型)。非标准比例(如 21:9 的 `1680x720`)仍需用 `aspect_ratio` + `resolution` 表达。
`video_config.reference_mode`	`auto`(默认,多图参考)/ `start_frame`(首帧,正好 1 张图)/ `start_end`(首尾帧,正好 2 张图,不能带参考视频)。
参考图数量	2.0 最多 9 张；2.5 最多 30 张。
参考视频数量	2.0 最多 3 个，总时长 ≤ 15s；2.5 最多 10 个。
参考音频数量	2.0 最多 3 个，总时长 ≤ 15s，音频须搭配图片或视频；2.5 最多 10 个，可单独参考音频。

文生／多图参考竖版（2.5 首帧／首尾帧除外）:传 size:"720x1280" 即可(推荐);也可用等价的 aspect_ratio:"9:16" + resolution:"720p" 写法,两者同时传时以显式 aspect_ratio / resolution 为准。 图生视频:传 image_url(单图)或 reference_image_urls(多图),并在 prompt 里用 @Image1 指代该图,否则模型不会按参考图生成。

2.5 的 media 模式（使用这些字段时，不再传 image_url、reference_*、audio_url 或 video_config）：

`mode`	素材要求
`TEXT_TO_VIDEO`	无素材
`IMAGE_TO_VIDEO`	恰好 1 张 `image/first_frame`，adaptive
`FIRST_LAST_FRAME`	恰好 `image/first_frame` 与 `image/last_frame` 各 1 张，adaptive
`REFERENCE_MATERIAL`	`image/reference_image`、`video/reference_video`、`audio/reference_audio`，至少 1 项，不混入首尾帧
`VIDEO_EDIT / VIDEO_EXTEND`	参考素材角色；至少 1 段 `video/reference_video`，adaptive；编辑必须 `seconds:"0"`

1.4 @ 引用语法

带参考素材时,模型靠 prompt 里的 @ImageN / @VideoN / @AudioN 来识别每个素材扮演的角色。素材按类型 + 序号引用(如 Image 1 / Video 1 / Audio 1),序号即该素材在请求中出现的顺序:

@Image1 = reference_image_urls[0](单图时即 image_url),@Image2 = reference_image_urls[1],依此类推
@Video1 = reference_videos[0],依此类推
@Audio1 = reference_audios[0],依此类推

多素材组合时必须用 @ 显式指代,否则模型会瞎猜哪张图是什么角色。

1.5 虚拟人像资产库

参考图字段除了 https:// URL 和 base64 data: URL,还接受 asset://<资产 ID> 形式的资产引用——引用你预先上传到自己资产库的虚拟人像素材。资产为你的组织私有,先通过资产库接口上传获得 asset:// ID,再在视频请求里引用:

{ "image_url": "asset://asset-20260713-xyz" }

规则:

资产是组织私有的:只有创建它的组织能引用自己的 asset:// ID;引用他人(或不存在)的 ID 会返回 400。上传/查询/删除见资产库 API。
asset:// 引用可以放在 image_url,也可以作为 reference_image_urls 的任意一项,并且可与普通 URL / data URL 混用(如"资产库人像 + 自备场景图")。
asset:// 素材始终作为人像/角色参考参与生成——即使放在 image_url 字段里,也不会被当作首帧。需要首帧语义时请使用普通 URL / data URL。
prompt 中仍按 1.4 @ 引用语法用 @ImageN 指代,编号规则与普通参考图完全一致(按素材在请求中出现的顺序)。
资产引用与普通参考图一样,不增加计费 token,同样计入"参考图最多 9 张"的上限。
仅海外线路(-hw 系列)支持:doubao-seedance-2-0-hw / -1080p-hw / -fast-hw。国内线路(doubao-seedance-2-0 / -1080p)不支持 asset://。

1.6 返回

提交成功立即返回(任务已排队,视频尚未生成):

{ "id": "task_xxxxxxxx", "status": "queued", "seconds": 5 }

用 id 字段作为后续轮询的任务 ID。

提交成功 ≠ 视频已生成。排队中的任务仍可能失败(如内容安全拒绝),需等待轮询到终态。

1.7 示例

Seedance 2.5 图生（素材决定比例）

{"model":"doubao-seedance-2-5","prompt":"@Image1 moves slowly","seconds":"5","aspect_ratio":"adaptive","image_url":"https://example.com/start-frame.jpg","generate_audio":true}

文生视频(仅用 `size`,标准写法)

只传 size 即可确定横竖版与分辨率,不需要再传 aspect_ratio / resolution:

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "size": "720x1280"
  }'

文生视频(横版)

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-1080p",
    "prompt": "A cinematic tracking shot through a neon-lit rainy street at night, slow dolly-in, 35mm grain",
    "aspect_ratio": "16:9",
    "size": "1920x1080",
    "seconds": "10"
  }'

文生视频(竖版)

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "size": "720x1280"
  }'

图生视频(单图首帧)

参考图可用 https:// URL,也可用 base64 data: URL。prompt 必须用 @Image1 指代参考图。

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 作为首帧,镜头缓慢推进,人物转身看向远方",
    "seconds": "10",
    "size": "720x1280",
    "image_url": "https://example.com/start-frame.jpg",
    "video_config": { "reference_mode": "start_frame" }
  }'

图生视频(多图组合:角色 + 场景)

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 的角色穿着白裙,在 @Image2 的场景中起舞,anamorphic lens",
    "aspect_ratio": "21:9",
    "resolution": "720p",
    "seconds": "15",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/setting.jpg"
    ]
  }'

图生视频(首尾帧:正好 2 张图)

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "从第一张画面平滑过渡到第二张画面,自然运镜和光影变化",
    "seconds": "10",
    "size": "1280x720",
    "reference_image_urls": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ],
    "video_config": { "reference_mode": "start_end" }
  }'

虚拟人像资产库(asset:// 引用)

资产库人像 + 自备场景图混用,@Image1 指代资产、@Image2 指代场景。注意 model 必须是海外线路的 -hw 名(国内线路不支持 asset://):

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-hw",
    "prompt": "@Image1 的人像站在 @Image2 的场景中,向镜头挥手微笑,自然光",
    "seconds": "5",
    "size": "1280x720",
    "reference_image_urls": [
      "asset://asset-20260713-xyz",
      "https://example.com/scene.jpg"
    ]
  }'

全能参考(图 + 视频 + 音频)

2.0 的 audio_url / reference_audios 须搭配参考图片或视频；2.5 可仅用音频参考。

curl https://api.modeltap.net/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 角色随 @Audio1 的节奏起舞,运镜参考 @Video1,鼓点强时镜头切换",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "size": "1280x720",
    "seconds": "10",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/scene.jpg"
    ],
    "reference_video": "https://example.com/camera-motion.mp4",
    "reference_videos": ["https://example.com/camera-motion.mp4"],
    "audio_url": "https://example.com/track.mp3",
    "reference_audios": ["https://example.com/track.mp3"]
  }'

2. 轮询结果:`GET /v1/videos/{id}`

curl https://api.modeltap.net/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status 取值:queued → processing → completed(或 failed)。视频渲染较慢,建议每数秒轮询一次。

进行中:

{ "id": "task_xxxxxxxx", "status": "processing" }

完成:

{
  "id": "task_xxxxxxxx",
  "status": "completed",
  "video_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "usage": { "total_tokens": 108900 }
}

失败:

{ "id": "task_xxxxxxxx", "status": "failed" }

关于 video_url:完成时返回一个下载链接,有效期有限,请尽快下载或转存。需要稳定获取视频文件,推荐优先使用下面的 /content 端点直接取字节流。

参数说明

字段	说明
`id`	任务 ID,用于轮询。与你的 API Key 所属组织绑定,他人无法访问。
`status`	`queued` / `processing` / `completed` / `failed`。
`video_url`	完成时的视频下载链接,便利字段,有效期有限。
`usage.total_tokens`	完成时返回,本次任务实际计费的 token 数,可用于核对账单。

下载视频:`GET /v1/videos/{id}/content`

除了 poll 响应里的 video_url 便利字段,也可以直接用标准端点获取视频的原始字节流(兼容 OpenAI SDK 的 .download_content() 用法),只在任务 completed 后可用:

curl https://api.modeltap.net/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

返回视频二进制内容；MP4 通常为 Content-Type: video/mp4，2.5 选择 MOV 时按实际视频格式返回。video_url 和 /content 二选一即可:video_url 适合直接分发/预览,但有效期有限;/content 不涉及链接过期问题,是生产环境稳定获取视频文件的推荐方式。

3. 计费说明

按生成的 token 数计费:费用 = 生成 token 数 × 每百万 token 单价。各模型单价见控制台模型目录。
2.0 的 token 估算参考（实际结算以返回 usage 为准，2.5 不使用固定每秒估算）：720p 每秒视频约 21,780 tokens(5 秒约 108,900);1080p 每秒约 49,005 tokens(5 秒约 245,025)。快速版(doubao-seedance-2-0-fast / -fast-hw)的 token 数与 720p 相同,单价更低。
参考图不增加计费 token;含参考视频的请求,视频内容会计入 token 数(如 5 秒参考视频约增加 108,900 tokens),但整单按更低的「含视频输入」档每百万 token 单价计费——两档单价均见控制台模型目录。
轮询响应中的 usage.total_tokens 就是实际计费的 token 数,可据此核对账单。
在视频完成时结算;失败 / 放弃的任务不计费。

4. 常见错误

HTTP	场景	说明
400	缺少 `model`	请求不完整。
400	`seconds` 类型错	`seconds` 必须是字符串,如 `"10"`(不能传数字)。
400	`seconds` 超范围	2.0 国内标准／1080p：`"4"`–`"15"`；2.5：`"4"`–`"30"` 或 `"0"` 自动；其他 2.0：`"5"`–`"15"`。均为字符串整数。
400	字段类型错	如 `size` 传了数字、`reference_image_urls` 不是字符串数组。
400	`size` 取值不支持	仅支持 `1280x720` / `1920x1080` / `720x1280` / `1080x1920`;其他比例请改用 `aspect_ratio` + `resolution`。
400	分辨率与模型档位不符	分辨率由所选模型决定:720p 档(`doubao-seedance-2-0` / `-fast` / `-hw` / `-fast-hw`)只出 720p,1080p 档(`-1080p` / `-1080p-hw`)只出 1080p。传了跨档的 `size` / `resolution` 会被拒绝——请改用对应档位的模型。
400	参考素材过多	2.0 为 9/3/3；2.5 为 30/10/10、合计 50。
400	2.0 音频缺少视觉素材	音频参考须搭配图片或视频。2.5 支持仅音频参考。
401	API Key 无效	检查 `Authorization` 头。
402	无有效订阅	视频按 token 计费,需先开通订阅。
403	模型不在 Key 允许范围	检查该 Key 的可用模型。
404	任务不存在 / 非本组织	轮询的 `id` 错误或不属于当前 Key 所在组织。
413	请求体过大	参考图建议用 `https://` URL;data URL 单图过大时改用 URL。
503	暂时不可用	模型服务临时超时或无可用通道,稍后重试。