视频生成

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` / `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[]	否	多张参考图(最多 9 张),用于风格/角色一致性等多图参考,每项为 URL、data URL 或 `asset://` 资产引用(见 1.5 虚拟人像资产库)。`@ImageN` 对应数组第 N 张。
`reference_video`	string	否	参考视频(与 `reference_videos` 同时传,值为数组第一个)。
`reference_videos`	string[]	否	参考视频数组(最多 3 个,总时长 ≤ 15s)。注意:参考视频的内容会计入计费 token(如 5 秒参考视频约增加 108,900 tokens),但含视频输入的请求按更低的「含视频输入」档单价计费,两档单价均见控制台模型目录。
`audio_url`	string	否	参考音频(如指定人声/配音风格;与 `reference_audios` 同时传,值为数组第一个)。用音频时必须同时带 ≥1 张参考图。
`reference_audios`	string[]	否	参考音频数组(最多 3 个,总时长 ≤ 15s)。支持 mp3 / wav / m4a / aac / ogg / flac 等。
`video_config`	object	否	高级配置,目前支持 `reference_mode`。见 1.3 取值范围。
`generate_audio`	boolean	否	是否生成模型配乐/音效,默认 `true`。设为 `false` 输出无声视频。
`seed`	integer	否	随机种子。固定同一 `seed` 与其余参数不变时,可复现同一生成结果。

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

1.2 模型

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

模型	输出	线路	资产库	说明
`doubao-seedance-2-0`	720p	国内	✗	标准清晰度。支持全能参考(图 + 视频 + 音频)与极端比例。
`doubao-seedance-2-0-1080p`	1080p	国内	✗	高清,能力同上,仅分辨率更高(渲染更慢、消耗 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`	字符串整数,`"5"`–`"15"`(含两端)。
`aspect_ratio`	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`(默认 `16:9`)。
`resolution`	由模型决定:720p 档(`doubao-seedance-2-0` / `-hw` / `-fast-hw`)出 `720p`,1080p 档(`doubao-seedance-2-0-1080p` / `-1080p-hw`)出 `1080p`。
`size`	标准取值:`1280x720` / `720x1280`(720p 模型)、`1920x1080` / `1080x1920`(1080p 模型)。非标准比例(如 21:9 的 `1680x720`)仍需用 `aspect_ratio` + `resolution` 表达。
`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" 写法,两者同时传时以显式 aspect_ratio / resolution 为准。 图生视频:传 image_url(单图)或 reference_image_urls(多图),并在 prompt 里用 @Image1 指代该图,否则模型不会按参考图生成。

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 示例

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

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

curl https://api.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/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"
    ]
  }'

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

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

curl https://api.portal.aiin1.ai/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.portal.aiin1.ai/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.portal.aiin1.ai/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

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

3. 计费说明

按生成的 token 数计费:费用 = 生成 token 数 × 每百万 token 单价。各模型单价见控制台模型目录。
token 数由分辨率和时长唯一确定:720p 每秒视频约 21,780 tokens(5 秒约 108,900);1080p 每秒约 49,005 tokens(5 秒约 245,025)。doubao-seedance-2-0-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` 超范围	取值范围 `"5"`–`"15"`。
400	字段类型错	如 `size` 传了数字、`reference_image_urls` 不是字符串数组。
400	`size` 取值不支持	仅支持 `1280x720` / `1920x1080` / `720x1280` / `1080x1920`;其他比例请改用 `aspect_ratio` + `resolution`。
400	分辨率与模型档位不符	分辨率由所选模型决定:720p 档(`doubao-seedance-2-0` / `-hw` / `-fast-hw`)只出 720p,1080p 档(`-1080p` / `-1080p-hw`)只出 1080p。传了跨档的 `size` / `resolution` 会被拒绝——请改用对应档位的模型。
400	参考素材过多	图 ≤ 9 / 视频 ≤ 3 / 音频 ≤ 3。
400	用音频但没带参考图	音频参考必须配 ≥1 张参考图。
401	API Key 无效	检查 `Authorization` 头。
402	无有效订阅	视频按 token 计费,需先开通订阅。
403	模型不在 Key 允许范围	检查该 Key 的可用模型。
404	任务不存在 / 非本组织	轮询的 `id` 错误或不属于当前 Key 所在组织。
413	请求体过大	参考图建议用 `https://` URL;data URL 单图过大时改用 URL。
503	暂时不可用	上游临时超时或无可用通道,稍后重试。