Wan 3.0 标志Wan 3.0

开发者

Wan 3.0 API

在你自己的程序里生成视频，模型、积分和限制都与 Wan 3.0 创作工作台一致。

创建 API 密钥快速开始

接口地址https://wan3.video/api/v1

本页目录

概览

Wan 3.0 API 用与创作工作台相同的模型、积分和限制生成视频。每个请求都以你的账户身份执行：消耗你的积分，遵循你的会员权益，生成的视频也会出现在你的历史记录里。

API 采用基于 HTTPS 的 REST 风格，请求体和响应都是 JSON。下文所有路径都相对于 https://wan3.video/api/v1。视频是异步生成的：先创建视频，再轮询直到 status 变为 completed 或 failed，然后下载。生成通常需要几分钟。通过 API 创建的视频不会发送完成通知邮件。

请从你自己的服务器调用 API。浏览器无法直接调用；写进网页或 App 代码里的 API 密钥可能被别人复制，进而消耗你的积分。

身份验证

登录后在 API 密钥页面 创建密钥。完整密钥只显示一次，请保存在密钥管理服务或环境变量里。每个账户最多有 10 个有效密钥；一旦怀疑泄露，请立即在该页面撤销。

每个请求都以 Bearer 令牌的形式携带密钥。缺少密钥、密钥无效或已撤销时返回 401 UNAUTHORIZED。

Shell
curl https://wan3.video/api/v1/account \
  -H "Authorization: Bearer $WAN3_API_KEY"

快速开始

1. 用一段提示词创建一个 5 秒的 720P 视频。响应是新的视频对象，其 status 为 processing。

Shell
curl https://wan3.video/api/v1/videos \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "w3.0-video",
    "prompt": "A paper boat drifting down a rain-soaked street at dusk, cinematic lighting",
    "resolution": "720P",
    "duration": 5,
    "aspectRatio": "16:9"
  }'

2. 每 10–15 秒轮询一次，直到视频完成或失败。

Shell
curl https://wan3.video/api/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $WAN3_API_KEY"

3. 下载 MP4。下载地址可能会重定向到我们的文件存储，请跟随重定向。

Shell
curl -L -o video.mp4 https://wan3.video/api/v1/videos/VIDEO_ID/content \
  -H "Authorization: Bearer $WAN3_API_KEY"

用 Python 实现同样的流程：

Python
import os
import time
import uuid

import requests

API = "https://wan3.video/api/v1"
KEY = os.environ["WAN3_API_KEY"]


def api(method, path, headers=None, **kwargs):
    response = requests.request(
        method,
        f"{API}{path}",
        headers={"Authorization": f"Bearer {KEY}", **(headers or {})},
        timeout=60,
        **kwargs,
    )
    body = response.json()
    if body["error"]:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body["data"]


video = api(
    "POST",
    "/videos",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "w3.0-video",
        "prompt": "A paper boat drifting down a rain-soaked street at dusk",
        "resolution": "720P",
        "duration": 5,
    },
)

while video["status"] == "processing":
    time.sleep(10)
    video = api("GET", f"/videos/{video['id']}")

if video["status"] == "failed":
    raise RuntimeError(video["error"]["message"])

download = requests.get(
    video["videoUrl"], headers={"Authorization": f"Bearer {KEY}"}, timeout=300
)
download.raise_for_status()
with open(f"{video['id']}.mp4", "wb") as file:
    file.write(download.content)

响应与错误

所有 JSON 响应都使用同一种结构。成功时为 { "data": …, "error": null }；失败时为 { "data": null, "error": { "code", "message" } }。请根据稳定不变的 error.code 做判断；message 供人阅读，措辞可能调整。部分错误会附带额外字段，例如视频所需的积分。

每个响应还带有 X-Request-Id 响应头。就某个请求联系客服时，请提供这个值。

错误响应
HTTP/1.1 402 Payment Required
X-Request-Id: 3f1c9a52-6a0e-4c55-9d7e-0f6f1d2b8c41

{
  "data": null,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this generation",
    "requiredCredits": 10,
    "availableCredits": 3.5
  }
}
状态码含义
200, 201请求成功；201 表示已创建资源。
400参数缺失或无效，错误信息会指出具体参数。
401API 密钥缺失、无效或已撤销。
402账户积分不足。
403账户无权执行此操作，例如没有会员。
404视频不存在，或属于其他账户。
409视频当前的状态不允许此操作。
422请求被拒绝，例如未通过内容安全审核。
429同时生成的视频过多，或内容安全审核次数过多。
451该服务在你所在的地区不可用。
5xx临时故障，请稍后重试；失败的视频会自动退还积分。

幂等请求

网络出错时，你可能无法确定视频是否已创建。调用 POST /videos 时带上 Idempotency-Key 请求头（例如一个 UUID），然后用同一个键重试：重试会返回第一次请求创建的视频，状态码为 200 并带有 Idempotent-Replayed: true 响应头，而不会再创建一个视频并重复扣费。

键可以是 1–255 个不含空格的可打印 ASCII 字符，只在你的账户内有效。每个新视频都请使用新键：用同一个键提交不同参数会返回 422 IDEMPOTENCY_KEY_MISMATCH。如果第一次请求在视频创建之前就被拒绝（例如积分不足），用同一个键重试会重新执行。

查询账户

GET/account

返回账户的积分余额、会员状态，以及当前正在生成的视频数量和并发上限。

响应
{
  "data": {
    "credits": 128.5,
    "membership": {
      "active": true,
      "plan": "pro",
      "expiresAt": "2026-11-06T08:00:00.000Z"
    },
    "activeGenerations": 2,
    "maxActiveGenerations": 20
  },
  "error": null
}

创建上传

POST/uploads

图生视频和视频编辑需要先上传文件。上传分三步：先在这里创建上传，再把文件 PUT 到返回的 uploadUrl，最后完成上传。创建视频时传入上传得到的 key。上传的文件属于你的账户，7 天后自动删除。

请求体参数
filenamestring · 必填文件名，1–255 个字符，只用于给存储的文件命名。
contentTypestring · 必填image/jpeg、image/png、image/webp、image/bmp、video/mp4 或 video/quicktime。
bytesinteger · 必填文件大小，单位为字节。
modelstring文件要用于哪个模型。传 doubao-seedance-2.5 时按 Seedance 2.5 的媒体规则校验；传其他值或不传时按 W3.0 的规则校验。
Shell
curl https://wan3.video/api/v1/uploads \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576
  }'
响应 · 201 Created
{
  "data": {
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "uploadUrl": "https://…r2.cloudflarestorage.com/…",
    "uploadMethod": "PUT",
    "uploadHeaders": { "Content-Type": "image/png" },
    "uploadExpiresAt": "2026-10-06T08:15:00.000Z",
    "expiresAt": "2026-10-13T08:00:00.000Z"
  },
  "error": null
}

然后在 15 分钟内，按返回的方法和请求头把文件内容发送到 uploadUrl。不要把 API 密钥发给这个地址。

Shell
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --upload-file first-frame.png

完成上传

POST/uploads/complete

按模型的媒体要求校验已上传的文件，视频文件还会返回时长。创建视频时会再次校验文件，所以这一步可以省略，但它能在创建视频之前发现有问题的文件。文件不会被缩放或转码，请上传已经符合要求的媒体。

请求体参数
keystring · 必填创建上传时返回的 key。
contentTypestring · 必填创建上传时使用的文件类型。
bytesinteger · 必填创建上传时声明的文件大小。
modelstring文件要用于哪个模型。传 doubao-seedance-2.5 时按 Seedance 2.5 的媒体规则校验；传其他值或不传时按 W3.0 的规则校验。
Shell
curl https://wan3.video/api/v1/uploads/complete \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576
  }'
响应
{
  "data": {
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576,
    "expiresAt": "2026-10-13T08:00:00.000Z"
  },
  "error": null
}

视频文件还会返回 durationSeconds。文件不存在、与声明的类型或大小不符，或不符合媒体规则时，返回 400 UPLOAD_INVALID 并说明原因。

创建视频

POST/videos

开始生成视频并扣除积分。生成失败时积分会自动退还。提示词会先经过内容安全审核；被拒绝的提示词不扣积分。

请求体参数
promptstring · 必填视频要呈现的内容，最多 20,000 个字符。
modelstring默认为 w3.0-video。参见模型与积分。
modestringtext-to-video、image-to-video 或 video-edit。不传时：带 videoKey 为 video-edit，带 images 为 image-to-video，否则为 text-to-video。
resolutionstring需为模型支持的分辨率。默认 720P，Pro 模型默认 1080P。高于 720P 需要有效会员。
durationinteger输出时长（秒），默认 5。W3.0 模型支持 2–30 秒，Seedance 2.5 支持 4–30 秒。W3.0 视频编辑的输出与原视频合计不超过 30 秒。Seedance 2.5 视频编辑的时长与原视频相同，请不要传 duration。
aspectRatiostring16:9, 9:16, 1:1, 4:3, 3:4；默认 16:9。W3.0 视频编辑如不指定，则保持原视频比例。Seedance 2.5 的首帧视频和视频编辑由模型自行决定比例。
seedinteger0–2147483647。相同输入配合相同种子会得到相近的结果。不传则随机。
imagesarray已上传的图片，格式为 { "key", "role" }。图生视频需要 1–10 张图片，每张都要指定角色：一张 first_frame 图片作为视频首帧，或最多 10 张 reference_image 图片作为主体和风格参考；两种角色不能混用。视频编辑最多可传 10 张参考图，角色可以省略。
videoKeystring视频编辑所用的已上传原视频。
图生视频
curl https://wan3.video/api/v1/videos \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b0f6f5e-0c55-4a2b-9a7d-3f1e2d4c5b6a" \
  -d '{
    "model": "w3.0-video",
    "prompt": "The camera slowly pushes in as she turns toward the window",
    "images": [
      { "key": "temp/5f0c…/first-frame.png", "role": "first_frame" }
    ],
    "duration": 5
  }'
视频编辑请求体
{
  "model": "w3.0-video",
  "prompt": "Turn the street into a snowy winter night",
  "videoKey": "temp/5f0c…/source.mp4",
  "images": [{ "key": "temp/5f0c…/style.jpg" }],
  "duration": 5
}

返回 201 和新的视频对象，其 status 为 processing。常见的拒绝有 402 INSUFFICIENT_CREDITS、403 MEMBERSHIP_REQUIRED、422 NSFW_PROMPT 和 429 ACTIVE_GENERATION_LIMIT；参见错误码。

视频对象

字段
idstring视频 ID。
statusstringprocessing、completed 或 failed。
model, mode, promptstring请求时提交的内容。
resolutionstring输出分辨率。
durationinteger输出时长（秒）。
aspectRatiostring输出比例；跟随首帧时为 adaptive，视频编辑保持原视频比例时为 source。
seedinteger | null实际使用的种子。
creditCostnumber | null扣除的积分。失败视频的积分会退还。
videoUrlstring | null完成后为下载地址，访问时需要带上 API 密钥；否则为 null。
errorobject | null视频失败时为 { "code", "message" }，code 为 GENERATION_FAILED、GENERATION_TIMED_OUT 或 PROVIDER_REQUEST_REJECTED。
createdAt, updatedAtstringISO 8601 格式的时间。
示例
{
  "data": {
    "id": "video_1759737600000_4f2a9c1e",
    "status": "completed",
    "model": "w3.0-video",
    "mode": "image-to-video",
    "prompt": "The camera slowly pushes in as she turns toward the window",
    "resolution": "720P",
    "duration": 5,
    "aspectRatio": "16:9",
    "seed": 1844673015,
    "creditCost": 5,
    "videoUrl": "https://wan3.video/api/v1/videos/video_1759737600000_4f2a9c1e/content",
    "error": null,
    "createdAt": "2026-10-06T08:00:00.000Z",
    "updatedAt": "2026-10-06T08:02:41.000Z"
  },
  "error": null
}

查询视频

GET/videos/{id}

返回视频对象。对仍在生成的视频，还会向服务商查询最新进度。轮询间隔请不要短于 5 秒。

视频列表

GET/videos

返回你的视频，按时间从新到旧排列。

查询参数
limitinteger每页 1–100 个视频，默认 20。
statusstring只返回 processing、completed 或 failed 状态的视频。
cursorstring上一页返回的 nextCursor，用于获取下一页。
Shell
curl "https://wan3.video/api/v1/videos?limit=20&status=completed" \
  -H "Authorization: Bearer $WAN3_API_KEY"
响应
{
  "data": {
    "videos": [ { "id": "video_…", "status": "completed", … } ],
    "nextCursor": "video_1759737600000_4f2a9c1e"
  },
  "error": null
}

最后一页的 nextCursor 为 null。

下载视频

GET/videos/{id}/content

以 MP4 文件返回已完成的视频。已归档的视频会返回 307 重定向到我们的文件存储，请跟随重定向；文件地址本身不需要密钥。支持 Range 请求。尚未完成的视频返回 409 VIDEO_NOT_READY。

删除视频

DELETE/videos/{id}

永久删除已完成的视频及其存储的文件。生成中或已失败的视频不能删除，会返回 409 VIDEO_NOT_DELETABLE。

响应
{
  "data": { "id": "video_1759737600000_4f2a9c1e", "deleted": true },
  "error": null
}

模型与积分

视频消耗的积分与时长和分辨率成正比。下表列出 5 秒视频所需的积分；10 秒视频的积分是它的两倍。可在价格页购买积分或会员。

模型说明5 秒视频所需积分会员
w3.0-videoW3.0480P: 2.5 · 720P: 5 · 1080P: 101080P 需要
w3.0-video-primeW3.0，更快生成480P: 3.5 · 720P: 7 · 1080P: 141080P 需要
w3.0-video-proW3.0 Pro，超分辨率1080P: 10 · 2K: 10 · 4K: 12.5需要
w3.0-video-prime-proW3.0 Pro，更快生成1080P: 14 · 2K: 14 · 4K: 17.5需要
doubao-seedance-2.5Seedance 2.5480P: 6.47 · 720P: 14.55 · 1080P: 25.921080P 需要

W3.0 视频编辑按请求的输出时长计费，与生成同样时长的新视频相同。Seedance 2.5 视频编辑按原视频时长计费两次（输入和输出各一次），单价更低：以 720P 编辑一段 10 秒的原视频需要 38.78 积分。每个视频的 creditCost 就是实际扣除的积分。

媒体要求

上传的文件会按目标模型的规则校验。文件不会被缩放或转码，请在上传前处理好。

W3.0 模型Seedance 2.5
图片格式JPEG、PNG（不能有透明通道）、WebP、BMPJPEG、PNG、WebP、BMP
图片大小不超过 20 MB小于 30 MB
图片边长240–8,000 像素300–6,000 像素
视频格式MP4、MOVMP4、MOV
视频大小不超过 100 MB小于 200 MB
视频时长1–15 秒4–30 秒
视频边长240–4,096 像素300–6,000 像素，总像素 409,600–8,295,044
帧率至少 16 FPS24–60 FPS
宽高比较长边与较短边之比不超过 8:1宽 ÷ 高在 0.4 到 2.5 之间

限制与存储

  • 每个账户最多同时生成 20 个视频。超出时返回 429 ACTIVE_GENERATION_LIMIT，等有视频完成后再提交。
  • 需要完整内容安全审核的提示词，每个账户每分钟最多 30 次、每小时最多 200 次。超出后创建视频会返回 429 PROMPT_MODERATION_RATE_LIMITED。
  • 超过 3 小时仍未生成完的视频会以 GENERATION_TIMED_OUT 失败。失败的视频一律退还积分。
  • 上传地址 15 分钟后失效，已上传的文件 7 天后删除。
  • 账户持有会员期间、或购买过积分之后生成的视频会被永久保存。其他视频保存在视频服务商处，可能会过期，请在完成后尽快下载。
  • 提示词最多 20,000 个字符，每个视频最多 10 张图片。

错误码

错误码状态码含义
INVALID_JSON400请求体不是 JSON 对象。
INVALID_REQUEST400参数缺失或无效，错误信息会指出具体参数。
INVALID_CURSOR400cursor 不是上一页返回的 nextCursor。
UPLOAD_INVALID400上传的文件不存在、与声明的不符，或不符合媒体规则。
UNAUTHORIZED401API 密钥缺失、无效或已撤销。
INSUFFICIENT_CREDITS402积分不足；requiredCredits 和 availableCredits 给出具体数量。
ACCOUNT_BANNED403账户已被封禁。
MEMBERSHIP_REQUIRED403Pro 模型和高于 720P 的分辨率需要有效会员。
VIDEO_NOT_FOUND404该账户下不存在这个 ID 的视频。
IDEMPOTENCY_KEY_REUSED409这个键对应的视频已被删除，请使用新的 Idempotency-Key。
VIDEO_NOT_READY409视频尚未完成。
VIDEO_NOT_DELETABLE409只能删除已完成的视频。
IDEMPOTENCY_KEY_MISMATCH422这个 Idempotency-Key 已用于不同的参数。
NSFW_PROMPT422提示词未通过内容安全审核，未扣积分。
PROVIDER_REQUEST_REJECTED422服务商在过去一天内拒绝过相同的提示词和媒体，请先修改。
ACTIVE_GENERATION_LIMIT429同时生成的视频过多；activeLimit 给出上限。
PROMPT_MODERATION_RATE_LIMITED429内容安全审核次数过多，请稍等一分钟。
REGION_UNAVAILABLE451该服务在你所在的地区不可用。
INTERNAL_ERROR500意外错误；联系客服时请提供 X-Request-Id。
PROVIDER_ERROR502视频服务商出错，请稍后重试。
VIDEO_UNAVAILABLE502暂时无法获取视频文件，请稍后重试。
SERVICE_UNAVAILABLE503某项服务暂时不可用，请稍后重试。
PROMPT_MODERATION_UNAVAILABLE503内容安全审核暂时不可用，请稍后重试。