视频模型 API 平台化接入指南

01三分钟跑通第一条视频

想先感受一下？用你的 API Key 在视频工作台直接生成一段视频，不用写代码。

最小闭环三步：提交 → 轮询 → 取片。

⚠️ 生成是异步的，出片耗时因模型、时长与画面复杂度而异。提交返回的是任务号，不是视频，请轮询响应里的 poll_url 获取结果。不要同步等待。

第一步：提交生成任务

curl 示例 · 提交任务
curl https://tryaiapi.com/videos/v1/videos/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "一段海上日出，镜头缓缓推近",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

响应里 status 初始为 queued，随后转 running；poll_url 就是下一步要轮询的地址：

响应示例 · 提交成功
{
  "job_id": "...",
  "status": "queued",
  "poll_url": "https://tryaiapi.com/videos/v1/videos/jobs/<job_id>",
  "created_at": "2026-08-22T10:03:11Z"
}

（可选）提交前先估价

请求字段与提交完全相同，只是把路径换成 /generations/estimate——不建任务、不扣费、不触发生成：

响应示例 · 估价（doubao-seedance-2.0 · 720p · 5 秒）
{
  "model": "doubao-seedance-2.0",
  "estimated_cost": 0.8132,
  "estimated_cost_cny": 5.69,
  "fx_cny_per_usd": 7,
  "currency": "USD",
  "basis": "pre_hold",
  "final_cost_may_adjust": true
}

第二步：轮询任务状态

把上一步响应里的 poll_url 原样拿来请求即可：

curl 示例 · 轮询
curl <poll_url> \
  -H "Authorization: Bearer <你的 API Key>"

第三步：取片

status 变成 completed 后，video_url 就是可下载的视频直链：

响应示例 · 已完成，可取片
{
  "job_id": "...",
  "status": "completed",
  "model": "doubao-seedance-2.0",
  "video_url": "<生成引擎官方直链，约 24 小时有效>",
  "platform_video_url": null,
  "expires_at": "2026-08-23T10:05:40Z",
  "cost_final": 0.81,
  "duration_ms": 118342,
  "metadata": { "duration": 5, "resolution": "720p" }
}

⚠️ video_url 约 24 小时后失效，请及时下载保存，不要依赖它长期可访问。

当前可用视频模型

模型	调用名（`model` 字段填这个）	支持分辨率
Seedance 2.0	`doubao-seedance-2.0`	480p / 720p / 1080p
Seedance 2.0 极速	`doubao-seedance-2.0-fast`	480p / 720p
万相 3.0	`wan3.0-video`	480p / 720p / 1080p

以上为当前可用的视频模型；完整、实时的清单以模型市场或 GET /v1/models 返回为准。

02参考图

🔴 API 提交参考图，请提供公网可访问的 URL，放进 image_urls。这与生成引擎官方的要求一致——上游只接收链接，不接收文件本身。

真人形象的图：先用这个 URL 建素材，拿到 asset://<素材ID> 后在生成请求里引用它，见下节「素材库：真人形象的唯一通道」。

（本平台另提供一个上传接口，供网页控制台在用户从本地选图时使用；平台化 API 接入用不到它，见「接口参考 → 5.8」。）

⚠️ 像素上限：单张图宽×高不得超过 3600 万像素。手机原图常见 6048×8064（约 4900 万像素），会被拒。我们无法替你提前拦截——请在你自己那侧压图，否则要到生成阶段才失败。

⚠️ 单次请求最多 9 张参考图。

03素材库：真人形象的唯一通道

为什么存在

模型对包含真人形象的参考图有内容审核，直接传图片链接会被拒。素材库是本平台提供的合规通道——先把形象注册为素材，再在生成请求里引用它。

什么时候必须用

参考图里有真人脸。如果你的业务每条视频都带真人（例如探店、口播、达人出镜），那么素材库不是可选项，是必经之路。

三步

拿到一个图片链接（自己的公网链接，或用上传接口拿一个）
调建素材接口，传入链接与名称 → 得到素材 ID
在生成请求的 image_urls 里写 asset://<素材ID>

⚠️ 建素材后有一个短暂的处理期（实测约 10 秒），处理完成才可用于生成。状态字段会告诉你处理到哪一步。

（可选）接入前先查一次该模型能不能用素材库

curl 示例 · 查询能力
BASE="https://tryaiapi.com"
curl "$BASE/videos/v1/videos/assets/capability?model=doubao-seedance-2.0" \
  -H "Authorization: Bearer <你的 API Key>"

响应示例
{
  "enabled": true,
  "upload_max_bytes": 31457280,
  "upload_max_pixels": 36000000
}

第一步：建素材

curl 示例 · 建素材
BASE="https://tryaiapi.com"
curl "$BASE/videos/v1/videos/assets" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "<你的公网图片链接>",
    "name": "服务员小李"
  }'

响应示例
{
  "id": "...",
  "asset_id": "...",
  "ref": "asset://<素材ID>",
  "name": "服务员小李",
  "status": "Processing",
  "usable": true,
  "source_url": "<你的公网图片链接>",
  "created_at": "2026-08-22T10:00:02Z"
}

素材状态：Processing（处理中）→ Active（可用于生成）/ Failed（处理失败）。只有 Active 才能在生成请求里引用。

第二步：在生成请求里引用它

把上一步拿到的 ref（asset://<素材ID>）放进 image_urls，和普通图片链接一样使用：

curl 示例 · 引用素材生成
curl https://tryaiapi.com/videos/v1/videos/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "这位人物走进店铺，面带微笑向镜头问好",
    "image_urls": ["asset://<素材ID>"],
    "resolution": "720p",
    "duration": 5
  }'

04人物命名与位置语法

多个参考图同时出现时，可以在提示词里指明"让这个人做什么"。

🔴 接口上必须使用位置语法 @图片1、@图片2，编号对应 image_urls 数组的顺序（从 1 开始）。

⚠️ 网页控制台里可以打 @张三 这种名字，接口上不行。网页版是在提交前把名字替换成位置编号再发出去的；接口这一层不做这个替换，你写的名字会被当作普通文字，人物绑定不会生效。

⇒ 如果你想让使用者用名字，替换要在你自己的平台里做：维护"名字 → 这张图排第几"的映射，提交前替换成 @图片N。

05接口参考

鉴权：所有接口用 Authorization: Bearer <你的密钥>。

错误信封（所有接口统一）：

错误响应结构
{ "error": { "code": "稳定码", "message": "说明", "type": "错误类别",
             "field": "出问题的字段（可选）", "details": { } } }

请按 code 分支处理，不要匹配 message 文字——文案可能调整，code 稳定。

5.1 提交生成任务 · POST /videos/v1/videos/generations

字段	类型	必填	说明
`model`	string	✅	模型名，≤100 字符
`prompt`	string	✅	提示词，≤2000 字符
`duration`	integer		秒，默认 5；标准范围 4–15（个别模型支持更宽的区间，例如最长可达 30 秒且可传 -1 由模型自动选择时长；越界会在提交时返回 400，具体以模型实际支持范围为准）
`resolution`	string		`480p` / `720p` / `1080p` / `4k`，默认 `720p`
`aspect_ratio`	string		`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`
`image_urls`	array		参考图，最多 9 项；两种写法见下
`video_urls`	string[]		参考视频，最多 3 项；不接受素材引用
`audio_urls`	string[]		参考音频，最多 3 项；不接受素材引用
`generate_audio`	boolean		是否生成音轨
`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>
对象：{ "url": "...", "role": "reference_image" }，role 可选 first_frame / last_frame / reference_image

请求头 Idempotency-Key（可选但强烈建议）：网络重试时带同一个键，不会重复下单、不会重复扣费。同一个键配不同的请求内容会返回 409，新任务请用新键。

成功响应：

响应示例 · 提交成功
{ "job_id": "...", "status": "queued", "poll_url": "https://tryaiapi.com/videos/v1/videos/jobs/<job_id>",
  "created_at": "2026-08-21T..." }

5.2 提交前估价 · POST /videos/v1/videos/generations/estimate

请求字段与 5.1 完全相同。不建任务、不扣费、不触发生成。

响应字段	说明
`estimated_cost`	预计费用（美元）
`estimated_cost_cny`	折算人民币（仅展示参考）
`fx_cny_per_usd`	展示汇率
`currency`	`USD`（计费本位为美元）
`final_cost_may_adjust`	`true`——实际结算可能微调

5.3 查询任务 · 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 时，表示正在与生成方确认结果，此时费用尚未结算，请勿重复提交。

5.4 任务列表 · 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 }，按提交时间倒序（不可调整）。

5.5 消费统计 · GET /videos/v1/videos/jobs/stats

过滤参数同 5.4。返回 total_jobs / completed_jobs / failed_jobs / in_flight_jobs / total_cost（仅计已完成）/ avg_duration_ms。

5.6 导出 · GET /videos/v1/videos/jobs/export.csv

过滤参数同 5.4。⚠️ 单次最多导出 200 行，需要更多请用 5.4 分页自行汇总。

5.7 素材库

建素材 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。建议接入时读取一次该接口，不要把上限固定写在你的代码里。

5.8 上传接口（网页控制台专用，API 接入通常不需要）

本平台提供一个上传接口，供网页控制台在用户从本地选图时使用——它把本地文件转成一个可用的 URL。平台化 API 接入不需要它：你直接提供你自己的公网 URL 即可，这与上游一致（见「参考图」一节）。

POST /videos/v1/videos/uploads，请求体为图片原始字节（不是表单），用 Content-Type 声明类型（image/jpeg / png / webp / gif / heic / heif）；响应含 url。

06错误码

请按 code 分支，不要匹配 message 文字。

6.1 需要让使用者知道、由他自己解决的（请把失败原因直白地告诉使用者）

code	HTTP	含义	该告诉用户
`input_image_real_person`	400	参考图疑似含真人形象	这张图需要先加入素材库再使用
`input_image_too_large`	400	图片像素超上限	换小一点的图（`details` 里有实际尺寸与上限）
`output_content_policy`	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	素材数量已达上限	删除不用的素材

6.2 你自己处理，不必打扰用户

code	HTTP	含义	建议动作
`invalid_api_key`	401/403	密钥无效或账号被禁用	检查配置，联系我们
`ip_not_allowed`	403	密钥绑定了网段，当前来源不在其中	联系我们调整
`insufficient_credits`	402	账户余额不足	充值；建议自建余额预警
`idempotency_key_reused`	409	同一个幂等键配了不同的请求内容	用新键
`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	本平台内部错误	联系我们

6.3 重试建议

400 类：不要自动重试，请求本身要改。
401 / 402 / 404 / 409：不要自动重试。
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，不要同步等待。

可以取消任务吗？

暂不支持取消。