视频生成

POST /v1/videos

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

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

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

1.1 请求参数

参数	类型	必填	说明
`model`	string	是	视频模型 ID。见 1.2 模型。
`prompt`	string	是	视频描述提示词。带参考素材时必须用 `@Image1` / `@Video1` / `@Audio1` 显式指代,见 1.4 @ 引用语法。
`seconds`	string	是	时长(秒),字符串类型,取值范围 `"5"`–`"15"`。
`aspect_ratio`	string	否	画面比例,默认 `16:9`。可选值见 1.3 取值范围。
`resolution`	string	否	分辨率。由所选模型决定(见 1.2 模型),一般无需手动传。
`size`	string	否	像素串,如 `1280x720`(横)/ `720x1280`(竖)。建议与 `aspect_ratio` + `resolution` 三件套一起传。
`image_url`	string	否	单张参考图,`https://` URL 或 base64 `data:` URL。只用 1 张图时用此字段。
`reference_image_urls`	string[]	否	多张参考图(最多 9 张),每项为 URL 或 data URL。`@ImageN` 对应数组第 N 张。
`reference_video`	string	否	参考视频(与 `reference_videos` 同时传,值为数组第一个)。
`reference_videos`	string[]	否	参考视频数组(最多 3 个,总时长 ≤ 15s)。
`audio_url`	string	否	参考音频(与 `reference_audios` 同时传,值为数组第一个)。用音频时必须同时带 ≥1 张参考图。
`reference_audios`	string[]	否	参考音频数组(最多 3 个,总时长 ≤ 15s)。支持 mp3 / wav / m4a / aac / ogg / flac 等。
`video_config`	object	否	高级配置,目前支持 `reference_mode`。见 1.3 取值范围。

视频生成需要一个有效订阅(按秒计费)。无订阅会返回 402。

1.2 模型

模型	说明
`doubao-seedance-2-0`	标准清晰度,输出 720p。支持全能参考(图 + 视频 + 音频)与极端比例。
`doubao-seedance-2-0-1080p`	高清,输出 1080p。能力与 `doubao-seedance-2-0` 一致,仅分辨率更高(渲染更慢,按秒计费不变)。

1.3 参数取值范围

参数	可选值 / 限制
`seconds`	字符串整数,`"5"`–`"15"`(含两端)。
`aspect_ratio`	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`(默认 `16:9`)。
`resolution`	由模型决定:`doubao-seedance-2-0` 出 `720p`,`doubao-seedance-2-0-1080p` 出 `1080p`。
`size`	`宽x高` 像素串,由 `aspect_ratio` + 分辨率推算。720p 常用:`1280x720`(16:9 横)、`720x1280`(9:16 竖)、`1680x720`(21:9);1080p 常用:`1920x1080`、`1080x1920`。
`video_config.reference_mode`	`auto`(默认,多图参考)/ `start_frame`(首帧,正好 1 张图)/ `start_end`(首尾帧,正好 2 张图,不能带参考视频)。
参考图数量	最多 9 张。
参考视频数量	最多 3 个,总时长 ≤ 15s。
参考音频数量	最多 3 个,总时长 ≤ 15s,且必须同时带 ≥1 张参考图。

竖版:传 size:"720x1280"(或 aspect_ratio:"9:16" + resolution:"720p")。 图生视频:传 image_url(单图)或 reference_image_urls(多图),并在 prompt 里用 @Image1 指代该图,否则模型不会按参考图生成。

1.4 @ 引用语法

带参考素材时,模型靠 prompt 里的 @ImageN / @VideoN / @AudioN 来识别每个素材扮演的角色:

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

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

1.5 返回

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

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

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

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

1.6 示例

文生视频(横版)

curl https://api.openbili.com/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.openbili.com/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.openbili.com/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.openbili.com/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",
    "size": "1680x720",
    "seconds": "15",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/setting.jpg"
    ]
  }'

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

curl https://api.openbili.com/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" }
  }'

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

用 audio_url / reference_audios 时必须同时带 ≥1 张参考图,否则会报错。

curl https://api.openbili.com/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.openbili.com/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=..."
}

失败:

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

关于 video_url:完成时返回一个带签名的下载链接(有效期约 2 小时)。请在有效期内下载/转存。

参数说明

字段	说明
`id`	任务 ID,用于轮询。与你的 API Key 所属组织绑定,他人无法访问。
`status`	`queued` / `processing` / `completed` / `failed`。
`video_url`	完成时的视频下载链接(约 2h 有效)。

3. 计费说明

按实际生成时长(秒)计费,在视频完成时结算。
失败 / 放弃的任务不计费。

4. 常见错误

HTTP	场景	说明
400	缺少 `model`	请求不完整。
400	`seconds` 类型错	`seconds` 必须是字符串,如 `"10"`(不能传数字)。
400	`seconds` 超范围	取值范围 `"5"`–`"15"`。
400	字段类型错	如 `size` 传了数字、`reference_image_urls` 不是字符串数组。
400	参考素材过多	图 ≤ 9 / 视频 ≤ 3 / 音频 ≤ 3。
400	用音频但没带参考图	音频参考必须配 ≥1 张参考图。
401	API Key 无效	检查 `Authorization` 头。
402	无有效订阅	视频按秒计费,需先开通订阅。
403	模型不在 Key 允许范围	检查该 Key 的可用模型。
404	任务不存在 / 非本组织	轮询的 `id` 错误或不属于当前 Key 所在组织。
413	请求体过大	参考图建议用 `https://` URL;data URL 单图过大时改用 URL。
503	暂时不可用	上游临时超时或无可用通道,稍后重试。