阿里 Wan 3.0 视频 API 入门:下一代视频生成快速上手
目标型号:
wan3.0-video(可选姊妹 ID:wan3.0-video-prime)
推理接口:https://api.toapis.com/v1/videos/generations
相关阅读:Wan 3.0 Prime 与 Wan 2.6 Flash 对比 · Kling Video O1 长视频连续性 · Wan 3.0 参考 · wan3.0-video 型号指南 · wan3.0-video-prime 型号指南
1. TL;DR 与能力概览
- 先核对目录:规划稿有时写成
wan-3-prime。该字符串不是已文档化的公共 ID。2026-11-20 核对官方 Wan 3.0 生成参考(HTTP 200),列出wan3.0-video和wan3.0-video-prime。两个型号使用该页同一套 All-in-One API。当时不存在单独的 Prime 专用文档路径。 - 调用约定:异步提交到
POST /v1/videos/generations,再轮询GET /v1/videos/generations/{id}直至completed或failed。普通任务也可以用GET /v1/tasks/{id}查询。官方示例使用https://toapis.com(中国大陆为https://toapis.cn)。本系列其他指南使用https://api.toapis.com。选定一个源站并保持一致。 - 同一结构上的多种方式:文生视频;首帧或首尾帧控制;参考图片、视频和音频的联合生成;单个文件或公开网页;以及基于参考片段的视频编辑或延长。首尾帧模式与参考素材模式互斥。
- 素材:只发送公开的
http://或https://URL。本地文件请先上传并使用返回的 URL。不要发送 base64 或本地路径。prompt与媒体素材至少提供一项。 - 应丢弃的未核实说法:诸如每 5 秒
$0.150的规划稿单价,不是当前 ToAPIs 文档。请在账户中确认实时价格与渠道支持。
2. 官方 Wan 3.0 ID、参数与组合规则
在 model 字段中使用两个公共型号名之一。不要替换成规划稿别名,也不要发明 Prime 模式开关。
| 目录 ID | 在本文中的角色 | 已文档化的能力 |
|---|---|---|
wan3.0-video | 默认 / 标准全能 ID | 文生视频、首尾帧、多模态参考、文件或链接、编辑与延长 |
wan3.0-video-prime | 同一结构上的 Prime 姊妹 ID | 与 wan3.0-video 相同的请求结构;仅在目录中列出且你确实要使用 Prime SKU 时选择它 |
wan2.6 | 相关的早期 Wan ID;见 Wan 2.6 生成参考 | 文生视频、图生视频和参考视频,参数映射不同(无 480p;时长为 5/10/15) |
核心请求字段(两个 Wan 3.0 ID 共用):
| 字段 | 文档化取值 | 说明 |
|---|---|---|
prompt | 字符串 | 内容、动作、镜头和声音。prompt 与媒体素材至少提供一项。按数组顺序用“图片1”“视频1”“音频1”引用素材 |
duration | 2–30 的整数,或 -1 | 默认 5。-1 为智能时长——由模型决定长度 |
ratio | adaptive(默认)、16:9、9:16、1:1、4:3、3:4 | aspect_ratio 是兼容别名;不要同时传入 |
resolution | 480p、720p、1080p(默认 1080p) | 本该合同文档化了全部三档 |
audio | 布尔,默认 true | 默认开启音频 |
watermark | 布尔,默认 false | 默认关闭 |
prompt_extend | 布尔,默认 true | 大模型改写可改善短提示词,同时增加耗时;设为 false 则原样使用提示词 |
seed | 可选整数 | 相同参数加种子有助于复现相近结果 |
image_with_roles | {url, role} 数组 | role 为 first_frame 或 last_frame。各最多一个;last_frame 必须同时有 first_frame |
reference_images | 最多 10 个公开图片 URL | 不能与首尾帧混用 |
video_list | 最多 5 段,总时长 ≤15 秒 | 每项为 {"video_url": "..."} |
audio_with_roles | 最多 5 段,总时长 ≤15 秒 | 每项为 {url, role: "reference_audio"} |
metadata.media | 一个 file 或一个 link | {type, url}。文件与链接不能同时使用,也不能与首尾帧模式混用 |
disable_nsfw | 布尔,默认 true | ToAPIs 平台参数,不会转发给上游。只有显式的 JSON false 才会在账号和销售区域符合条件时启用备用渠道;中国大陆始终禁用 |
官方表格中的素材组合规则:
| 请求内容 | 是否支持 | 说明 |
|---|---|---|
| 仅提示词 | 是 | 文生视频 |
| 仅首帧 | 是 | 首帧控制 |
| 首帧和尾帧 | 是 | 尾帧不能单独使用 |
| 参考图片和参考视频 | 是 | 可联合参考,也可再加参考音频 |
| 首帧和参考视频 | 否 | 首尾帧模式与参考素材模式互斥 |
| 文件和网页链接 | 否 | 两者互斥 |
如果接口返回类似“Wan 3.0 不能在同一请求中混用首尾帧与参考素材/文件/网页”的信息,请删除其中一类后再提交。
视频编辑是按提示词分类的路径,不是单独的端点:在提示词中包含编辑意图(例如“edit the video”、“remove”、“replace”),并传入参考片段。这类任务要求 ratio 为 adaptive、duration 为 -1,且输入为 4–30 秒。延长使用“extend”或“continue”等用词,将 duration 设为 -1 或源时长加延长部分(总计 ≤ 30 秒)。

图 1:已文档化的 Wan 3.0 载荷提交到 POST /v1/videos/generations;轮询同一任务 ID,仅在 status 为 completed 后读取 result.data[0].url。
若要与 Wan 2.6 Flash 对比能力和成本,见 Wan 3.0 Prime 与 Wan 2.6 Flash。若要在另一产品族上用 3–10 秒窗口做长视频连续性,见 Kling Video O1 指南。
3. 生产实现:cURL 与 Python
本系列的国际示例使用 https://api.toapis.com。官方文档要求中国大陆用户使用 https://toapis.cn。每个环境只保留一个源站。
步骤 1:用 cURL 提交文生视频
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
"duration": 5,
"ratio": "16:9",
"resolution": "1080p",
"audio": true,
"watermark": false
}'
首尾帧请求使用 image_with_roles,且不得包含参考素材、文件或链接:
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
"duration": 8,
"ratio": "adaptive",
"resolution": "1080p",
"image_with_roles": [
{"url": "https://example.com/first-frame.png", "role": "first_frame"},
{"url": "https://example.com/last-frame.png", "role": "last_frame"}
]
}'
步骤 2:Python 助手与轮询器
下面的片段遵循已文档化的任务状态路径,以及 queued / in_progress / completed / failed 状态。上线前请对照你账户对应的 API 参考确认 id、result.data[0].url 和响应包络。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_IDS = {"wan3.0-video", "wan3.0-video-prime"}
RATIOS = {"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4"}
RESOLUTIONS = {"480p", "720p", "1080p"}
def dispatch_wan30(
prompt: str | None = None,
*,
model: str = "wan3.0-video",
duration: int = 5,
ratio: str = "16:9",
resolution: str = "1080p",
audio: bool = True,
watermark: bool = False,
prompt_extend: bool | None = None,
image_with_roles: list[dict] | None = None,
reference_images: list[str] | None = None,
video_list: list[dict] | None = None,
audio_with_roles: list[dict] | None = None,
media: list[dict] | None = None,
) -> str:
if model not in DOCUMENTED_IDS:
raise ValueError("Send wan3.0-video or wan3.0-video-prime; wan-3-prime is not a documented public ID")
if duration != -1 and duration not in range(2, 31):
raise ValueError("duration must be 2–30 or -1")
if ratio not in RATIOS:
raise ValueError("unsupported ratio")
if resolution not in RESOLUTIONS:
raise ValueError("resolution must be 480p, 720p, or 1080p")
roles = [item.get("role") for item in (image_with_roles or [])]
if "last_frame" in roles and "first_frame" not in roles:
raise ValueError("last_frame requires first_frame")
has_frames = bool(image_with_roles)
has_refs = any([reference_images, video_list, audio_with_roles, media])
if has_frames and has_refs:
raise ValueError("first/last-frame mode cannot mix with reference assets, files, or links")
if media and len(media) > 1:
raise ValueError("a single request accepts at most one file or one web page")
if media and len({item.get("type") for item in media}) > 1:
raise ValueError("file and link cannot be used together")
if not prompt and not has_frames and not has_refs:
raise ValueError("provide a prompt or at least one media asset")
if reference_images and len(reference_images) > 10:
raise ValueError("reference_images is documented as at most 10")
if video_list and len(video_list) > 5:
raise ValueError("video_list is documented as at most 5 clips")
if audio_with_roles and len(audio_with_roles) > 5:
raise ValueError("audio_with_roles is documented as at most 5 clips")
payload: dict = {
"model": model,
"duration": duration,
"ratio": ratio,
"resolution": resolution,
"audio": audio,
"watermark": watermark,
}
if prompt:
payload["prompt"] = prompt
if prompt_extend is not None:
payload["prompt_extend"] = prompt_extend
if image_with_roles:
payload["image_with_roles"] = image_with_roles
if reference_images:
payload["reference_images"] = reference_images
if video_list:
payload["video_list"] = video_list
if audio_with_roles:
payload["audio_with_roles"] = audio_with_roles
if media:
payload["metadata"] = {"media": media}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 900) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_wan30(
"An orange cat running through the streets of Tokyo after rain, cinematic camera work",
duration=5,
ratio="16:9",
resolution="1080p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
把提示词模板版本和任务记录放在一起,以便区分参数改动和措辞改动。在 expires_at 之前下载文件;状态参考写明保留窗口为 30 天。若开启 prompt_extend(默认如此),短提示词会额外增加耗时——官方页面只做了定性说明,并未公布实测延迟。
4. 错误处理与状态矩阵
下表是诊断起点,并不保证与 ToAPIs 错误码完全一一对应。HTTP 查询成功后仍需读取任务 status。请求错误与 status: failed 的原因(例如 content_policy_rejected、insufficient_user_balance、generation_timeout 或 video_edit_parameters_required)见 错误码参考。
| HTTP 或任务状态 | 常见类别 | 建议操作 |
|---|---|---|
400 | 字段无效、首尾帧与参考素材混用、同时传了 ratio 和 aspect_ratio,或文件与链接并存 | 确认 wan3.0-video 或 wan3.0-video-prime,去掉互斥的一类,并只使用公开 URL |
401 | 缺少或无效的 API Key | 在 ToAPIs 控制台轮换密钥,并确认 Authorization: Bearer 请求头 |
429 | 速率或并发限制 | 如有 Retry-After 请遵守;加抖动退避;仅在安全时重试 |
5xx 或客户端超时 | 网关或上游暂时问题 | 先查询已有任务 ID 再决定是否重提 |
status: queued 或 in_progress | 不是错误 | 等待并再次轮询;prompt_extend 可能增加耗时 |
status: failed 且原因为 video_edit_parameters_required | 未满足编辑约束 | 将 ratio 设为 adaptive、duration 设为 -1,并使用 4–30 秒的源视频 |
status: failed(其他) | 生成未成功 | 读取 error.code 与 error.message(若有 error.reason 也一并查看)。不要原样重试被策略拒绝的载荷 |
5. 定价与 FinOps
Wan 3.0 生成参考并未公布美元或积分价表。2026-11-20 获取的型号指南页面显示,wan3.0-video 的定价参考为 26.3 credits / 秒,wan3.0-video-prime 为 41.14 credits / 秒,并且都写明最终计费以当前账户报价以及当前时长和分辨率规则为准。请把这些积分数字视为快照,而不是对每种分辨率或模式的合同价。不要自行把积分换算成货币,也不要沿用规划稿中的美元单价。
- 先从中等时长的
wan3.0-video起步(例如 5 秒),等提示词和素材组合稳定后再提高分辨率或切换到 Prime。 - 智能时长(
-1)和prompt_extend会改变模型实际完成的工作量。 它们是已文档化的能力,不能据此假设固定的单次价格或时延。 - 展示价格不是渠道保证。 在预估批量成本之前,用
GET /v1/models?type=video和账户目录确认 ID 与实时报价。
6. 常见问题
详见 frontmatter 中的 FAQ。摘要:发送 wan3.0-video 或 wan3.0-video-prime,不要发送 wan-3-prime;首尾帧不能与参考素材混用;时长为 2–30 秒或 -1;编辑需要 ratio=adaptive 且 duration=-1;务必轮询 generations 状态路径并持久化任务 ID。
7. 行动清单
- 在 ToAPIs 开发者门户 创建密钥。
- 通过
GET /v1/models?type=video确认当前密钥能看到wan3.0-video(若需要,也包括wan3.0-video-prime)——不要发送wan-3-prime。 - 用
duration: 5、ratio: "16:9"和resolution: "1080p"对 cURL 示例做冒烟测试。 - 以有界超时轮询
GET /v1/videos/generations/{id},并在expires_at之前下载结果。 - 下一步:参阅 Wan 3.0 Prime 与 Wan 2.6 Flash 对比 了解已文档化的能力与成本比较,并查看 wan3.0-video 型号指南 了解实时目录状态。







