Wan 3.0 视频生成 API 对接手册

更新日期：2026-11-03。适用于 wan3.0-video、wan3.0-video-prime、wan3.0-video-p 与 wan3.0-video-prime-p。四款模型使用相同的知梦视频对外 JSON 格式，按模型、分辨率和计费秒数以人民币结算。

打开 Wan 3.0 在线调试 →

接口与鉴权

用途	方法	地址	鉴权
创建异步任务	POST	https://movie.zmoapi.cn/v1/videos	用户 Bearer API Key
查询任务	GET	https://movie.zmoapi.cn/v1/videos/{task_id}	用户 Bearer API Key
下载成片	GET	https://movie.zmoapi.cn/v1/videos/{task_id}/content	用户 Bearer API Key，需跟随重定向
查询公开价格	GET	https://movie.zmoapi.cn/api/pricing	无需密钥，查看对应模型的 request_price_tiers

Base URL 为 https://movie.zmoapi.cn。创建请求设置 Content-Type: application/json，创建、查询和本站下载接口使用 Authorization: Bearer YOUR_API_KEY。密钥请保存在服务端环境变量，勿提交到公开仓库。

流程为：提交任务 → 保存返回的完整公开任务 ID → 轮询查询 → completed 后获取视频。创建成功不代表已生成成片。网页工作台的上传入口使用网页登录会话，不能当作 Bearer API Key 的上传接口；外部 API 客户端提供公网可读素材 URL。

模型、时长与公开售价

以下均为客户售价，单位为人民币 CNY / 计费秒。— 表示不支持该分辨率。

精确模型 ID	输出整数秒	480P	720P	1080P	参考视频计费
wan3.0-video	2–30	¥0.30	¥0.32	¥0.34	免费，仍须通过校验
wan3.0-video-prime	仅 15、30	—	¥0.30	¥0.34	免费，仍须通过校验
wan3.0-video-p	5–30	¥0.29	¥0.45	¥0.79	按同模型、同分辨率秒价另计
wan3.0-video-prime-p	5–30	¥0.39	¥0.69	¥1.25	按同模型、同分辨率秒价另计

请使用表中的精确 ID，不附加固定分辨率后缀；分辨率由 resolution 指定。wan3.0-video-prime-p 支持 5–30 秒，只有普通 Prime 限定 15/30 秒。

计费方式

参考图片和参考音频不另收费。普通两款的参考视频也免费；P 两款按服务端读取的参考视频真实总时长合计后向上取整一次收费：

输出费用 = duration × 对应模型及分辨率的每秒单价

普通两款：参考视频附加费 = 0
P 两款：参考计费秒数 = ceil(所有参考视频实际秒数之和)
        参考视频附加费 = 参考计费秒数 × 同一档每秒单价

总基础费用 = 输出费用 + 参考视频附加费

例如 2.4 秒与 3.1 秒参考视频，应按 ceil(2.4 + 3.1) = 6 秒收费，不是分别取整得到 7 秒。客户端提供的时长提示不能作为计费依据；素材实际时长和可用性由服务端核验。账户适用分组和最终金额以提交时配置及消费记录为准。

示例	基础费用
普通版，480P，输出 2 秒 + 参考视频 5 秒	2 × ¥0.30 = ¥0.60
Prime，720P，输出 15 秒 + 参考视频 5 秒	15 × ¥0.30 = ¥4.50
标准 P，720P，输出 8 秒 + 参考视频 2.4 秒、3.1 秒	(8 + ceil(5.5)) × ¥0.45 = ¥6.30
Prime P，720P，输出 5 秒 + 参考视频 4.2 秒	(5 + ceil(4.2)) × ¥0.69 = ¥6.90

请求参数

四款模型统一推荐以下平铺格式；纯文生视频省略三个参考数组即可：

{
  "model": "wan3.0-video-p",
  "prompt": "参考图片的人物与参考视频的动作方向，结合音频氛围生成新的八秒短片",
  "duration": 8,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "reference_images": ["https://example.com/person.jpg"],
  "reference_videos": ["https://example.com/motion.mp4"],
  "reference_audios": ["https://example.com/ambience.wav"]
}

字段	类型	必填	说明
model	string	是	上表四个精确模型 ID 之一，不做静默型号替换。
prompt	string	是	去除首尾空白后非空的视频描述；用文字说明希望参考的主体、动作与镜头，无需写 @1。
duration	integer	是	输出秒数：普通版 2–30、普通 Prime 仅 15/30、P 两款 5–30。不可传小数。
resolution	string	是	480P / 720P / 1080P，普通 Prime 无 480P；建议按此大写形式提交。
aspect_ratio	string	否	默认 16:9；支持值见下表，auto 会规范化为 adaptive。
reference_images	string[]	否	公网 HTTP(S) 图片直链，去重后最多 10 张。
reference_videos	string[]	否	公网 HTTP(S) 视频直链；去重后普通两款最多 5 段，P 两款最多 10 段。
reference_audios	string[]	否	公网 HTTP(S) 音频直链；去重后普通两款最多 5 段，P 两款最多 10 段。仅代表输入参考音频。

模型	合法 aspect_ratio
wan3.0-video、wan3.0-video-prime	adaptive、16:9、9:16、1:1、4:3、3:4、21:9
wan3.0-video-p、wan3.0-video-prime-p	adaptive、16:9、9:16、1:1

当前这四款模型不支持以 audio、generate_audio、prompt_extend、watermark、seed 控制输出。不要根据发送这些字段推断它们已生效。first_frame / last_frame 也不是当前可用的素材类型，参考图不承诺精确首尾帧。

兼容字段与冲突规则

已有客户端可兼容 seconds / duration_seconds（时长）、size（分辨率）、ratio（画幅）。素材也可用顶层 media 或 input.media 的 {type, url} 项，类型仅限 reference_image、reference_video、reference_audio。P 两款还兼容 input.prompt 和 parameters.duration/resolution/ratio。

新客户端统一采用上面的平铺字段，不将多套别名混入同一请求。顶层和嵌套提示词并存时须一致，时长、分辨率等重复参数若冲突会被拒绝。旧文档的 metadata.input.media、首尾帧和控制开关写法不再作为当前接入示例。

参考素材限制

素材	数量（去重后）	格式及体积	实际时长
图片	四款均最多 10 张	建议 JPG / PNG / WebP，须为可读取图片直链	视觉参考，不保证逐帧复制
视频	普通最多 5 段，P 最多 10 段	真实有效 MP4 / MOV；每个文件 ≤64 MiB	每段 >0 且 ≤15 秒；全部视频合计 ≤15 秒
音频	普通最多 5 段，P 最多 10 段	MP3 / WAV / M4A / AAC / OGG / FLAC；每个文件 ≤64 MiB	单段及全部音频总长均 ≤15 秒

视频和音频会由服务端主动下载并校验媒体结构、非空内容、大小和真实时长，下载须返回 HTTP 200。URL 扩展名或调用方填写的时长不能代替真实媒体校验。视频总长与音频总长各自校验；图片和音频不增加计费秒数。

普通两款另要求 输出时长 + 参考视频实际总长 ≤30 秒，因此输出 30 秒时不能带非零参考视频；即使参考视频免费，也执行该限制。P 两款没有这一合并上限，可输出 30 秒并搭配总长不超过 15 秒的参考视频。

URL 须在提交、验证及生成期间持续可访问。不要使用私网地址、需要登录/Cookie 的页面、已过期签名 URL 或网页分享地址。外部 API 不使用工作台的 @1 标记传递素材，素材通过参考数组中的 URL 关联。

调用示例

以下示例地址均为占位图片/视频，使用前替换为可公开下载的真实素材链接。

纯文生视频

curl 'https://movie.zmoapi.cn/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "wan3.0-video",
    "prompt": "海浪拍打礁石，镜头缓缓推进，电影质感",
    "duration": 2,
    "resolution": "480P",
    "aspect_ratio": "16:9"
  }'

Prime 图片参考

{
  "model": "wan3.0-video-prime",
  "prompt": "参考图片中的人物外观，在花园中缓缓行走，镜头稳定跟随",
  "duration": 15,
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "reference_images": ["https://example.com/person.jpg"]
}

将上面的 JSON 提交到同一个 POST /v1/videos。这是一张普通视觉参考图，不是精确首帧控制。

Prime P 视频参考

{
  "model": "wan3.0-video-prime-p",
  "prompt": "参考视频中的主体和运镜方向，生成新的五秒镜头",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "reference_videos": ["https://example.com/motion.mp4"]
}

参考视频假设实测 4.2 秒，则计费秒数为 5 + ceil(4.2) = 10 秒，基础费用为 10 × ¥0.69 = ¥6.90。实际以服务端实测为准。

Python 创建、查询与获取结果

import os
import time
import requests

base_url = "https://movie.zmoapi.cn"
headers = {"Authorization": "Bearer " + os.environ["ZHIMENG_VIDEO_API_KEY"]}
payload = {
    "model": "wan3.0-video-p",
    "prompt": "海边日落，镜头缓缓推进",
    "duration": 8,
    "resolution": "720P",
    "aspect_ratio": "16:9",
}
response = requests.post(base_url + "/v1/videos", headers=headers,
                         json=payload, timeout=(10, 180))
response.raise_for_status()
task = response.json()
task_id = task.get("id") or task.get("task_id")
if not task_id:
    raise RuntimeError("创建响应没有公开任务 ID，请核对任务记录，不要盲目重发")
print("保存任务 ID：", task_id)

for _ in range(120):
    status = task.get("status")
    if status == "completed":
        url = (task.get("content") or {}).get("url")
        url = url or task.get("result_url") or task.get("video_url") or task.get("url")
        print("成片地址：", url or "请使用本站 /content 下载接口")
        break
    if status == "failed":
        raise RuntimeError(task.get("error") or task.get("message") or "生成失败")
    time.sleep(10)
    response = requests.get(base_url + "/v1/videos/" + task_id,
                            headers=headers, timeout=(10, 60))
    response.raise_for_status()
    task = response.json()
else:
    raise TimeoutError("本次等待结束，请使用已保存任务 ID 继续查询，不要重新创建")

生产环境应保存完整任务 ID；查询暂时失败或超时后继续查询同一任务，不自动重新发送创建请求。上例在异常时退出等待，但已打印的任务 ID 仍可用于恢复查询。

查询、状态与下载

创建响应示意：

{"id": "task_xxxxxxxxx", "task_id": "task_xxxxxxxxx", "status": "queued"}

原样保存完整的 id 或 task_id，不要截断、修改或使用渠道内部 ID。建议每 10–20 秒查询一次：

curl 'https://movie.zmoapi.cn/v1/videos/task_xxxxxxxxx' \
  -H 'Authorization: Bearer YOUR_API_KEY'

status	含义	处理
queued	排队中	继续查询
in_progress	正在生成 / 处理	继续查询
completed	已完成	获取结果并及时下载
failed	失败	停止轮询，读取 error / message

HTTP 200 或 progress: 100 均不能单独证明完成，以 status 为准。完成后优先读取 content.url，兼容 result_url、video_url、url。创建响应不保证立即带有视频 URL。

需要经本站下载时，使用同一 API Key 并跟随重定向：

curl --location 'https://movie.zmoapi.cn/v1/videos/task_xxxxxxxxx/content' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output result.mp4

只向知梦视频 API 入口发送 API Key；不要把密钥附加到外部素材或成片存储域名。使用 cURL 跟随重定向时不要启用将认证头发送给其他主机的 --location-trusted。

错误处理

状态 / 错误类型	排查要点
400 invalid_request	四个精确模型 ID、合法 JSON、非空提示词、该模型时长/分辨率/画幅、字段别名冲突、素材数量
400 invalid_reference_video	URL、HTTP 200、非空、MP4/MOV 结构、64 MiB、单段/总时长及普通款合并时长限制
400 invalid_reference_audio	音频 URL、格式、64 MiB、单段与总长 ≤15 秒
401 / 403 / model_disabled	密钥、分组、模型权限、开关和额度
429	按响应退避，避免高频重复查询或提交
5xx / 客户端超时	检查已保存的任务 ID 和任务记录，先查询状态，避免盲目重新创建

参数通过或任务提交成功不保证画面逐帧遵循参考素材。失败与扣退费以平台任务记录和消费明细为准。

结果保存和有效期

完成后请尽快下载，以实际链接有效期为准。成片存储链接可能属于其他域名，也可能是本站代理链接，不能将其当作永久地址；本站创建、查询、/content 下载入口始终使用 movie.zmoapi.cn。

网页工作台的 Wan 成片有效期按 86400 秒（1 天）展示；外部 Bearer API 调用不承诺经过相同转存和清理流程，因此不能据此保证 API 结果固定保留一天，也不保证 API 任务出现在工作台作品列表。

在线调试与相关页面

• Wan 3.0 调试台：四款模型、合法规格与平铺请求
• 视频 API 概览
• 视频计费说明
• 价格与模型