Wan 系列
- 文生视频、图生视频、首尾帧、续写、参考生视频、视频编辑
- 支持自定义配乐与文档生视频
- 输出可带头部音轨
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
视频模型 ID，取值见下方模型列表。
画面描述。文生视频必填；图生视频建议填写，用来控制镜头运动。
wan3.0 上限 20000 字符，超出部分自动截断；wan2.7 上限 5000 字符。
反向描述，写不希望出现的内容，如模糊、变形、低质量。上限 500 字符。
输出分辨率，取值随模型变化：
wan2.5-preview：480p、720p、1080pwan2.6：720p、1080pwan2.7、wan3.0-video：720P、1080P，wan3.0另有480P
输出画幅，取值 16:9、9:16、1:1、4:3、3:4，wan3.0 还接受 adaptive。
只在文生视频生效，图生视频沿用输入图片比例。别名 aspect_ratio。
时长，单位秒。
wan2.5-preview：5或10wan2.6：5、10、15wan2.7：2 到 15wan3.0-video：2 到 30，或-1由模型自行决定
图生视频的图片，公网地址或 Base64 data URI。
1 张为首帧，2 张为首帧加尾帧。wan3.0 在参考模式下最多 10 张。
带角色的图片数组，每项含 url 与 role。
role 取值 first_frame、last_frame、reference_image。
续写或参考视频。wan2.7 只取第一段，时长 2 到 10 秒；wan3.0 最多 5 段，合计不超过 15 秒。
自定义音频。文生视频下作为背景音乐；图生视频下驱动画面节奏。
格式 wav 或 mp3，2 到 30 秒，不超过 15MB。
是否生成音轨。wan2.5 默认 true 且不支持关闭；wan3.0 默认 true 可关闭，开关不影响价格。
自动扩写提示词。短提示词收益明显，代价是生成时间变长。
随机种子，取值 0 到 2147483647。相同种子趋向相似结果，但不保证完全一致。
wan3.0 专用，取值 frame 或 reference，决定裸 image_urls 归入哪一族。
wan3.0 专用，文档生视频的输入文件。
docx、pdf、txt 等格式，不超过 100MB 或 50 页，不能与 link_url 同时使用。
wan3.0 专用，网页生视频的输入链接。必须公网可访问且无需登录。
是否在右下角添加 AI 生成标识，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
The video model ID; see the model list below.
The scene description. Required for text to video; recommended for image to video to control camera movement.
wan3.0 allows up to 20000 characters, with any excess truncated automatically; wan2.7 allows up to 5000.
A negative description of what you don't want, such as blur, distortion, or low quality. Up to 500 characters.
Output resolution; valid values depend on the model:
wan2.5-preview:480p,720p,1080pwan2.6:720p,1080pwan2.7,wan3.0-video:720P,1080P;wan3.0also has480P
Output framing: 16:9, 9:16, 1:1, 4:3, or 3:4; wan3.0 also accepts adaptive.
Takes effect only for text to video; image to video follows the input image's ratio. Alias: aspect_ratio.
Duration in seconds.
wan2.5-preview:5or10wan2.6:5,10,15wan2.7: 2 to 15wan3.0-video: 2 to 30, or-1to let the model decide
Images for image to video, as public URLs or Base64 data URIs.
1 image is the first frame; 2 are the first frame plus the last. wan3.0 accepts up to 10 in reference mode.
An array of images with roles, each with url and role.
role is first_frame, last_frame, or reference_image.
Videos for continuation or reference. wan2.7 uses only the first, 2 to 10 seconds long; wan3.0 accepts up to 5, totaling no more than 15 seconds.
Custom audio. In text to video it serves as background music; in image to video it drives the pacing.
Format wav or mp3, 2 to 30 seconds, up to 15MB.
Whether to generate an audio track. On wan2.5 it defaults to true and can't be disabled; on wan3.0 it defaults to true and can be disabled, with no effect on price.
Automatically extend the prompt. Noticeably helps with short prompts at the cost of longer generation time.
Random seed, 0 to 2147483647. The same seed trends toward similar results, though not guaranteed identical.
wan3.0 only: frame or reference, deciding which family a bare image_urls belongs to.
wan3.0 only: the input file for document-to-video.
docx, pdf, txt, and similar formats, up to 100MB or 50 pages; can't be used together with link_url.
wan3.0 only: the input link for web-page-to-video. Must be publicly reachable and require no login.
Whether to add an AI-generated mark in the bottom right; defaults to false.
模式判定
不带媒体字段是文生视频。
带 image_urls 或 image_with_roles 走图生视频：1 张首帧，2 张首尾帧，带 reference_image 角色或配合参考视频、音频、文档时转为参考生视频。
带 video_urls 是续写；带 file_url 或 link_url 是文档或网页生视频。
帧族（首帧、尾帧）与参考族（参考图、参考视频、参考音频、文档、链接）互斥，混用返回 400，不创建任务也不扣费。
No media fields means text to video.
With image_urls or image_with_roles it's image to video: 1 image is the first frame, 2 are first and last; a reference_image role, or pairing with reference video, audio, or a document, turns it into reference to video.
With video_urls it's continuation; with file_url or link_url it's document or web-page to video.
The frame family (first frame, last frame) and the reference family (reference image, reference video, reference audio, document, link) are mutually exclusive; mixing them returns a 400, creating no task and charging nothing.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
wan3.0-video | 当前旗舰，支持文档生视频与 2 到 30 秒时长 |
wan3.0-video-prime | 3.0 的高画质版，参数与 wan3.0-video 完全一致 |
wan2.7 | 文生、图生、续写三合一 |
wan2.6 | 支持镜头类型与 13 种趣味模板 |
wan2.5-preview | 支持音轨自动生成与自定义配乐 |
| Model ID | Positioning |
|---|---|
wan3.0-video | Current flagship; supports document-to-video and 2 to 30 second durations |
wan3.0-video-prime | The higher-quality 3.0 variant; parameters identical to wan3.0-video |
wan2.7 | Three in one: text, image, and continuation |
wan2.6 | Supports shot types and 13 fun templates |
wan2.5-preview | Supports automatic audio generation and custom soundtracks |
使用限制
- 帧族与参考族不能混用
file_url与link_url不能同时传- 有视频输入时，输入总时长加输出时长不超过 30 秒
- 参考图最多 10 张
- 参数错误同步返回 400，不扣费
- The frame family and reference family can't be mixed
file_urlandlink_urlcan't be passed together- With video input, total input duration plus output duration must not exceed 30 seconds
- At most 10 reference images
- Parameter errors return a 400 synchronously and aren't billed
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.