视频模型 API 平台化接入指南
把视频生成接口接进你自己的产品或工具，供你的用户或团队使用。
已经在用火山方舟原生请求格式的开发者，可以直接使用本平台的方舟兼容入口（POST /videos/api/v3/contents/generations/tasks）；与方舟原生的具体差异见下方「方舟兼容入口：与方舟原生的差异」。
01三分钟跑通第一条视频
想先感受一下？用你的 API Key 在视频工作台直接生成一段视频，不用写代码。
最小闭环三步：提交 → 轮询 → 取片。
⚠️ 生成是异步的，出片耗时因模型、时长与画面复杂度而异。提交返回的是任务号，不是视频，请轮询响应里的 poll_url 获取结果。不要同步等待。
响应里 status 初始为 queued，随后转 running；poll_url 就是下一步要轮询的地址：
请求字段与提交完全相同，只是把路径换成 /generations/estimate——不建任务、不扣费、不触发生成：
把上一步响应里的 poll_url 原样拿来请求即可：
status 变成 completed 后，video_url 就是可下载的视频直链：
⚠️ video_url 约 24 小时后失效，请及时下载保存，不要依赖它长期可访问。
| 模型 | 调用名（model 字段填这个） | 支持分辨率 |
|---|---|---|
| Seedance 2.0 | doubao-seedance-2.0 | 480p / 720p / 1080p |
| Seedance 2.0 极速 | doubao-seedance-2.0-fast | 480p / 720p |
| Seedance 2.5 | doubao-seedance-2.5 | 480p / 720p / 1080p |
| MiniMax H3 | MiniMax-H3 | 768P / 2K |
以上为当前可用的视频模型；完整、实时的清单以模型市场为准。视频模型不在文本网关的 GET /v1/models 里。
02参考图
🔴 API 提交参考图，请提供公网可访问的 URL，放进 image_urls。这与生成引擎官方的要求一致——上游只接收链接，不接收文件本身。
真人形象的图：先用这个 URL 建素材，拿到 asset://<素材ID> 后在生成请求里引用它，见下节「素材库：真人形象的唯一通道」。
（本平台另提供一个上传接口，供视频工作台在用户从本地选图时使用；平台化 API 接入用不到它，见「接口参考 → 5.8」。）
⚠️ 像素上限：单张图宽×高不得超过 3600 万像素。手机原图常见 6048×8064（约 4900 万像素），会被拒。用公网 URL 提交时，本平台不预检像素——请在你自己那侧压图，否则要到生成阶段才失败。走上传接口则会在上传时拦截。
⚠️ 单次请求最多 9 张参考图。
03素材库：真人形象的唯一通道
模型对包含真人形象的参考图有内容审核，直接传图片链接会被拒。素材库是本平台提供的合规通道——先把形象注册为素材，再在生成请求里引用它。
参考图里有真人脸。如果你的业务每条视频都带真人（例如探店、口播、达人出镜），那么素材库不是可选项，是必经之路。
- 拿到一个图片链接（自己的公网链接，或用上传接口拿一个）
- 调建素材接口，传入链接与名称 → 得到素材 ID
- 在生成请求的
image_urls里写asset://<素材ID>
⚠️ 建素材后有一个短暂的处理期，处理完成才可用于生成。请以列表接口 usable 为准——建议轮询到 usable 为 true 再提交生成请求，不要按固定等待时长猜。
素材状态：Processing（处理中）→ Active（处理完成）/ Failed（处理失败）。
⚠️ 建素材这一步返回的 usable 恒为 true，它只说明「这条素材建在了当前通道上」，不代表已经就绪——上面示例里 status 还是 Processing。doubao-seedance-2.0 / -fast 必须等到 Active 才能引用。判据请用列表接口带 ?model=<模型名> 查到的 usable——它已经把「通道对得上」和「在该通道上已就绪」两件事一起算进去了，比单看 status 准。
拿不准就调 GET /videos/v1/videos/assets/capability?model=<模型名>，enabled 会直接告诉你这个模型能不能引用素材。
把上一步拿到的 ref（asset://<素材ID>）放进 image_urls，和普通图片链接一样使用：
04人物命名与位置语法
多个参考图同时出现时，可以在提示词里指明"让这个人做什么"。
🔴 接口上必须使用位置语法 @图片1、@图片2，编号对应 image_urls 数组的顺序（从 1 开始）。
⚠️ 视频工作台里可以打 @张三 这种名字，接口上不行。视频工作台是在提交前把名字替换成位置编号再发出去的；接口这一层不做这个替换，你写的名字会被当作普通文字，人物绑定不会生效。
⇒ 如果你想让使用者用名字，替换要在你自己的产品里做：维护"名字 → 这张图排第几"的映射，提交前替换成 @图片N。
请求格式、状态枚举与 content.video_url 语义与方舟原生一致；以下为本平台特有行为：
- 地址：
POST /videos/api/v3/contents/generations/tasks·GET …/tasks/{id} - 任务号：本平台返回 UUID；任务在哪条入口提交就在哪条查询
- 素材：真人形象参考图必须先在本平台注册为素材（
asset://），见素材库 - 回调：不支持
callback_url，请轮询GET …/tasks/{id} - 取消 / 列表：暂不支持（501）
- 成片：
content.video_url为引擎直链（约 24 小时）；本平台额外返回content.platform_video_url（保留 7 天）与platform_expires_at - 错误码：失败任务的
error.code使用本平台稳定码（input_image_real_person/asset_unavailable/output_content_policy/content_safety_rejected/rate_limit_exceeded/upstream_generation_failed/task_not_found），message为人话说明 - 顶层参数：
model/content/resolution/ratio/duration/generate_audio/seed/watermark/omni_reference_task_type/camera_fixed/frames；不在此列的参数返回 400 并点名，不静默丢弃 - 提示词内联参数（
--rs/--rt/--dur/--wm/--seed/--cf/--frames）：本平台解析并填入对应字段；与顶层字段同时给出且不一致时返回 400 - Seedance 2.5 参考图：未指定
role的图片按参考生视频处理（reference_image），画幅按你传的值生效；首尾帧模式（first_frame/last_frame）画幅固定为adaptive
05接口参考
鉴权：所有接口用 Authorization: Bearer <你的密钥>。
错误信封（所有接口统一）：
请按 code 分支处理，不要匹配 message 文字——文案可能调整，code 稳定。
POST /videos/v1/videos/generations| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | ✅ | 模型名，≤100 字符 |
prompt | string | ✅ | 提示词，≤2000 字符 |
duration | integer | 秒，默认 5。doubao-seedance-2.0 / -fast 为 4–15，不能传 -1。越界会在提交时返回 400 | |
resolution | string | 480p / 720p / 1080p，默认 720p。当前在售模型都不支持 4k；doubao-seedance-2.0-fast 最高 720p | |
aspect_ratio | string | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive。doubao-seedance-2.5 带参考图时默认按参考生视频处理，画幅按你传的值生效；仅首尾帧模式（generation_type: "first_and_last_frames"）画幅固定为 adaptive | |
image_urls | array | 参考图，最多 9 项；两种写法见下 | |
video_urls | string[] | 参考视频，最多 3 项；不接受素材引用 | |
audio_urls | string[] | 参考音频，最多 3 项；不接受素材引用；不能单独使用，必须搭配参考图或参考视频 | |
generate_audio | boolean | 是否生成音轨。要出声请显式传 true，要无声请显式传 false，不要依赖默认值 | |
watermark | boolean | 是否加水印 | |
seed | integer | -1 ~ 4294967295 | |
generation_type | string | omni_reference（多模态参考，默认语义）/ first_and_last_frames（首尾帧；此模式下参考视频和参考音频会被忽略） | |
callback_url / callback_secret | — | ❌ | 不支持，传了会报错。请轮询 poll_url |
image_urls 每项可以是：
- 字符串：一个公网图片链接，或
asset://<素材ID>。不写role时按首帧图生视频处理 - 对象：
{ "url": "...", "role": "reference_image" }，role可选first_frame/last_frame/reference_image。做多模态参考请显式写reference_image
请求头 Idempotency-Key（可选但强烈建议）：网络重试时带同一把键，不会重复下单、不会重复扣费。同一把键再提交一次，无论内容是否改过，都返回第一单——看起来像成功，片子却是上一版。新任务必须用新键。本入口不会因内容不同而返回 409。
成功响应：
POST /videos/v1/videos/generations/estimate请求字段与 5.1 完全相同。不建任务、不扣费、不触发生成。
| 响应字段 | 说明 |
|---|---|
estimated_cost | 预计费用（美元） |
estimated_cost_cny | 折算人民币（仅展示参考） |
fx_cny_per_usd | 展示汇率 |
currency | USD（计费本位为美元） |
final_cost_may_adjust | true——实际结算可能微调 |
GET /videos/v1/videos/jobs/{job_id}| 字段 | 说明 |
|---|---|
status | 见下方状态表 |
status_note | 仅在需要说明时出现（中文一句话） |
video_url | 生成引擎官方直链，约 24 小时有效 |
expires_at | 上面那条链接的到期时间 |
platform_video_url | 本平台副本；默认为 null（未开通 7 天副本时不产生） |
platform_expires_at | 副本到期时间（仅开通 7 天副本后返回） |
error | 失败时的 {code, message, details}；处理中恒为 null |
cost_pending / cost_final | 预扣 / 结算金额（美元） |
duration_ms | 从提交到完成的耗时 |
metadata | duration / resolution / ratio / seed / usage 等 |
任务状态：
| 值 | 含义 |
|---|---|
queued | 已受理，排队中 |
running | 生成中 |
completed | 已完成，可取片 |
failed | 失败（预扣自动退回） |
cancelled | 已取消 |
timeout | 超时（预扣自动退回） |
⚠️ 看到 running 且带 status_note 时，表示正在与生成方确认结果，此时费用尚未结算，请勿重复提交。
GET /videos/v1/videos/jobs| 参数 | 说明 |
|---|---|
page / page_size | 页码（≥1）/ 每页条数（1–200，默认 20） |
status | 按状态过滤，取值同上表 |
start_date / end_date | YYYY-MM-DD，均含当天 |
api_key_id | 按密钥过滤 |
响应 { items: [...], total, page, page_size }，按提交时间倒序（不可调整）。
GET /videos/v1/videos/jobs/stats过滤参数同 5.4。返回 total_jobs / completed_jobs / failed_jobs / in_flight_jobs / total_cost（仅计已完成）/ avg_duration_ms。
GET /videos/v1/videos/jobs/export.csv过滤参数同 5.4。⚠️ 单次最多导出 200 行，需要更多请用 5.4 分页自行汇总。
建素材 POST /videos/v1/videos/assets
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | ✅ | http(s) 图片链接，≤2048 字符 |
name | string | ≤64 字符；不能叫「图片」或「图片N」（保留给位置语法）；同一账号内不可重名 |
响应含 id（删除用）、ref（形如 asset://xxx，直接放进 image_urls）、status（Processing / Active / Failed）。只有 Active 才能用于生成。
列出素材 GET /videos/v1/videos/assets?model=<模型名>
返回 { assets: [...] }。带上 model 时每项会有 usable 表示在该模型下是否可用；不带 model 时 usable 为 null（未判定，不要当作可用）。
删除素材 DELETE /videos/v1/videos/assets/<素材ID>
从你的库中移除。响应里的 already_retired 为 true 表示此前已删除（重复调用安全）。
查询能力 GET /videos/v1/videos/assets/capability?model=<模型名>
返回 enabled（该模型能否用素材库）、upload_max_bytes、upload_max_pixels。建议接入时读取一次该接口，不要把上限固定写在你的代码里。
本平台提供一个上传接口，供视频工作台在用户从本地选图时使用——它把本地文件转成一个可用的 URL。平台化 API 接入不需要它：你直接提供你自己的公网 URL 即可，这与上游一致（见「参考图」一节）。
POST /videos/v1/videos/uploads，请求体为图片原始字节（不是表单），用 Content-Type 声明类型（image/jpeg / png / webp / gif / heic / heif）；响应含 url。
06错误码
请按 code 分支，不要匹配 message 文字。
| code | HTTP | 含义 | 该告诉用户 |
|---|---|---|---|
input_image_real_person | 400 | 参考图疑似含真人形象 | 这张图需要先加入素材库再使用 |
input_image_too_large | 400 | 图片像素超上限 | 换小一点的图（details 里有实际尺寸与上限） |
output_content_policy | 400 | 生成内容可能涉及版权或敏感信息 | 调整参考图或提示词后重试 |
content_safety_rejected | 400 | 提交内容未通过上游内容安全审核（审的是提示词与参考素材，任务未建立） | 检查提示词与参考素材后重试；同一内容偶发误拦，直接重试一次通常可通过 |
reference_media_unfetchable | 400 | 参考图/视频读不到 | 检查链接是否公网可访问、是否太慢 |
invalid_asset_reference_format | 400 | 素材引用的写法不对（不是 asset://<素材ID> 的形态，或把它写进了 video_urls/audio_urls） | 这是你拼错了字符串，不是用户的问题——不要原样显示给使用者，请自查代码 |
invalid_asset_reference | 400 | 引用的素材不在你的库里，或不适用于该模型的通道 | 重新建素材 |
asset_unavailable | 400 | 素材还没就绪 | 等它变为 Active 再提交 |
asset_name_taken / asset_name_reserved / asset_name_too_long | 400 | 素材命名问题 | 换个名字 |
asset_library_full | 400 | 素材数量已达上限 | 删除不用的素材 |
unsupported_resolution | 400 | 该模型不支持这个分辨率（例如传了 4k，或极速档传了 1080p） | 改用该模型支持的分辨率，见上方模型表 |
frame_role_conflict | 400 | 首帧/尾帧角色不能和参考视频同时用 | 去掉其中一类，不要混用 |
audio_requires_visual | 400 | 参考音频不能单独使用 | 补一张参考图或一段参考视频 |
| code | HTTP | 含义 | 建议动作 |
|---|---|---|---|
invalid_api_key | 401/403 | 密钥无效或账号被禁用 | 检查配置，联系我们 |
ip_not_allowed | 403 | 密钥绑定了网段，当前来源不在其中 | 联系我们调整 |
insufficient_credits | 402 | 账户余额不足 | 充值；建议自建余额预警 |
model_not_found | 404 | 模型名不存在或未开通 | 检查模型名 |
task_not_found | 404 | 任务不存在或不属于你 | 检查任务号 |
upload_quota_exceeded | 429 | 上传配额触顶 | 平台化接入不应使用上传接口，见「参考图」 |
rate_limit_exceeded | 429 | 请求过于频繁 | 退避后重试 |
upstream_channel_unavailable | 502 | 生成通道暂时不可用 | 退避后重试 |
upstream_timeout | 504 | 生成超时（预扣自动退回） | 可重试 |
upstream_generation_failed | 502/503 | 生成方侧失败（预扣自动退回） | 退避后重试 |
submission_result_ambiguous | 502 | 提交结果无法确认 | 🔴 先联系我们，不要直接重试 |
internal_error | 500 | 本平台内部错误 | 联系我们 |
- 400 类：不要自动重试，请求本身要改。
- 401 / 402 / 404：不要自动重试。
- 429：指数退避。
- 502 / 503 / 504：可退避重试，但
submission_result_ambiguous例外——它表示我们无法确认那一单是否已在生成方受理，盲目重试可能重复出片重复计费。
07归属与隔离边界 🔴 接入前必读
素材与任务的归属，按你的账号划分，不按密钥划分。
如果你只在自己的服务内部调用本接口、由你决定谁能看到什么，那么下面这些不会影响到你的使用者——他们看到的一切，都由你的产品决定。但如果你打算把素材的列表、查询或删除能力转交出去（例如给使用者开一个素材管理面板，或把本接口的密钥直接发给他们），请先读完这一节。
原因是：即使你为不同的使用者分配不同的密钥，在本平台看来他们都属于同一个主体。于是：
- 一旦你把「列出素材」「删除素材」这两个能力透传出去，使用者 A 就能看到、并且能删除使用者 B 上传的素材
- 素材数量上限是账号级的，你名下全体使用者共用同一个额度——每账号最多 10 万个
- 消耗明细我们最细只能提供到密钥这一级
本平台只能识别到你的账号这一层，看不到、也无法区分你的产品上具体是哪个使用者在操作。使用者之间"谁能看到谁、谁有什么权限"，只能由你在自己的产品里实现——这是本平台无法代劳的一层。
不同客户之间彼此隔离：账号与账号互不可见，你看不到其他客户的素材。
🔴 真人形象素材的授权，是你的责任。本平台的素材库通道不包含生成引擎官方那套"本人实名认证 / 活体验证"流程——素材可以直接入库用于生成，本平台不会为你产生任何"被拍摄者已授权"的凭证。
你须自行确保：你的产品上所有上传真人形象素材的使用者，对该形象拥有合法使用与授权，并自行留存相应的授权证明；你应在与你的使用者签订的服务协议中，就此作出相应约定。涉及未成年人形象、声音等，须遵循更严格的合规要求。
08配额与限制
| 项 | 限制 | 作用域 |
|---|---|---|
| 提示词长度 | 2000 字符 | 每请求 |
| 参考图数量 | 9 张 | 每请求 |
| 参考视频 / 音频数量 | 各 3 项 | 每请求 |
| 单张图片像素 | 3600 万（宽×高） | 每张 |
| 单张图片大小 | 30 MB | 每张 |
| 请求体总大小 | 1 MB（不含上传接口） | 每请求 |
| 素材库容量 | 10 万个 | 每账号（不是每密钥） |
| CSV 单次导出 | 200 行 | 每请求 |
🔴 素材库容量是按账号算的，你全体使用者共用同一个额度：每账号最多 10 万个素材，覆盖绝大多数场景。如果你的用户数较多、需要更高额度，请联系我们上调。
⚠️ 成片链接会过期：默认仅提供生成引擎官方直链（约 24 小时有效），请及时下载转存到你自己的存储；如需本平台保留 7 天副本，可联系我们开通。
⚠️ 暂不支持取消任务。
09常见接入问题
为什么我传的图被拒了？
@张三 为什么不生效？
@图片1，见「人物命名与位置语法」。我的用户之间素材互相可见，怎么办？
任务多久出片？
poll_url，不要同步等待。可以取消任务吗？
想了解更多接入细节？请联系 [email protected]，我们会尽快与你确认接入细节。