Wan 3.0 视频 API 对接文档

适用平台：https://movie.zmoapi.cn
对外模型名称：wan3.0-video
核对日期：2026-09-10

本文面向持有本平台 API Key 的开发者，按当前线上实现整理。请求异步创建视频任务，随后查询状态并保存成片。无需登录工作台，也无需接触上游账号。

1. 接入地址与鉴权

用途	方法与路径
创建视频	`POST /v1/videos`
查询任务	`GET /v1/videos/{id}`
下载成片（平台代理，可选）	`GET /v1/videos/{id}/content`

请求头：

http

Authorization: Bearer YOUR_PLATFORM_API_KEY
Content-Type: application/json

使用本平台签发的模型调用 API Key，不是站点登录密码、管理访问令牌或上游密钥。查询和下载必须使用有权访问该任务所属账号的 API Key；建议创建、查询、下载全程使用同一把 Key。

当前工作台使用“聚合视频”分组。外部 Key 也需要配置到已开通 wan3.0-video 的可用分组，并具备该模型权限、足够的账号余额及令牌额度。分组在平台令牌配置中选择，不是在 JSON 中添加 group 字段。

以下示例仅含占位符。请在自己的服务端安全注入 API_KEY，不要把实际 Key 放进浏览器前端或公开仓库。当前给定地址使用 HTTP；若运营方提供 HTTPS 地址，生产接入应使用该地址。

2. 用户上传参考素材的流程

text

用户选择图片 / 视频 / 音频
    → 上传到开发者自己的图床或对象存储
    → 获得可直接读取文件的 HTTP(S) URL
    → 将 URL 填入 metadata.input.media
    → 本平台把原始 URL 转交上游
    → 上游读取素材并生成视频

对于 Wan 的参考素材，本平台只校验 URL 形式、素材类型及数量，不下载素材，也不重新上传素材。 图片、视频、音频采用同一套 URL 入参结构。

URL 要满足：

使用 http:// 或 https://，具有有效主机名，不能包含 用户名:密码@主机 形式的凭据。
返回文件本体，不能是网盘分享页、预览页、登录页、本地路径、blob: 或 Base64 data: URL。
上游服务器可以直接访问，不依赖登录 Cookie、额外 Authorization 请求头或浏览器会话。
签名 URL 的有效期应覆盖排队、读取和生成过程；任务结束前不要删除或替换素材。参考素材保留期由你使用的图床或对象存储决定。

工作台上传接口与对外视频 API 是两件事。 /api/video-studio/wan/upload 是登录用户使用的工作台接口，使用 Cookie 鉴权；不能拿对外 API Key 直接调用它。工作台上传时单文件最大 64 MiB、每次上传一个文件。该 64 MiB 限制不能当作 /v1/videos 对外 URL 入参的文件大小校验：对外请求不会下载参考文件来检查大小、编码或时长。

当前 /v1/files 上传未实现。外部开发者应先在自己的存储服务获得 URL，不要假设可向本站上传文件后换取 file_id。BASE_URL 不包含 /v1，拼接路径时也不要重复添加 /v1。

当前已核对的是平台接受的字段和校验规则；上游对参考文件编码、大小、分辨率、时长及素材组合的完整限制尚未逐项验证。首次接入请先用少量常见格式的小文件验证，不要把“平台接受 URL”理解为“上游必定能处理该文件”。

3. 创建请求与参数

POST /v1/videos，请求体使用 JSON 对象。

3.1 顶层字段

字段	类型	说明
`model`	string	必填，使用 `wan3.0-video`
`prompt`	string	必填且不能全为空白；建议与 `metadata.input.prompt` 一致
`duration`	integer	建议显式填写，与 `metadata.parameters.duration` 一致
`metadata`	object	Wan 专用的 `input` 与 `parameters`，请直接传 JSON 对象

顶层 prompt 必须存在，不能只写 metadata.input.prompt，否则通用请求校验会先报 prompt is required。

3.2 `metadata.input`

字段	类型	说明
`prompt`	string	最终提示词，1–20000 个字符且不能全为空白；省略则沿用顶层 `prompt`
`media`	array	可选参考素材数组；纯文生视频可省略
`media[].type`	string	只能是 `reference_image`、`reference_video`、`reference_audio`
`media[].url`	string	对应文件的公开 HTTP(S) 直链

每次请求最多 10 张参考图片、5 段参考视频、5 段参考音频，按类型分别计数。这是当前平台的数量上限，不能替代上游对具体素材的校验。

3.3 `metadata.parameters`

字段	类型	默认与范围
`resolution`	string	默认 `720P`；可用 `480P`、`720P`、`1080P`
`ratio`	string	默认 `16:9`；可用 `adaptive`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`
`duration`	integer	2–30 秒；省略时先用顶层 `duration`，再用顶层 `seconds`，均未指定则为 5 秒
`audio`	boolean	可选，是否生成音频；外部 API 省略时不发送，由上游决定默认行为
`prompt_extend`	boolean	可选，是否启用提示词扩展；省略时交给上游默认
`watermark`	boolean	可选，水印开关；省略时交给上游默认
`seed`	integer	可选，0–2147483647；省略时不发送

工作台会显式发送 audio: true、prompt_extend: true、watermark: false；这不是外部 API 在省略字段时的强制默认。需要相同行为请明确传入。

参数处理顺序是先使用顶层提示词、时长和平台默认值，再用 metadata.input、metadata.parameters 覆盖。费用计算使用最终校验后的时长与分辨率。为了避免自己展示的时长与实际生成、扣费不同，顶层 duration 与 metadata.parameters.duration 保持一致，顶层 prompt 与 metadata.input.prompt 也保持一致。

不要通过 metadata.model 更改模型；不要把 Wan 的参考素材写成顶层 image_urls、video_urls、audio_urls，也不要沿用旧模型的 img_url 或 first_frame_url。本接口的 Wan 3.0 分支使用 metadata.input.media。画面比例使用 ratio，不要用其他模型的 aspect_ratio；分辨率通过 metadata.parameters.resolution 设置，不要依靠顶层 size。

4. 文生视频示例

这是适合首次验证的 2 秒、480P 请求。按当前默认分组系数，预期站内费用为 ¥0.56。

保存为 wan-request.json：

json

{
  "model": "wan3.0-video",
  "prompt": "一只橘猫坐在窗边，午后阳光洒在毛发上，镜头缓慢推进，画面稳定自然。",
  "duration": 2,
  "metadata": {
    "input": {
      "prompt": "一只橘猫坐在窗边，午后阳光洒在毛发上，镜头缓慢推进，画面稳定自然。"
    },
    "parameters": {
      "resolution": "480P",
      "ratio": "16:9",
      "duration": 2,
      "audio": true,
      "prompt_extend": true,
      "watermark": false
    }
  }
}

以下命令需要 Bash、curl 和 jq。API_KEY 应已在本地安全设置；不要把占位符原样当作可用 Key。

bash

export BASE_URL='https://movie.zmoapi.cn'
: "${API_KEY:?请先在本地安全设置 API_KEY}"

# 只提交一次。网络超时或连接中断时，不要自动重复 POST。
curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 120 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @wan-request.json \
  -o wan-create-response.json

# 上一步成功后执行，并持久保存任务 ID，后续只轮询此任务。
jq -er '.id' wan-create-response.json > wan-task-id.txt

创建成功响应示例（任务 ID 已替换）：

json

{
  "id": "task_REPLACE_WITH_RETURNED_ID",
  "task_id": "task_REPLACE_WITH_RETURNED_ID",
  "object": "video",
  "model": "wan3.0-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1789033559
}

HTTP 200 只表示任务创建成功，不能当作视频已经完成。后续统一使用返回的 id 查询；task_id 是兼容字段，不应作为必须存在的字段。

5. 图片、视频、音频参考示例

仍调用同一个 POST /v1/videos。下例展示三种素材的组合结构；请把 media.example.com 替换为真实、可直接访问的文件链接。只需要一种参考时，保留对应条目即可；多张图片则添加多个 reference_image 条目。

json

{
  "model": "wan3.0-video",
  "prompt": "使用所附图片中的人物外观，参考视频中的动作和镜头节奏，参考音频的氛围，生成连贯自然的短片。",
  "duration": 5,
  "metadata": {
    "input": {
      "prompt": "使用所附图片中的人物外观，参考视频中的动作和镜头节奏，参考音频的氛围，生成连贯自然的短片。",
      "media": [
        {
          "type": "reference_image",
          "url": "https://media.example.com/reference/person.jpg"
        },
        {
          "type": "reference_video",
          "url": "https://media.example.com/reference/movement.mp4"
        },
        {
          "type": "reference_audio",
          "url": "https://media.example.com/reference/mood.mp3"
        }
      ]
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": true,
      "prompt_extend": true,
      "watermark": false
    }
  }
}

把该 JSON 保存为新的请求文件，即可替换前例的 --data-binary @文件名 提交。此示例用于说明当前字段协议，图片、视频、音频多参考组合未在本次测试中逐项实测；参考音频不等于保证原样合成该音轨，也不代表保证口型同步。

6. 轮询状态与读取结果

bash

TASK_ID="$(cat wan-task-id.txt)"
curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

响应是视频对象本身，没有 success / data 外壳。

`status`	含义与处理
`queued`	已排队，继续查询
`in_progress`	生成中，继续查询
`completed`	完成，读取 `metadata.url` 并尽快保存
`failed`	失败，记录 `error.code`、`error.message`，停止轮询
`unknown`	状态暂不明确，保留任务 ID，稍后再查；不要立即重新生成

progress 是整数百分比，只供展示，不保证连续变化。created_at、completed_at 为 Unix 秒；当前实现中的 completed_at 来源于任务更新时间，未完成时不能仅靠它判断完成。应以 status 为准。

已成功任务的真实结构如下，任务 ID 和成片 URL 已脱敏：

json

{
  "id": "task_REPLACE_WITH_RETURNED_ID",
  "object": "video",
  "model": "wan3.0-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1789033559,
  "completed_at": 1789034154,
  "metadata": {
    "url": "https://storage.example.com/file/generated-video.mp4"
  }
}

成功响应不保证包含 seconds、size、expires_at 或费用字段；你的应用应自行保存提交参数和计价快照。成片地址读取 metadata.url，不是顶层 url、video_url 或 data.url。

下面是可续跑的轮询与保存示例。建议每 15 秒查询一次；30 分钟是本示例客户端的等待上限，不是平台承诺的完成时间，也不会取消服务端任务。

保存为 poll-wan.sh，设置好 BASE_URL、API_KEY 后运行 bash poll-wan.sh：

bash

#!/usr/bin/env bash
set -euo pipefail
: "${BASE_URL:?请设置 BASE_URL}"
: "${API_KEY:?请安全设置 API_KEY}"
TASK_ID="$(cat wan-task-id.txt)"
deadline=$((SECONDS + 1800))

while (( SECONDS < deadline )); do
  # GET 查询失败可以重试，不会重新创建生成任务。
  if ! curl --fail-with-body --silent --show-error \
      --connect-timeout 10 --max-time 60 \
      "$BASE_URL/v1/videos/$TASK_ID" \
      -H "Authorization: Bearer $API_KEY" \
      -o wan-status.json; then
    echo '查询失败，请检查 wan-status.json 和 HTTP 错误；任务 ID 已保留。' >&2
    exit 1
  fi
  status="$(jq -er '.status' wan-status.json)"
  case "$status" in
    completed)
      result_url="$(jq -er '.metadata.url | select(type == "string" and length > 0)' wan-status.json)"
      case "$result_url" in
        http://*|https://*) ;;
        *) echo '结果 URL 格式异常，请保留响应并联系平台。' >&2; exit 1 ;;
      esac
      # 下载文件直链时不发送平台 API Key。
      curl --fail --silent --show-error --location \
        --connect-timeout 10 --max-time 300 \
        "$result_url" -o wan-result.mp4
      echo '已保存 wan-result.mp4'
      exit 0
      ;;
    failed)
      jq '{id, status, error}' wan-status.json >&2
      exit 1
      ;;
    queued|in_progress|unknown)
      echo "任务状态：$status"
      ;;
    *)
      echo '收到未识别状态，请检查 wan-status.json；不要重复创建任务。' >&2
      exit 1
      ;;
  esac
  sleep 15
done

echo "本地等待结束，服务端任务可能仍在运行。保留任务 $TASK_ID，稍后重新运行此脚本。" >&2
exit 2

如果应用希望统一通过平台鉴权下载，也可以在任务完成后调用：

bash

curl --fail --silent --show-error \
  --connect-timeout 10 --max-time 120 \
  "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o wan-result.mp4

/content 返回视频二进制，不是 JSON。平台代理内部取流超时为 60 秒，较慢下载可能失败；读取 metadata.url 后直接下载通常更适合保存成片。不要把 API Key 附加到第三方成片直链或参考素材 URL 的请求头中。

7. 成片保存与有效期

参考素材和生成结果采用不同流程：输入参考素材只转发 URL；生成的成片会由平台下载并转存后再发布结果 URL。 因此“参考素材不下载重传”不代表平台永远不会下载视频。

当前 Wan 成片转存有 64 MiB 文件上限，转存时要求 3600 秒（1 小时） 保留期。该成片转存逻辑也适用于直接通过 /v1/videos 创建的任务。高分辨率、长时长生成可能产生更大的文件；上游生成成功但成片转存失败时，平台未必立即向调用方发布 completed 和可用 URL。

收到 completed 后立即把成片保存到你的持久存储。不要把 metadata.url 当作长期有效的资源，也不要等待 expires_at 字段才开始保存——当前 Wan 查询响应没有该字段。保留期从成片转存阶段计算，不是从你第一次下载时开始；轮询延迟会缩短可用下载时间。

下载限制要区分任务来源：

纯 API 创建的任务：当前不套用工作台的“最多下载 3 次”计数；成片图床的 1 小时保留期仍然适用。
工作台创建的任务：工作台记录执行 1 小时有效期和最多 3 次受计数下载。即使改用公共 /v1/videos/{id}/content 下载该工作台任务，仍会按工作台记录计数；不能把它当作规避限制的方法。

纯 API 任务记录显示 completed 不保证 URL 仍有效。若成片已经过期，再次查询任务也不会重新生成或延长保存期限。

8. 当前计费方式

Wan 3.0 实际按生成秒数计费。模型广场当前显示“按次”有误，不要照该标签按一整条视频估价。

截至核对日期，站内现价如下，默认分组系数为 1：

分辨率	单价 / 秒	2 秒示例	5 秒示例
480P	¥0.28	¥0.56	¥1.40
720P	¥0.37	¥0.74	¥1.85
1080P	¥0.42	¥0.84	¥2.10

text

站内费用 = 分辨率对应每秒单价 × 最终请求时长 × 适用分组系数

这是平台对调用账号的计价，不是上游余额或上游成本。实际分组系数、单价以调用时平台配置及消费记录为准，不应永久硬编码。本次 2 秒、480P 测试的站内扣费为 ¥0.56；成片实际容器时长约 2.02 秒，计价使用请求的 2 秒。

当前 Wan 计费实现没有额外叠加参考图片、参考视频或参考音频费用；不要套用其他模型的素材附加费规则。调用方自己的图床或对象存储费用另计。

异步任务涉及预扣与结算；服务端确认失败会进入退费处理。客户端 HTTP 超时、本地停止轮询或关闭页面不等于服务端失败，也不等于已退款。发生扣费疑问时，保存任务 ID，并以平台任务状态和消费记录核对。

9. 常见错误与接入注意事项

现象	常见原因与处理
HTTP 401 / 鉴权失败	Key 无效、失效或未正确发送 Bearer；不要使用站点账号密码替代
HTTP 403 / 无可用渠道 / 模型无权限	检查令牌分组、模型权限、账号可用分组，以及平台是否开通该模型
余额或令牌额度不足	同时检查账号余额、令牌额度与最终参数对应的预估费用
`prompt is required`	缺少顶层 `prompt`；只放在 metadata 中不能通过通用校验
HTTP 400 / `invalid_wan_request`	检查 2–30 秒、枚举值、提示词长度、seed、素材类型和数量；JSON 类型也要正确
请求成功但参数没生效	确认使用 JSON 对象形式的 `metadata.input` / `metadata.parameters`，不要放错层级；顶层 `size` 不设置 Wan 分辨率
素材链接能在自己的浏览器打开，上游仍失败	检查链接是否依赖登录、是否返回预览页面、签名是否过期、是否阻拦外部抓取，以及文件格式/编码是否可用
HTTP 200 但一直没有文件	创建成功只是排队；继续查询同一个任务，必须等待 `completed`
任务 `failed`	读取 `error`，先修正错误原因；原请求未经修改反复重试通常不能解决素材或参数问题
HTTP 429	降低频率；对查询请求按返回提示退避重试，不要循环创建新视频
POST 超时 / 断网	任务可能已经创建并扣费；当前对外接口未确认可依赖的提交幂等保证，应先核对任务与消费记录，再决定是否重提
任务不存在/无权访问（可能返回 400 或 404）	核对完整 `id`、平台地址及任务所属账号；不要使用上游内部任务 ID，结合错误体判断
下载返回 400	任务可能尚未完成；先查询状态
工作台任务下载返回 410 / 429	可能已过期或达到工作台下载次数上限；API 创建任务不套工作台计数，但成片仍可能过期
上游完成后平台仍迟迟不发布结果	可能处于成片下载、转存或重试阶段；保留任务 ID 联系平台核对，不要立即重复生成
`completed` 但文件下载失败	检查是否超过 1 小时、图床临时故障或文件转存问题；完成状态本身不是永久可下载保证

提交错误可能来自不同层，错误 JSON 不应只按一种结构写死。建议保存 HTTP 状态码、响应中的错误代码/消息、任务 ID（如已有）以及返回的请求标识；日志中遮盖 Key 和带签名的素材 URL。

不要默认通用视频 SDK 会保留 Wan 专用 metadata。如果 SDK 丢弃这些字段，应使用能完整发送本文 JSON 的 HTTP 客户端。

10. 本次验证范围

已通过视频工作台提交纯文字 wan3.0-video 任务；工作台内部调用同一条 /v1/videos 创建通路。
实测参数为 2 秒、480P，成功生成并下载成片，实际时长约 2.02 秒、画面 854×480；耗时约 10 分钟，站内扣费 ¥0.56。
已使用 API 令牌对既有成功任务执行 GET /v1/videos/{id}，确认本文的公开查询响应结构与 metadata.url。
尚未通过外部客户端新建一条独立付费任务；参考图片、参考视频、参考音频及其混合组合也未逐项生成实测。上文相关部分依据当前线上适配与校验实现说明。

10 分钟是本次样本耗时，不是完成时间保证。后续模型、价格、分组或上游规则发生变更时，应由平台更新本独立文档。

Wan 3.0 视频 API 对接文档 ​

1. 接入地址与鉴权 ​

2. 用户上传参考素材的流程 ​

3. 创建请求与参数 ​

3.1 顶层字段 ​

3.2 metadata.input ​

3.3 metadata.parameters ​

4. 文生视频示例 ​

5. 图片、视频、音频参考示例 ​

6. 轮询状态与读取结果 ​

7. 成片保存与有效期 ​

8. 当前计费方式 ​

9. 常见错误与接入注意事项 ​

10. 本次验证范围 ​

Wan 3.0 视频 API 对接文档

1. 接入地址与鉴权

2. 用户上传参考素材的流程

3. 创建请求与参数

3.1 顶层字段

3.2 `metadata.input`

3.3 `metadata.parameters`

4. 文生视频示例

5. 图片、视频、音频参考示例

6. 轮询状态与读取结果

7. 成片保存与有效期

8. 当前计费方式

9. 常见错误与接入注意事项

10. 本次验证范围