视频模型 API 平台化接入指南
把视频生成接口接进你自己的产品或工具，供你的用户或团队使用。
已经在用火山方舟原生请求格式的开发者，可以直接使用本平台的方舟兼容入口（POST /videos/api/v3/contents/generations/tasks）；与方舟原生的具体差异见下方「5.9 方舟兼容入口：与方舟原生的差异」。
01三分钟跑通第一条视频
想先感受一下？用你的 API Key 在视频工作台直接生成一段视频，不用写代码。
最小闭环三步：提交 → 轮询 → 取片。
⚠️ 生成是异步的，出片耗时因模型、时长与画面复杂度而异。提交返回的是任务号，不是视频，请轮询响应里的 poll_url 获取结果。不要同步等待。
在控制台「令牌」页新建即可。分组只决定文本类模型的计价档位，视频模型不走分组，保持默认的 auto 即可；任何一把 key 都能调用本文列出的全部视频模型。价格按客户折扣计算，实际以 /estimate 当次返回为准——同一模型不同客户看到的金额可能不同。
🔴 密钥上的「IP 白名单」对视频接口生效：来源不在名单内会返回 403 ip_not_allowed，出口 IP 不固定时建议留空。「可用模型」白名单不作用于视频接口。
响应里 status 初始为 queued（这一态可能极短，提交响应里直接看到 running 也正常），随后转 running；poll_url 就是下一步要轮询的地址：
请求字段与提交完全相同，只是把路径换成 /generations/estimate——不建任务、不扣费、不触发生成：
/estimate 当次返回为准）把上一步响应里的 poll_url 原样拿来请求即可：
status 变成 completed 后，video_url 就是可下载的视频直链：
⚠️ video_url 会失效，请及时下载保存，不要依赖它长期可访问；具体失效时间以同一响应里的 expires_at 为准（不同模型所在的上游通道有效期不同，多数约 24 小时，请以每次返回的值为准）。
| 模型 | 调用名（model 字段填这个） | 支持分辨率 |
|---|---|---|
| Seedance 2.0 | doubao-seedance-2.0 | 480p / 720p / 1080p / 4k |
| 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（须小写；768P / 2K 会被拒） |
以上为当前可用的视频模型；完整、实时的清单以模型市场为准。视频模型不在文本网关的 GET /v1/models 里。
最后更新：2026-09-27
02参考图
🔴 API 提交参考图，请提供公网可访问的 URL，放进 image_urls。
真人形象的图：先用这个 URL 建素材，拿到 asset://<素材ID> 后在生成请求里引用它，见下节「素材库：真人形象的唯一通道」。
（本平台另提供一个上传接口，供视频工作台在用户从本地选图时使用；平台化 API 接入用不到它，见「接口参考 → 5.8」。）
⚠️ 像素上限：本平台上传预检按单张图宽×高不超过 3600 万像素拦截（该值取自现役供应通道 2026-08-18 生产实测的真实拒绝阈值，不同供应通道的生成时上游限制可能不同，以生成时返回的错误信息为准）。手机原图常见 6048×8064（约 4900 万像素），会超限。超限的图片会导致任务失败，预扣自动退回。
Base64：与生成引擎官方一致，图片 / 音频可以直接写 data:image/<格式>;base64,… / data:audio/<格式>;base64,…（格式小写；图片 jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30 MB；音频 wav、mp3，单段不超过 15 MB；整个请求体不超过 64 MB）。任务详情里显示的是平台生成的链接。格式或大小不符返回 invalid_inline_media，不扣费。参考视频不支持 Base64。大文件建议先上传或入素材库，再传链接。
⚠️ 单次请求的参考素材上限按模型不同：Seedance 2.0 系列最多 9 张参考图、3 段参考视频、3 段参考音频；Seedance 2.5 最多 30 张参考图、10 段参考视频、10 段参考音频。
最后更新：2026-09-27
03素材库：真人形象的唯一通道
目前适用于 Seedance 2.0 和 Seedance 2.5：这两个模型对包含真人形象的参考图有内容审核，直接传图片链接会被拒。素材库是引用真人形象的通道：先把形象注册为素材，再在生成请求里引用它。其他模型是否有同样的审核，请以生成请求实际返回的错误码为准（未触发该审核的模型不会返回 input_image_real_person）。
Seedance 2.0 和 Seedance 2.5 的参考图里有真人脸时。参考素材含真实人脸时必须走素材库注册；直接传人脸图片 URL 会被审核拦截。
- 拿到一个图片或视频的公网链接（自己的链接，或用上传接口拿一个）
- 调建素材接口，传入链接与名称（视频素材加
"kind": "video"，音频素材加"kind": "audio"；视频、音频只收公网可直下链接，没有上传接口）→ 得到素材 ID。视频、音频素材是否支持取决于当前素材库通道：不支持时返回asset_kind_unsupported（400，不扣费），此时改为在生成请求里直接传公网直链，不走素材库 - 在生成请求的
image_urls（视频素材则video_urls）里写asset://<素材ID>
⚠️ 建素材后有一个短暂的处理期（通常十秒内），处理完成才可用于生成。拿建素材响应里的 id，按 id 单独查这一张（GET /videos/v1/videos/assets/<id>），轮询到 status 为 Active 再提交生成请求，不要按固定等待时长猜。
- 把要用的几张图一起登记（每张各调一次建素材接口，不必等上一张就绪），记下每张的
id - 每 2～3 秒按
id逐张查一次状态，地址就是：GET https://tryaiapi.com/videos/v1/videos/assets/<id>（curl 示例见下方） - 查到
status为Active→ 这张可以提交生成 - 查到
Failed→ 换一张图重新登记，不要重试同一张 - 为整轮登记设一个总上限 120 秒；超过再按失败处理。多数几秒就绪，个别会更久，120 秒内不要只因为等得久就判失败
🔴 轮询退出条件必须覆盖两个终态：Active（处理完成，可以提交生成）与 Failed（处理失败，换一张图）。
GET /videos/v1/videos/assets/<id>路径里的 <id> 用建素材响应里的 id；直接用 asset_id 也可以。返回字段与列表接口里的单条完全一样。不属于你的 id、不存在的 id、已删除的素材，一律返回 404。
（可选）在多个模型之间来回切换时，可加 ?model=<模型名> 让 usable 给出 true/false（不带或填了未知模型名时为 null）。
🔴 列表接口用于管理素材，不要用它轮询状态；轮询请用上面的单张查询接口。
⚠️ Failed 目前不附带失败原因，最常见的原因是图片太小，请使用正常拍摄尺寸的图片。Failed 应按「换一张图重建」处理，不要重试同一张。
素材状态：Processing（处理中）→ Active（处理完成）/ Failed（处理失败）。
⚠️ 上面示例里 status 还是 Processing，这一次响应不能直接拿去提交生成——请拿响应里的 id 按 id 轮询，查到 status 为 Active 再提交。doubao-seedance-2.0 / doubao-seedance-2.0-fast 必须等到处理完成才能引用；MiniMax-H3 例外，登记后即可引用，不看这个状态。
拿不准就调 GET /videos/v1/videos/assets/capability?model=<模型名>，enabled 会直接告诉你这个模型能不能引用素材。
把上一步拿到的 ref（asset://<素材ID>）放进 image_urls，和普通图片链接一样使用：
最后更新：2026-09-27
04人物命名与位置语法
多个参考图同时出现时，可以在提示词里指明"让这个人做什么"。
🔴 接口上必须使用位置语法 @图片1、@图片2（写成 @图片 1 带空格也可以），编号对应 image_urls 数组的顺序（从 1 开始）。目前仅 Seedance 2.0 和 Seedance 2.5 支持这套 @ 语法。MiniMax-H3 不解析它：多张参考图按 image_urls 的数组顺序与每项的 role 字段区分（见「参考图」一节），提示词里不能用 @ 绑定角色。
⚠️ 接口只识别 @图片1、@图片2 这类位置语法，不解析自定义人名。写入人名会被当作普通提示词文字，人物绑定不生效；需要支持人名输入的，请在提交前映射为 @图片N。
⇒ 如果你想让使用者用名字，替换要在你自己的产品里做：维护"名字 → 这张图排第几"的映射，提交前替换成 @图片N。
最后更新：2026-09-27
05接口参考
鉴权：所有接口用 Authorization: Bearer <你的密钥>。
错误信封（本节 REST 接口与方舟兼容入口统一）：
请按 code 分支处理，不要匹配 message 文字——文案可能调整，code 稳定。
POST /videos/v1/videos/generations| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | ✅ | 模型名，≤100 字符 |
prompt | string | ✅（样片正式视频除外） | 提示词。Seedance 2.0 系列与 Seedance 2.5 建议中文不超过 500 字、英文不超过 1000 词（与官方建议一致，过长时模型可能忽略细节），MiniMax-H3 ≤2000 字符（本平台当前入口限制，非官方上限）。不要在提示词里写 --dur / --rs / --rt 这类内联参数——本原生入口对所有模型都会直接拒绝（prompt_reserved_params）。请一律使用请求字段；只有方舟兼容入口会解析内联参数（解析后从提示词中剥离） |
duration | integer | 秒。不传时：doubao-seedance-2.5 默认 -1（与火山方舟官方一致）；doubao-seedance-2.0、doubao-seedance-2.0-fast、MiniMax-H3 默认 5。doubao-seedance-2.0 / doubao-seedance-2.0-fast 为 4–15 或 -1，doubao-seedance-2.5 为 4–30 或 -1，MiniMax-H3 为 4–15（不能传 -1）。-1＝由模型自动选择时长（与火山方舟官方一致）：提交时按该模型最长时长预扣（Seedance 2.0 系列 15 秒、Seedance 2.5 为 30 秒），完成后按实际出片时长结算，多扣的部分退回；实际时长见查询结果 metadata.duration。doubao-seedance-2.5 视频编辑（omni_reference_task_type: "edit"）只接受 -1，不传即按 -1。越界会在提交时返回 400 | |
resolution | string | Seedance 系列：480p / 720p / 1080p，默认 720p，doubao-seedance-2.0-fast 最高 720p；4k 只有 doubao-seedance-2.0（按官方 4k 单价计费）；样片（draft: true）只能 480p、基于样片的正式视频只能 1080p（不传即自动取该档）；MiniMax-H3：768p / 2k（传值小写，无 1080p），默认 768p | |
aspect_ratio | string | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive。doubao-seedance-2.5 带参考图时默认按参考生视频处理，画幅按你传的值生效；在首帧 / 首尾帧模式下输出画幅跟随首帧图，声明为视频编辑 / 视频延长（omni_reference_task_type 为 edit / extend）时跟随原视频，这些模式下传入的画幅不生效，也不会报错。doubao-seedance-2.0 系列在这些模式下可以指定画幅。注意：带参考视频但未声明子任务时，模型可能自行判定为编辑 / 延长，官方建议此时画幅传 adaptive | |
image_urls | array | 参考图，最多 9 项；doubao-seedance-2.5 最多 30 项；两种写法见下 | |
video_urls | string[] | 参考视频，最多 3 项（doubao-seedance-2.5 最多 10 项）；每项是公网视频链接，或 asset://<视频素材ID>（素材必须是 kind: video；把图片素材写在这里会被拒）。Seedance 2.0 系列每段 2–15 秒、总时长 ≤15 秒；doubao-seedance-2.5 每段 2–30 秒（视频编辑 4–30 秒）、总时长 ≤30 秒。超出时长范围会被拒绝，不扣费（错误码 reference_video_duration_out_of_range / reference_video_total_too_long）。链接须能直接下载（mp4 / mov）。带参考视频的任务生成耗时显著增加，轮询超时请相应放宽 | |
audio_urls | string[] | 参考音频，最多 3 项（doubao-seedance-2.5 最多 10 项、总时长 ≤30 秒）；每项是公网音频链接，或 asset://<音频素材ID>（素材必须是 kind: audio）；除 doubao-seedance-2.5 外不能单独使用，必须搭配参考图或参考视频 | |
generate_audio | boolean | 是否生成音轨。不传默认 true（有声），与火山方舟官方默认一致；要无声显式传 false。建议两种情况都显式传，不依赖默认值 | |
watermark | boolean | 是否加水印 | |
seed | integer | -1 ~ 4294967295。官方只对 Seedance 1.0 列出该参数，对 Seedance 2.0 和 Seedance 2.5 不生效（传了不报错） | |
camera_fixed | boolean | 同上：官方只对 Seedance 1.0 列出，对 Seedance 2.0 和 Seedance 2.5 不生效（传了不报错） | |
frames | integer | 同上：官方只对 Seedance 1.0 列出，对 Seedance 2.0 和 Seedance 2.5 不生效（传了不报错）；请用 duration | |
omni_reference_task_type | string | 全模态参考的子任务：auto / reference / edit（视频编辑）/ extend（视频延长），doubao-seedance-2.5 官方参数（对 Seedance 2.0 系列不生效，传了不报错）。edit / extend 必须带至少一段 video_urls，否则 400；edit 的时长只能 -1；传其他值返回 400 | |
return_last_frame | boolean | 为 true 时，完成后查询结果带 last_frame_url（成片最后一帧的 JPEG，约 24 小时有效，本平台不转存），可作为下一段视频的首帧，拼接连续镜头。Seedance 2.0 和 Seedance 2.5 都支持；不另收费 | |
draft | boolean | 样片模式，仅 doubao-seedance-2.5：先生成一段 480p 预览确认镜头与动作，价格与普通 480p 相同。doubao-seedance-2.0、doubao-seedance-2.0-fast、MiniMax-H3 传 true 返回 400 | |
draft_task_id | string | 基于样片生成正式视频，仅 doubao-seedance-2.5：填你自己 7 天内、同一模型、已完成的样片任务号。正式视频固定 1080p，时长与样片相同，按普通 1080p 视频计费。提示词、参考素材、时长、画幅、seed、generate_audio、omni_reference_task_type 由样片复用，不要再传（传了返回 400） | |
output_format | string | mp4（默认）/ mov（仅 doubao-seedance-2.5，色彩精度更高，适合后期调色、抠像；部分播放器不兼容）。Seedance 2.0 系列只出 mp4：传 mp4 等于不传，传 mov 返回 400。不另收费 | |
tools | array | 联网搜索：[{"type": "web_search"}]，Seedance 2.0 和 Seedance 2.5 都支持。模型按提示词自行判断是否搜索，官方说明仅适用于纯文本输入；实际搜索次数见查询结果 metadata.usage.tool_usage.web_search | |
priority | integer | 排队优先级 0–9，数值越大越优先（默认 0），Seedance 2.0 和 Seedance 2.5 都支持 | |
execution_expires_after | integer | 任务过期秒数，3600–259200（默认 172800）。Seedance 2.0 和 Seedance 2.5 超时后最长等到这个时间再确认结果，见下方 timeout | |
safety_identifier | string | 你的终端用户标识（建议传哈希值），可打印 ASCII，≤64 字符，原样转给生成方（官方用途说明见火山方舟文档） | |
service_tier | string | Seedance 2.0 和 Seedance 2.5 只有在线推理：传 default 等于不传，传 flex 返回 400 | |
generation_type | string | omni_reference（多模态参考，默认语义）/ first_and_last_frames（首尾帧；此模式下参考视频和参考音频会被忽略） | |
callback_url / callback_secret | — | ❌ | 不支持，传了会报错。请轮询 poll_url |
image_urls 每项可以是：
- 字符串：一个公网图片链接，或
asset://<素材ID>。只传 1 张且不写role时按首帧图生视频处理。 - 🔴 传 2 张及以上时（非首尾帧模式），没写
role的图片按参考图（reference_image）处理，你自己写了role的按你写的处理。适用 Seedance 2.0 和 Seedance 2.5。 - 单图例外：
doubao-seedance-2.5在非首尾帧模式下只传 1 张也按参考图处理（参考生视频）。 - 没写
role的单图同时带参考视频或参考音频时，这张图按参考图处理。 - 对象：
{ "url": "...", "role": "reference_image" }，role可选first_frame/last_frame/reference_image。做多模态参考请显式写reference_image
video_urls / audio_urls 只传纯 URL 字符串，不需要写 role（走方舟格式入口时，照官方示例在 video_url / audio_url 项上写这两个固定 role 也可以）。三个字段都可以用 asset:// 素材引用，素材类型要与字段对应（图片→image_urls、视频→video_urls、音频→audio_urls）。
请求头 Idempotency-Key（可选但强烈建议）：网络重试时带同一把键，不会重复下单、不会重复扣费。同一把键再提交一次，无论请求体是否改过，都返回首次创建的任务，不校验请求体差异。新任务必须使用新键。
成功响应：
POST /videos/v1/videos/generations/estimate请求字段与 5.1 完全相同。不建任务、不扣费、不触发生成。
| 响应字段 | 说明 |
|---|---|
model | 估价对应的模型（回显） |
estimated_cost | 预计费用（美元） |
estimated_cost_cny | 折算人民币（仅展示参考） |
fx_cny_per_usd | 展示汇率 |
currency | USD（计费本位为美元） |
basis | 估价口径，固定 pre_hold（按提交前的预扣口径估算） |
final_cost_may_adjust | true——实际结算可能微调 |
GET /videos/v1/videos/jobs/{job_id}| 字段 | 说明 |
|---|---|
status | 见下方状态表 |
status_note | 仅在需要说明时出现（中文一句话） |
video_url | 生成引擎官方直链；有效期不同模型所在的上游通道不同（多数约 24 小时），以下面 expires_at 为准 |
expires_at | 上面那条链接的到期时间 |
platform_video_url | 本平台副本；默认为 null（未开通 7 天副本时不产生） |
platform_expires_at | 副本到期时间（仅开通 7 天副本后返回） |
last_frame_url / last_frame_expires_at | 尾帧图链接与到期时间（创建时 return_last_frame: true 才有，约 24 小时有效，本平台不转存）；否则为 null |
error | 失败时的 {code, message, details}；处理中恒为 null |
cost_pending / cost_final | 预扣 / 结算金额（美元） |
duration_ms | 从提交到完成的耗时 |
metadata | duration（实际时长，传 -1 时看这里）/ resolution / ratio / seed / usage（含联网搜索次数 tool_usage）/ output_format / tools 等 |
任务状态：
| 值 | 含义 |
|---|---|
queued | 已受理，排队中 |
running | 生成中 |
completed | 已完成，可取片 |
failed | 失败（预扣自动退回） |
cancelled | 已取消 |
timeout | 超时（预扣自动退回）。⚠️ 超时的任务仍可能出片：结果确认前状态保持 running，一般不超过 24 小时，Seedance 2.0 和 Seedance 2.5 最长等到该任务的 execution_expires_after（默认 48 小时，与官方一致），确认未出片才退款；原生入口此时会在响应里多一个 status_note 字段说明情况，方舟入口没有该字段。请把客户端总超时设到 48 小时以上（传了 execution_expires_after 的，按它来） |
⚠️ 看到 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, fx_cny_per_usd }，按提交时间倒序（不可调整）。fx_cny_per_usd 是本平台当前展示用的美元兑人民币汇率，仅供换算显示，扣费以美元为准。
GET /videos/v1/videos/jobs/stats过滤参数同 5.4。返回 total_jobs / completed_jobs / failed_jobs / in_flight_jobs / total_cost（仅计已完成）/ avg_duration_ms / fx_cny_per_usd（展示用汇率，同 5.4）。
GET /videos/v1/videos/jobs/export.csv过滤参数同 5.4。⚠️ 单次最多导出 200 行，需要更多请用 5.4 分页自行汇总。
表头（列名与 5.3 任务对象字段一一对应）：job_id, status, model, token_name, cost_final, cost_pending, duration_ms, created_at, completed_at, video_url, platform_video_url, error_code, error_detail, cost_final_cny (display only: cost_final x fx_cny_per_usd, converted at the current display FX), fx_cny_per_usd。
建素材 POST /videos/v1/videos/assets
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | ✅ | http(s) 图片、视频或音频链接（带签名参数的临时链接可直接用） |
kind | string | image（默认）/ video / audio（音频：wav / mp3，2–30 秒，≤15MB）。链接后缀与类型明显不符会被拒（asset_kind_url_mismatch） | |
name | string | ≤64 字符；不能叫「图片」或「图片N」（保留给位置语法）；同一账号内不可重名 |
响应含 id（查询与删除用）、ref（形如 asset://xxx，直接放进 image_urls）、status（Processing / Active / Failed）。只有 Active 才能用于生成（例外：MiniMax-H3 登记后即可引用，不看这个状态）。
列出素材 GET /videos/v1/videos/assets
返回 { assets: [...] }。
🔴 这个接口用于管理素材，不要用它轮询状态——轮询请用下面的「查单个素材」。
查单个素材 GET /videos/v1/videos/assets/<id>
只返回你名下的这一张，字段与列表单条相同（id、status 等）；<id> 用建素材响应里的 id 或 asset_id 均可。不属于你的、不存在的、已删除的一律 404。登记后请用它按 id 轮询（每 2～3 秒），查到 status 为 Active 即可提交生成、Failed 则换一张图重新登记，不必取回整个列表。
（可选）在多个模型之间来回切换时，可加 ?model=<模型名> 让 usable 给出 true/false（不带或填了未知模型名时为 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 / bmp / tiff）；响应含 url。只收图片：视频素材与参考视频没有上传接口——视频一律提供公网可直接下载的链接（mp4 / mov），视频工作台里也是粘贴链接，不提供本地上传。
已在用火山方舟原生格式的可直接接入 POST /videos/api/v3/contents/generations/tasks。下表只列不同之处：
| 项目 | 方舟原生 | 本平台 |
|---|---|---|
| 地址与鉴权 | https://ark.cn-beijing.volces.com/api/v3，方舟 API Key | base_url 填 https://tryaiapi.com/videos/api/v3，api_key 填本平台 API Key；漏写 /api/v3 返回 404 |
| 模型名 | 模型 ID，或推理接入点 ID（ep- 开头） | 填模型名，如 doubao-seedance-2-0-260128；ep- 接入点 ID 返回 400 |
| 任务号 | 火山方舟任务 ID | 本平台 UUID |
| 回调 | 支持 callback_url | 不支持，传了返回 400，请轮询 GET …/tasks/{id} |
| 任务列表 | 只返回最近 7 天；filter.model 填推理接入点 ID | 含 7 天以前的任务；filter.model 填模型名 |
| 取消进行中的任务 | 排队中可取消，生成中不可取消 | 已交给生成方的，供应通道支持且生成方接受时可取消（预扣全额退回），否则返回 400；本平台排队中的也返回 400；409（CancellationPending）＝已取消、结算写入中，稍后查询。已结束任务的删除同官方，账单明细保留 |
| 失败任务的错误码 | 方舟错误码 | 本平台稳定码，见 §06 错误码 |
| 成片链接 | content.video_url，24 小时有效 | content.video_url 为生成方直链，有效期见 content.expires_at；转存成功时另给 7 天平台副本 content.platform_video_url |
| 请求参数 | 按官方参数表 | 表外参数返回 400 并点名，不静默丢弃；官方支持但当前通道未接通的，提交前返回 400（unsupported_parameter），不扣费 |
| 真人参考图 | 方舟侧素材的 asset:// | 须先登记到本平台素材库，用这里返回的 asset:// |
其余请求格式、报错格式、状态枚举、参数语义与官方一致；各参数对哪个模型生效见 5.1。提示词内联参数（--rs / --dur 等）会解析成对应字段，与顶层字段不一致时返回 400；基于样片生成正式视频时，draft_task.id 填本平台的样片任务号。
最后更新：2026-09-28
06错误码
请按 code 分支，不要匹配 message 文字。
| code | HTTP | 含义 | 建议处理 |
|---|---|---|---|
input_image_real_person | 400 | 参考图疑似含真人形象 | 这张图需要先加入素材库再使用 |
input_image_too_large | 400 | 图片像素超上限 | 换小一点的图（details 里有实际尺寸与上限） |
output_content_policy | 400 | 生成内容可能涉及版权或敏感信息 | 调整参考图或提示词后重试 |
content_safety_rejected | 400 | 提交内容未通过上游内容安全审核（审的是提示词与参考素材；任务会以 failed 收场，预扣自动退回） | 检查提示词与参考素材后，换一个新的 Idempotency-Key 重试（用旧键只会返回那单失败的任务） |
reference_media_unfetchable | 400 | 参考图/视频读不到 | 检查链接是否公网可访问、是否太慢 |
invalid_asset_reference_format | 400 | 素材引用的写法不对（不是 asset://<素材ID> 的形态） | 请求方参数错误，须为 asset://<素材ID> 格式 |
invalid_asset_reference | 400 | 引用的素材不在你的库里，或这个模型用不了它 | 换一个能用它的模型，或重新建素材 |
asset_unavailable | 400 | 素材还不能用：还在处理中，或已处理失败 | Processing 等到 Active 再提交；Failed 换一张图重新登记 |
asset_library_full | 400 | 素材数量已达上限（仅在本平台为你的账号配置了素材数量上限时才会出现；默认不限） | 删除不用的素材 |
unsupported_resolution | 400 | 该模型不支持这个分辨率（例如 doubao-seedance-2.5 或极速档传了 4k、极速档传了 1080p、样片传了 480p 以外的档位） | 改用该模型支持的分辨率，见上方模型表 |
unsupported_parameter | 400 | 该模型不支持这个参数 / 取值（例如 doubao-seedance-2.0 传 draft: true 或 output_format: "mov"；原生入口写了方舟入口的字段名 ratio / content；样片正式视频又传了提示词或时长），message 会点名字段 | 按 message 去掉或改正该字段 |
invalid_draft_task | 400 | draft_task_id 用不了：不是你的任务、不是样片、还没完成、超过 7 天，或模型不同 | 重新生成样片后用新的任务号 |
frame_role_conflict | 400 | 首帧/尾帧角色不能和参考视频同时用 | 去掉其中一类，不要混用 |
asset_kind_invalid | 400 | 建素材时 kind 不是 image / video / audio | 改成这三个值之一 |
asset_kind_url_mismatch | 400 | 建素材时链接后缀与 kind 明显不符（如 .mp4 配 image） | 改 kind 或换链接 |
asset_kind_field_mismatch | 400 | 生成请求里素材类型与字段不符（如图片素材写进 video_urls、视频素材写进 image_urls、音频素材写进非 audio_urls 字段） | 图片素材放 image_urls，视频素材放 video_urls，音频素材放 audio_urls |
asset_kind_unsupported | 400 | 该模型的素材库不支持这种素材类型 | 改传公网直链 |
asset_url_invalid | 400 | 建素材的 url 不是 http(s) 链接 | 检查链接 |
invalid_inline_media | 400 | Base64 内联素材格式不对（data: 前缀、MIME 类型、编码或文件格式不符合要求）；提交前校验，不扣费 | 按 message 修正 Base64 内容，或改传公网链接 |
invalid_upload | 400 | 上传文件不合规（超出大小限制或不是支持的类型） | 按上传接口的限制重传 |
unsupported_model | 400 | 这个入口不支持该模型 | 换模型或换入口 |
idempotency_key_reused | 409 | 同一个 Idempotency-Key 被用于内容不同的请求。本页的原生入口与方舟兼容入口不会返回此码：同一把键再提交会返回首次创建的任务，见 5.1 的说明 | 换一个新的 Idempotency-Key |
billing_in_progress / billing_reconcile_required | 409 | 这一单的扣费正在进行中（或已被挂起等待人工核对） | 🔴 不要换新的 Idempotency-Key：该键对应的扣费正在进行，换键会再扣一次。请继续轮询该任务；超过一分钟仍返回此码，请联系我们 |
job_state_conflict | 409 | 请求没问题，但它指向的任务在这期间状态变了 | 先查询那个 job_id，等它到终态（completed / failed / timeout / cancelled）再换一个新的 Idempotency-Key 提交；它可能仍占着预扣，没等终态就重发会冻两份钱 |
storage_unavailable | 503 | 平台存储暂时不可用 | 稍后重试。⚠️ 若发生在提交阶段，任务可能已创建并保留预扣、等待核对：请用同一把 Idempotency-Key 重试，会回放原单；换新键可能冻两份钱 |
prompt_reserved_params | 400 | 提示词里写了 --dur / --rs 等内联参数（本原生入口不解析） | 改用 duration / resolution 等请求字段 |
inline_param_conflict | 400 | 仅方舟兼容入口：提示词内联参数与顶层字段的值不一致 | 二选一，去掉其中一处 |
audio_requires_visual | 400 | 参考音频不能单独使用 | 补一张参考图或一段参考视频 |
invalid_request | 400 | 参数不合法的通用码（类型不对、枚举值不在允许范围、超上限、时长越界等），message 会点名字段并给出允许范围。所有模型的时长越界都是这个码，没有单独的时长错误码 | 按 message 提示修正请求参数 |
too_many_reference_items | 400 | 仅 MiniMax-H3：超出它特有的素材组合上限（如首/尾帧图数量）。其余情况下参考素材超过该模型上限（见「配额与限制」）返回 invalid_request | 减少参考图 / 参考视频数量 |
frame_and_reference_mixed | 400 | 首/尾帧图与参考图混用（MiniMax-H3 等） | 二选一 |
reference_video_duration_out_of_range | 400 | 参考视频单段时长超出范围（Seedance 2.0 系列 2–15 秒；doubao-seedance-2.5 2–30 秒，视频编辑 4–30 秒） | 裁剪后重新提交 |
reference_video_total_too_long | 400 | 参考视频总时长超上限（Seedance 2.0 系列 15 秒；doubao-seedance-2.5 30 秒） | 少放一段或裁短一些 |
reference_video_duration_unverifiable | 400 | 读不出参考视频的时长（链接不是可直接下载的 MP4 / MOV，如网盘分享页、需要登录的链接） | 换一个能直接下载的公网链接 |
asset_name_too_long / asset_name_reserved / asset_name_taken | 400 | 注册素材时名字过长 / 用了保留格式「图片」「图片N」/ 与库里已有素材重名 | 换一个名字——名字就是提示词里的 @ 句柄，必须唯一且不能被截断 |
upload_expired | 409 | 通过上传接口传的图片已过保留期，不能再入库 | 重新上传后再入库 |
| 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 | 上传配额触顶（仅在本平台为上传接口启用了配额拦截时才会出现；未启用时超额只记录不拦截） | API 接入请直接提供公网链接，见「参考图」 |
rate_limit_exceeded | 429 | 请求过于频繁 | 退避后重试 |
submission_rate_limited | 429 | 本账号同时在跑的任务数、或最近一分钟的提交数触顶（不是失败，任务没有被创建、也没有扣费）；该闸可能被本平台关闭，关闭时不会返回此码 | 按响应头 Retry-After 退避后重试；details 里带当前值与上限（inflight/max_inflight 或 submits_last_minute/max_per_minute），可据此自适应降速 |
upstream_timeout | 504 | 生成超时（预扣自动退回） | 可重试 |
upstream_generation_failed | 502/503 | 生成方侧失败（预扣自动退回）；建素材时素材库暂不可用也返回此码（此时不计费） | 退避后重试 |
submission_result_ambiguous | 502 | 提交结果无法确认 | 🔴 先联系我们，不要直接重试 |
internal_error | 500 | 本平台内部错误 | 联系我们 |
billing_error | 500 | 提交前的余额核验失败（计费系统暂时不可用）；发生在预扣之前，未扣费 | 稍后重试；持续失败请联系我们 |
invalid_json | 400 | 请求体不是合法 JSON | 检查序列化与 Content-Type: application/json |
request_too_large | 413 | 请求体超过 64 MB（见「配额与限制」）；解析前拒绝，不扣费 | 缩小请求体（大文件改传链接，或先转存 / 入素材库） |
not_found | 404 | 路径不存在（method/URL 拼写或版本前缀有误，与业务层的 task_not_found / model_not_found 无关） | 核对请求地址（含 base_url 拼接，见 5.9「方舟兼容入口」差异表） |
asset_upstream_missing | 502 | 素材暂时不可用，平台正在自动恢复 | 稍后重试 |
credits_lock_unavailable | 503 | 系统繁忙，本次未扣费 | 稍后重试 |
discount_lookup_unavailable | 503 | 暂时无法计价，本次未扣费 | 稍后重试 |
upstream_state_persistence_failed | 503 | 任务可能已开始生成，但平台暂时无法记录它的状态 | 🔴 先联系我们再重试，盲目重试可能重复出片 |
upstream_channel_unavailable | 502 | 生成服务暂时不可用（与你的密钥无关） | 退避后重试；持续不恢复请联系我们 |
missing_task_id | 502 | 提交未成功，预扣自动退回 | 稍后重试 |
- 400 类：不要自动重试，请求本身要改。
- 401 / 402 / 404：不要自动重试。
- 429：指数退避。
- 502 / 503 / 504：可退避重试，但
submission_result_ambiguous例外——它表示我们无法确认那一单是否已在生成方受理，盲目重试可能重复出片重复计费。
最后更新：2026-09-28
07归属与隔离边界 🔴 接入前必读
素材与任务的归属，按你的账号划分，不按密钥划分。
如果你只在自己的服务内部调用本接口、由你决定谁能看到什么，那么下面这些不会影响到你的使用者——他们看到的一切，都由你的产品决定。但如果你打算把素材的列表、查询或删除能力转交出去（例如给使用者开一个素材管理面板，或把本接口的密钥直接发给他们），请先读完这一节。
本平台以主账号为隔离边界：同一账号下签发的所有密钥，在平台看来属于同一个主体。于是：
- 一旦你把「列出素材」「删除素材」这两个能力透传出去，使用者 A 就能看到、并且能删除使用者 B 上传的素材
- 素材库是账号级的，你名下全体使用者共用同一个素材库
- 消耗明细我们最细只能提供到密钥这一级
本平台只能识别到你的账号这一层，看不到、也无法区分你的产品上具体是哪个使用者在操作。使用者之间"谁能看到谁、谁有什么权限"，只能由你在自己的产品里实现。
不同客户之间彼此隔离：账号与账号互不可见，你看不到其他客户的素材。
🔴 合规须知：真人形象素材的授权由接入方负责。本平台的素材库通道不包含生成引擎官方的实名认证 / 活体验证流程，也不产生任何「被拍摄者已授权」的凭证。
你须自行确保：你的产品上所有上传真人形象素材的使用者，对该形象拥有合法使用与授权，并自行留存相应的授权证明；你应在与你的使用者签订的服务协议中，就此作出相应约定。涉及未成年人形象、声音等，须遵循更严格的合规要求。
最后更新：2026-09-24
08配额与限制
| 项 | 限制 | 作用域 |
|---|---|---|
| 提示词长度 | Seedance 2.0 和 Seedance 2.5 建议中文不超过 500 字、英文不超过 1000 词；MiniMax-H3 2000 字符（本平台当前入口限制，非官方上限） | 每请求 |
| 参考图数量 | Seedance 2.0 系列与 MiniMax-H3 9 张；Seedance 2.5 30 张 | 每请求 |
| 参考视频 / 音频数量 | Seedance 2.0 系列与 MiniMax-H3 各 3 段（各自总时长 ≤15 秒）；Seedance 2.5 各 10 段（各自总时长 ≤30 秒） | 每请求 |
| 单张图片像素 | 3600 万（宽×高，本平台上传预检值；对应现役供应通道生产实测的生成时上游限制，其他通道可能不同） | 每张 |
| 单张图片大小 | 30 MB | 每张 |
| 请求体总大小 | 64 MB（与官方一致；带 Base64 素材的大请求会排队依次处理） | 每请求 |
| CSV 单次导出 | 200 行 | 每请求 |
⚠️ 成片链接会过期：默认仅提供生成引擎官方直链，具体有效期以响应里的 expires_at 为准（不同模型所在的上游通道不同，多数约 24 小时），请及时下载转存到你自己的存储；如需本平台保留 7 天副本，可联系我们开通。
⚠️ 取消任务在方舟兼容入口提供，适用于当前供应通道支持取消的进行中任务：取消成功则预扣全额退回；生成方不再接受取消、或当前通道不支持取消时返回 400；还在本平台排队、尚未提交给生成方的任务同样返回 400。已结束的任务可以删除记录（见 5.9「方舟兼容入口：与方舟原生的差异」）。失败、超时的任务会自动退回预扣。
最后更新：2026-09-28
09常见接入问题
为什么我传的图被拒了？
@张三 为什么不生效？
@图片1，见「人物命名与位置语法」。我的用户之间素材互相可见，怎么办？
任务多久出片？
poll_url，不要同步等待。可以取消任务吗？
DELETE …/tasks/{id} 即申请取消，取消成功预扣全额退回；生成方不再接受取消、或当前通道不支持取消时返回 400；还在排队、尚未提交给生成方的任务同样返回 400。已结束的任务用同一个接口删除记录。失败、超时的任务会自动退回预扣。最后更新：2026-09-27
想了解更多接入细节？请联系 support@tryaiapi.com，我们会尽快与你确认接入细节。