AI Video API万相 3.0 Prime API（Wan 3.0 Video Prime API）
本文介绍万相 3.0 Prime wan-3.0-video-prime，支持文生视频、首/尾帧图生视频、多模态参考生视频、参考文件和公开网页生成视频。
计费
| 分辨率 | 积分/秒 | 5 秒纯文生视频 |
|---|---|---|
480p | 18 | 90 积分 |
720p | 36 | 180 积分 |
1080p | 72 | 360 积分 |
固定时长请求没有参考视频时，计费秒数等于请求的输出时长；带 video_urls 时：
（探测到的输入视频秒数 + 请求输出秒数）× 分辨率费率
图片、音频、文件和网页不会计入输入视频时长。例如 4.5 秒参考视频 + 5 秒 720p 输出，费用为 (4.5 + 5) × 36 = 342 积分。
自动时长（duration=-1）
Prime 支持自动决定输出时长。平台先按 30 秒总计费时长 × 当前模型与分辨率费率 预扣。这 30 秒已经包含参考视频输入，不会再额外加上输入视频时长。
| 分辨率 | 预扣积分 |
|---|---|
480p | 540 |
720p | 1,080 |
1080p | 2,160 |
创建任务
POST https://api.aivideoapi.ai/v1/videos/generations
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | wan-3.0-video-prime |
input | object | 是 | 提示词、媒体和输出参数 |
callback_url | string | 否 | 接收终态通知的公网回调 URL |
input.prompt 与媒体字段各自都可选，但至少需要提供一个有效提示词或媒体输入。
Input 字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
prompt | string | — | 最长 20,000 字符 |
first_frame_url | string | — | 公网 HTTP(S) 首帧图片 URL |
last_frame_url | string | — | 公网 HTTP(S) 尾帧图片 URL；必须同时有首帧 |
image_urls | string[] | [] | 最多 10 张参考图 |
video_urls | string[] | [] | 最多 5 个 MP4/MOV；单个 1–15 秒，总计不超过 15 秒 |
audio_urls | string[] | [] | 最多 5 个 MP3/WAV；单个 1–15 秒，总计不超过 15 秒 |
file_url | string | — | 一个公网文件 URL |
link_url | string | — | 一个无需登录的公开网页 URL |
resolution | string | 1080p | 480p、720p 或 1080p |
aspect_ratio | string | adaptive | adaptive、16:9、4:3、1:1、3:4、9:16 |
duration | integer | 5 | -1 表示自动时长，或 2–30 的整数；不接受数字字符串 |
audio | boolean | true | 输出是否包含音轨 |
seed | integer | — | 0–2147483647 |
watermark | boolean | false | 是否添加水印 |
公开契约只接受公网 HTTP(S) URL。Base64、OSS URI、URL 内嵌凭据、localhost 和私网地址不在支持范围内。
模式与时长规则
- 首/尾帧模式不能与
image_urls、video_urls、audio_urls、file_url、link_url混用。 last_frame_url不能脱离first_frame_url单独提交。file_url与link_url互斥。- 同类型参考媒体保持数组顺序；提示词中的图、视频、音频分别独立编号。
- 输入视频总时长 + 输出时长不能超过 30 秒。
- 自动时长
duration=-1按 30 秒总计费上限预扣，成功后按实际时长结算。
创建响应
HTTP 200 会立即返回平台任务 ID。使用 data.taskId 查询任务状态。
{
"code": 200,
"msg": "success",
"data": {
"taskId": "cbf6b69d-4f03-4817-8ed7-94c0292184a8"
}
}
示例
自动时长
{
"model": "wan-3.0-video-prime",
"input": {
"prompt": "从日出到日落穿越城市的电影感旅程",
"resolution": "720p",
"duration": -1
}
}
文生视频
curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "wan-3.0-video-prime",
"callback_url": "https://your-server.com/webhook",
"input": {
"prompt": "一只小猫在月光下的屋顶奔跑，远处城市霓虹闪烁，电影感运镜",
"resolution": "1080p",
"aspect_ratio": "16:9",
"duration": 5,
"audio": true
}
}'
首尾帧生视频
{
"model": "wan-3.0-video-prime",
"input": {
"prompt": "人物从微笑逐渐变为大笑，背景从冷光转为暖光",
"first_frame_url": "https://example.com/first.jpg",
"last_frame_url": "https://example.com/last.jpg",
"duration": 6
}
}
图片、视频与音频混合参考
{
"model": "wan-3.0-video-prime",
"input": {
"prompt": "视频1提供镜头运动，图1提供角色外观，音频1引导背景音乐",
"image_urls": ["https://example.com/character.png"],
"video_urls": ["https://example.com/camera.mp4"],
"audio_urls": ["https://example.com/music.mp3"],
"resolution": "720p",
"duration": 5
}
}
使用 file_url 传入支持的公网文档，或用 link_url 传入公开网页；一次请求不能同时传两者。
查询任务状态
curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
-H "Authorization: Bearer sk-your-api-key"
任务状态为 pending、processing、completed、failed。确认失败时只退款一次；自动时长任务成功后只在结算时退还未使用的预扣差额，绝不触发失败退款。上游记录过期成为 UNKNOWN 时，本地会标记为不可自动退款的失败并保留已消费积分，等待人工核对。Wan 3.0 Prime 不支持取消。
等待中响应
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "pending",
"model": "wan-3.0-video-prime",
"credits_consumed": 0,
"created_at": 1786330800,
"estimated_seconds": 300
}
处理中响应
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "processing",
"model": "wan-3.0-video-prime",
"credits_consumed": 0,
"created_at": 1786330800,
"progress": null
}
成功响应
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "completed",
"model": "wan-3.0-video-prime",
"credits_consumed": 360,
"created_at": 1786330800,
"completed_at": 1786330928,
"output": {
"urls": [
"https://dashscope-result.oss-cn-beijing.aliyuncs.com/example.mp4"
],
"metadata": {
"usage": {
"duration": 5,
"input_video_duration": 0,
"output_video_duration": 5,
"video_count": 1,
"fps": 24,
"SR": 1080,
"ratio": "16:9"
}
}
},
"usage": {
"total_seconds": 5,
"input_seconds": 0,
"output_seconds": 5,
"video_count": 1,
"fps": 24,
"resolution": 1080,
"ratio": "16:9"
}
}
任务进行中以及确认失败退款后，credits_consumed 为 0；成功时为结算后的最终消耗积分。实际时长无法核验时，该字段保留预扣积分。存在对应数据时，Wan 3.0 Prime 成功任务会同时返回顶层 usage。回调与任务查询返回相同的最终积分。
自动时长结算响应
以 duration=-1、720p 和一个 4.5 秒参考视频创建 Prime 任务，若最终输出为 5 秒，查询成功响应节选如下：
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "completed",
"model": "wan-3.0-video-prime",
"credits_consumed": 342,
"output": {
"urls": ["https://example.com/generated-video.mp4"]
},
"usage": {
"input_seconds": 4.5,
"output_seconds": 5
}
}
usage.input_seconds 和 usage.output_seconds 分别表示返回的实际输入与输出视频时长。该例先预扣 1,080 积分，再将 1,080 - 342 = 738 积分自动退回余额；任务查询和成功回调中的 credits_consumed 均为 342。响应不会新增单独的退款金额字段。usage 字段仅在结果提供对应数值时返回，不能将缺失字段当作 0。
失败响应
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "failed",
"model": "wan-3.0-video-prime",
"credits_consumed": 0,
"created_at": 1786330800,
"error": {
"code": "upstream_error",
"message": "Video generation failed"
}
}
上游记录过期成为 UNKNOWN 时，响应状态同样为 failed，但 credits_consumed 会保留预扣积分，因为该状态不可自动退款。
上游成功链接大约保留 24 小时。账户已开启 Bailian R2 转存时，平台会保存结果；未开启时请及时下载 provider URL。
回调通知
创建任务时，在请求体顶层传入 callback_url。任务变为 completed 或 failed 后，平台会向该地址发送 HTTP POST 通知；pending 和 processing 不触发回调。
配置回调地址
callback_url 与 model、input 同级，不要放入 input。地址必须是公网可访问的 HTTP(S) URL，建议使用 HTTPS；不支持 localhost 或内网地址。
{
"model": "wan-3.0-video-prime",
"callback_url": "https://your-server.com/webhooks/wan",
"input": {
"prompt": "一只猫在阳光下的花园里漫步",
"resolution": "720p",
"duration": 5
}
}
将以上请求体提交到 POST /v1/videos/generations，并保存创建响应中的任务 id，用于关联回调和查询结果。
回调请求头
| Header | 说明 |
|---|---|
Content-Type | application/json |
X-Event | 成功为 task.completed，失败为 task.failed |
X-Task-Id | 任务 ID，与请求体中的 id 相同 |
X-Timestamp | 本次通知发送时的 Unix 时间戳，单位为秒 |
回调请求体直接是任务对象，没有额外的 event 或 data 包装层。这些请求头不包含签名；业务处理前可使用 API Key 查询对应任务，核对任务归属和最终结果。
成功回调
以下示例对应无参考视频、720p、5 秒输出的任务，X-Event 为 task.completed：
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "completed",
"model": "wan-3.0-video-prime",
"credits_consumed": 180,
"created_at": 1786330800,
"completed_at": 1786330928,
"output": {
"urls": ["https://example.com/generated-video.mp4"]
},
"usage": {
"input_seconds": 0,
"output_seconds": 5
}
}
从 output.urls 获取成品视频。usage 仅在有对应数据时返回，其他可选字段见上方查询响应。对于 duration=-1，回调中的 credits_consumed 为最终消耗，与任务查询结果一致。
失败回调
X-Event 为 task.failed，请求体通过 error 返回失败信息。以下为已确认失败并退款的示例：
{
"id": "cbf6b69d-4f03-4817-8ed7-94c0292184a8",
"status": "failed",
"model": "wan-3.0-video-prime",
"credits_consumed": 0,
"created_at": 1786330800,
"error": {
"code": "upstream_error",
"message": "Video generation failed"
}
}
失败回调不包含 output 和 completed_at；各字段含义与上方失败查询响应一致。
接收响应与重试
接收端应在可靠保存通知后，于 10 秒内返回任意 2xx 状态码。例如返回以下响应即可确认接收，无需响应体；耗时的后续处理可异步执行。
HTTP/1.1 204 No Content
请求级 callback_url 因网络错误、超时或非 2xx 响应投递失败时，最多尝试 3 次（含首次）：
| 投递次数 | 时机 |
|---|---|
| 第 1 次 | 任务进入终态后 |
| 第 2 次 | 第 1 次失败约 3 分钟后 |
| 第 3 次 | 第 2 次失败约 10 分钟后 |
重试由定时任务执行，实际投递可能稍晚于上述时间。同一通知可能重复到达，请按任务 id 和 status 做幂等处理，避免重复更新业务记录。
回调投递失败不会改变生成任务结果。未收到通知或重试结束后，可使用 API Key 调用 GET /v1/tasks/{taskId} 查询最终结果。通用说明见回调文档。
常见错误码
请求失败时，API 返回 JSON 格式的错误响应：
{
"error": {
"code": "insufficient_credits",
"message": "Your credit balance is too low. Please top up.",
"type": "billing_error"
}
}
错误码一览
| HTTP 状态码 | 错误码 | 类型 | 说明 |
|---|---|---|---|
| 400 | invalid_request | invalid_request_error | 缺少必填参数或参数无效 |
| 401 | invalid_api_key | authentication_error | API Key 无效、已禁用或已删除 |
| 402 | insufficient_credits | billing_error | 积分余额不足，请充值 |
| 403 | ip_not_allowed | permission_error | 请求 IP 不在 Key 的白名单中 |
| 404 | model_not_found | invalid_request_error | 模型不存在或已停用 |
| 404 | task_not_found | invalid_request_error | 任务 ID 不存在 |
| 429 | rate_limit_exceeded | rate_limit_error | 请求过于频繁，请降低频率 |
| 429 | spend_limit_exceeded | billing_error | 达到 Key 的消费限额（每小时/每天/总量） |
| 500 | internal_error | api_error | 服务器内部错误 |
| 503 | upstream_error | upstream_error | 上游 AI 服务返回错误 |
常见场景
invalid_request (400)
缺少必填字段或参数格式错误时返回。
{
"error": {
"code": "invalid_request",
"message": "'model' is required.",
"type": "invalid_request_error"
}
}
insufficient_credits (402)
积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。
invalid_api_key (401)
可能原因：
- Key 不以
sk-开头 - Key 已被禁用或删除
- 用户账户已被封禁
upstream_error (503)
上游 AI 服务返回错误，可能原因：
- 输入内容包含敏感或违规信息
- 上游服务暂时不可用
- 请求参数不被上游支持
因上游错误导致任务失败时，预扣积分会自动退还。