Wan 3.0
用提示词、首尾帧，或者参考图、参考视频、参考音频生成带声音的视频，按出片时长计费。
Wan 3.0（产品 wan）用提示词、首帧（也可以加上尾帧），或者参考图、参考视频、参考音频生成视频，出片默认带声音。有两个版本。
mode | 说明 |
|---|---|
text_to_video | 文生视频：只用提示词生成 |
image_to_video | 首尾帧生视频：指定首帧（也可以加上尾帧）生成 |
reference_to_video | 参考生成：用参考图、参考视频、参考音频生成新视频 |
版本
每个任务用 variant 选一个：standard 或 prime。两个版本的参数和分辨率（480p、720p、1080p）都一样，prime 更贵，见价格。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口，model 传 "wan-3.0"。接口通常不到 1 秒返回，几秒内冻结费用，一般 1–5 分钟出片；任务结束后获取结果。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>，见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串，建议用 UUID（1–255 个字符），见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | wan-3.0 |
variant | string | 是 | standard 或 prime，见版本，决定价格 |
mode | string | 是 | text_to_video、image_to_video 或 reference_to_video |
prompt | string | 是 | 描述要生成的画面，最长 8000 字符，建议用英文。可以用 <<<image_1>>>、<<<video_1>>>、<<<audio_1>>> 指代素材，见引用素材 |
image_urls | string[] | image_to_video 必填；reference_to_video 可选；text_to_video 不能传 | image_to_video：1–2 张，第 1 张是首帧，第 2 张（可选）是尾帧。reference_to_video：最多 10 张参考图 |
video_urls | string[] | 只有 reference_to_video 能传，可选 | 最多 5 段参考视频：每段 1–15 秒，加起来不超过 15 秒，并且加起来再加上 duration 不超过 30 秒。见素材 |
audio_urls | string[] | 只有 reference_to_video 能传，可选 | 最多 5 段参考音频（mp3 或 wav）：每段、加起来都不超过 15 秒 |
resolution | string | 是 | 480p、720p 或 1080p，决定价格 |
aspect_ratio | string | text_to_video、reference_to_video 必填；image_to_video 不能传 | text_to_video：16:9、9:16、1:1、4:3 或 3:4。reference_to_video：这几个或者 auto，auto 跟随参考图、参考视频的比例（只有参考音频时按 16:9）。image_to_video 跟随首帧 |
duration | integer | 是 | 出片时长（秒），2–30，按它计费，见价格。带了参考视频时最多是 30 − 视频段数 |
generate_audio | boolean | 否 | 出片是否带声音，默认 true。带不带都是同一个价 |
enable_thinking | boolean | 否 | true 时生成前先让模型推理提示词，更贴合描述，但更慢。默认 false |
webhook_url | string | 否 | 任务成功或失败时通知该地址：https，最长 2048 字符，不能指向内网、回环或保留地址。见回调 |
- 参数检查：参数不符合所选模式的规则时（例如
text_to_video传了image_urls或aspect_ratio: auto、image_to_video传了aspect_ratio、reference_to_video一样素材都没传），返回400 invalid_request，param是对应的参数名，任务不会创建；传了其他参数也一样。见错误。 - 提示词：建议用英文写，效果更好。
响应：200 OK。data 是刚创建的任务，只有下面这几个字段，各字段的含义见创建任务的返回。保存 data.id，用它获取结果。任务创建后仍可能失败（例如素材下载不了），以查询或回调的结果为准。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbq5w8m2c4x7b0n3q6t9e1r5",
"model": "wan-3.0",
"status": "queued",
"error": null,
"created_at": "2026-11-11T08:30:00Z"
}
}文生视频
只用 prompt 生成视频。
standard、720p、16:9、5 秒：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2a7e4c90-5b1d-4f36-8a2c-9d6e0b3f7a18" \
-d '{
"model": "wan-3.0",
"variant": "standard",
"mode": "text_to_video",
"prompt": "A golden retriever running along a beach at sunset, cinematic tracking shot",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration": 5
}'首尾帧生视频
从 image_urls 的第 1 张图开始生成，传了第 2 张时以它结尾，prompt 描述中间发生什么。比例跟随首帧，所以不能传 aspect_ratio。两张图的横竖请保持一致（都是横图或都是竖图），一横一竖时可能生成失败。
prime、首尾帧、1080p、5 秒：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8c5b3e17-0d9a-4e62-b7f4-1a6c2e8d5b39" \
-d '{
"model": "wan-3.0",
"variant": "prime",
"mode": "image_to_video",
"image_urls": [
"https://example.com/first_frame.jpg",
"https://example.com/last_frame.jpg"
],
"prompt": "The woman turns around and walks toward the window, the camera follows her",
"resolution": "1080p",
"duration": 5
}'参考生成
让参考图里的人物、物体出现在新视频里，照着参考视频里的动作、运镜，或者用参考音频做声音。image_urls、video_urls、audio_urls 至少传一样，只传参考音频也可以。
参考图（image_urls） | 参考视频（video_urls） | 参考音频（audio_urls） | |
|---|---|---|---|
| 数量 | 最多 10 张 | 最多 5 段 | 最多 5 段 |
| 时长 | – | 每段 1–15 秒；加起来不超过 15 秒（duration 超过 15 秒时不超过 30 − duration） | 每段、加起来都不超过 15 秒 |
带了参考视频时，duration 最多是 30 − 视频段数。其他要求见素材。
一张参考图、一段参考视频加背景音乐，480p、5 秒，比例 auto（跟随参考图和参考视频）：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5e0f8a26-3c7b-4d91-a4e8-6b2d9c1f0a73" \
-d '{
"model": "wan-3.0",
"variant": "standard",
"mode": "reference_to_video",
"image_urls": ["https://example.com/cat.jpg"],
"video_urls": ["https://example.com/camera_move.mp4"],
"audio_urls": ["https://example.com/music.mp3"],
"prompt": "The cat from <<<image_1>>> sits on the car hood, the camera moves like in <<<video_1>>>, with <<<audio_1>>> as the background sound",
"resolution": "480p",
"aspect_ratio": "auto",
"duration": 5
}'获取结果
一般 1–5 分钟出片：分辨率越高、时长越长越慢，enable_thinking 为 true 时也更慢。任务结束（成功或失败）后用下面任一方式拿结果：
- 回调（生产环境推荐）：创建时传了
webhook_url，任务结束时会把完整的任务推送一次，见回调。 - 轮询：用
data.id调用GET /v1/tasks/{task_id}，间隔 15 秒以上，直到status为succeeded或failed；多个任务用列出任务的ids一次查询。
| 字段 | Wan 3.0 |
|---|---|
outputs[0].url | 成片，mp4（H.264，30fps，例如 1080p 16:9 是 1920×1080），generate_audio 为 true（默认）时带声音。从任务完成起保存 15 天 |
outputs[0].preview_url | 无声的压缩版，适合预览，宽最多 600；压缩失败时为 null（请用 url）。见结果 |
billing.billed_seconds | duration |
input | 你提交的参数；素材、generate_audio、enable_thinking 传了才有 |
失败时冻结的钱全额退回，原因在 data.error.type，见错误。完整的字段见任务对象。
素材
所有素材都以公开的 http(s) 链接提交。不提供上传接口，请自行托管文件。链接最长 4096 字符，必须能直接下载，不能指向 localhost 或内网、回环、保留地址。
| 参数 | 是什么 | 哪些模式 |
|---|---|---|
image_urls | 图片：首帧和尾帧（最多 2 张），或者参考图（最多 10 张） | image_to_video、reference_to_video |
video_urls | 参考视频，最多 5 段 | reference_to_video |
audio_urls | 参考音频（mp3 或 wav），最多 5 段 | reference_to_video |
素材要满足下面的要求：
| 素材要求 | 不满足时任务失败 |
|---|---|
| 每段参考视频 1–15 秒 | video_too_short / video_too_long |
参考视频加起来不超过 15 秒；duration 超过 15 秒时，加起来不超过 30 − duration 秒 | video_too_long |
| 每段参考视频的画面比例不超过 2.5:1 | invalid_media |
| 每段参考音频、所有参考音频加起来都不超过 15 秒 | invalid_media |
素材下载不了、读不了（损坏、格式不支持）时，任务失败（invalid_media）。
Wan 3.0 的所有素材都在任务提交给生成服务后才读取（创建后几秒内），这时已经冻结过费用，上面这些创建任务时都不检查；素材用不了时，冻结的费用全额退回。任务结束前所有链接都要保持可访问，有有效期的链接也不能提前过期。
在提示词里引用素材
prompt 里写 | 指的是 |
|---|---|
<<<image_1>>>、<<<image_2>>>… | image_urls 里的图片，按顺序编号 |
<<<video_1>>>、<<<video_2>>>… | video_urls 里的视频，按顺序编号 |
<<<audio_1>>>、<<<audio_2>>>… | audio_urls 里的音频，按顺序编号 |
每种素材各自从 1 开始编号。
价格
费用 = 出片时长 duration × 所选版本和分辨率的每秒单价正在读取当前价格…
计费秒数就是请求的 duration（2–30 秒）。每秒单价只看 variant 和 resolution：模式、参考图、参考视频、参考音频、出片带不带声音（generate_audio）、enable_thinking 都不影响价格。
例如上面的文生视频请求（standard、720p、5 秒）冻结 5 × standard 的 720p 每秒单价，成功后扣同样的金额，失败全额退回。冻结和扣费的通用规则见计费。
正在读取当前价格…
价格只看请求就能算出来，可以在提交前显示：当前单价从 GET /v1/products 读取，prices 每个版本、每个分辨率一行（看这一行的 variant）。价格会调整，不要写死；实际费用以查询任务返回的 billing.frozen 为准。
错误
Wan 3.0 特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误，全部失败原因见失败原因。
创建请求出错：请求返回 HTTP 错误，任务不会创建。param 是对应的参数名。
| 状态码 | error.type | 何时出现 | 怎么处理 |
|---|---|---|---|
400 | invalid_request | 少传了必填参数（Field required），或者 variant、mode、resolution、duration 不是允许的值（例如 Input should be 'standard' or 'prime' for wan-3.0） | 必填参数都要传，取值见创建任务 |
400 | invalid_request | text_to_video、reference_to_video 没传 aspect_ratio（aspect_ratio is required for mode text_to_video），image_to_video 传了 aspect_ratio（aspect_ratio is not allowed for mode image_to_video; the output follows the first frame），或者取值不是这个模式能用的（text_to_video 传了 auto：Input should be '16:9', '9:16', '1:1', '4:3' or '3:4' for mode text_to_video） | 按模式改好 aspect_ratio，见创建任务 |
400 | invalid_request | 素材不符合模式的规则：text_to_video 传了素材（image_urls is not allowed for mode text_to_video）；image_to_video 没传 image_urls、超过 2 张，或者传了 video_urls、audio_urls；reference_to_video 三样都没传（param 为 image_urls，message 是 image_urls, video_urls or audio_urls is required for mode reference_to_video），或者参考图超过 10 张、参考视频超过 5 段、参考音频超过 5 段 | 按 param 改好参数后重新请求 |
400 | invalid_request | duration 超过 30 − 参考视频段数，param 为 "duration"（例如 duration must be at most 29 with 1 reference video: the videos (at least 1 second each) plus duration must be at most 30 seconds） | 调小 duration，或者少带几段参考视频 |
400 | invalid_request | 传了这个模型没有的参数（Extra inputs are not permitted） | 去掉这个参数 |
创建接口的其他错误（401、402、429 等）见创建任务 → 错误。
任务失败：创建请求成功（200），任务之后变成 failed。这种情况没有 HTTP 状态码，原因在任务的 error.type，通过查询任务或回调拿到。
error.type | 何时出现 | 怎么处理 |
|---|---|---|
insufficient_balance | 可用余额不够 duration × 每秒单价。创建后几秒内出现，不冻结费用 | 充值后重新创建 |
spend_limit_exceeded | 加上这个任务的费用会超出 API Key 的消费限额。创建后几秒内出现，不冻结费用 | 到控制台 → API Keys 调高限额，或等限额重置后重新创建 |
invalid_media | 图片、视频或音频下载不了或读不了（损坏、格式不支持），参考视频的画面比例超过 2.5:1，或者参考音频有一段超过 15 秒（The audio duration must be at most 15 seconds.）、加起来超过 15 秒（The total duration of the audio files must be at most 15 seconds.）。提交后几秒内下载素材时才发现 | 按 error.message 换掉有问题的素材或裁剪音频，重新创建 |
content_policy | 提示词或素材不符合内容政策：含不适宜内容，或含受保护的肖像、版权内容（例如公众人物照片）。被模型服务商的审核拦下的素材也算。提交给生成服务时或生成过程中被拦下 | 原样重新提交还会失败，请更换提示词或素材 |
video_too_short | 有一段参考视频不到 1 秒。提交后几秒内下载视频时才发现，started_at 可能为 null | 换成 1–15 秒的参考视频，重新创建 |
video_too_long | 有一段参考视频超过 15 秒，或者加起来超过 15 秒（duration 超过 15 秒时是超过 30 − duration 秒）。提交后几秒内下载视频时才发现，started_at 可能为 null | 裁剪视频（或少带几段），重新创建 |
generation_failed | 生成失败或超时 | 稍后重新创建，或者换一份提示词、素材 |
queue_timeout / internal_error | 排队超过 30 分钟未开始 / 内部错误 | 稍后重新创建 |
error.message 只说要求，不说你的文件多长，全部说明见每种原因的 message。所有失败的任务都已全额退回冻结金额，billing.charged 为 "0.00"：invalid_media、video_too_short、video_too_long 是在冻结之后失败的，billing.frozen 是冻结的金额，refunded 等于 frozen。