Wan 视频生成（阿里云通义万相）

阿里云通义万相 Wan2.7 视频生成系列完整指南：文生视频 / 图生视频（含音频驱动）/ 参考图生视频 / 视频编辑，统一 DashScope 异步端点，支持 720P / 1080P 与 2–15 秒时长。

​

概述

Wan（通义万相） 是阿里云推出的视频生成模型系列。API易 通过 DashScope 透传通道 直连阿里云百炼，让你用一个 sk- 开头的 API易 Key 即可调用全部 Wan 视频能力，无需单独注册阿里云账号。当前主力版本为 Wan2.7，覆盖四种核心玩法：

玩法	模型 ID	你给的输入	产出
文生视频	wan2.7-t2v	一段文本 prompt	5–15 秒短视频
图生视频	wan2.7-i2v	首帧图 + prompt（可选驱动音频）	让静态图”动起来”，配音频可做对口型 / rap
参考图生视频	wan2.7-r2v	1–5 个参考图/视频 + prompt	保持参考主体特征的单/多角色视频，支持音色参考
视频编辑	wan2.7-videoedit	一段视频 + 1–5 张参考图 + 编辑指令	换装、换背景等编辑后的视频

🎬 核心亮点：四种能力共用同一个异步端点和同一套请求结构，切换玩法只改 model 字段。原生支持 720P / 1080P 分辨率与 2–15 秒整数时长，wan2.7-i2v 还支持驱动音频做对口型。适合短视频生产、电商素材、数字人口播、创意运营等场景。

文生视频 API

wan2.7-t2v，纯文本提示词生成视频，最简单的入口。

图生视频 API

wan2.7-i2v，首帧图 + 可选驱动音频，做对口型 / rap。

参考图生视频 API

wan2.7-r2v，参考图/视频保持主体特征，支持音色参考。

视频编辑 API

wan2.7-videoedit，视频 + 参考图做换装、换背景等编辑。

可视化接口测试

在 iCover 可视化测试工具里直接调试本接口，无需写代码。

异步任务查询 / 下载

在 API易后台查看已提交的视频任务、下载视频链接（API 之外的查询入口）。

​

为什么选 API易 的 Wan

一个 Key 调全部能力

无需注册阿里云、无需配置地域和环境变量。一把 API易 Key 即可调用 Wan2.7 全部四种能力以及 HappyHorse 系列。

国内直连 · 免出海

直连 api.apiyi.com，国内机房、家宽网络均可访问，省去为阿里云配置地域 Endpoint 的麻烦。

失败不计费

任务进入 failed 状态（媒体 URL 不可达、prompt 涉敏、上游容量等）不计费，可放心重试。

DashScope 协议透传

请求体与阿里云 DashScope 原生协议一一对齐，对照官方文档即可迁移，响应已统一收口便于轮询。

​

核心特性

四合一异步端点

t2v / i2v / r2v / video-edit 共用 POST /wan/api/v1/...video-synthesis，提交后返回 task_id，轮询 + 下载，便于批量管理。

音频驱动对口型

wan2.7-i2v 支持 driving_audio，让静态人像跟随音频做口型与节奏，适合 rap / 口播 / 数字人。

多主体参考

wan2.7-r2v 支持参考图 + 参考视频混合输入（合计 ≤5），用「图1 / 视频1」标识在 prompt 里指代，支持音色参考。

多档分辨率与时长

720P / 1080P 分辨率，2–15 秒整数时长，prompt_extend 智能改写进一步提升短 prompt 的画质。

​

支持的模型

模型 ID	能力	必需媒体输入	说明
wan2.7-t2v	文生视频	无	纯文本生成
wan2.7-i2v	图生视频	first_frame（+ 可选 driving_audio）	唯一支持音频驱动的能力
wan2.7-r2v	参考图生视频	reference_image / reference_video（合计 ≤5）	支持 reference_voice 音色参考
wan2.7-videoedit	视频编辑	video + reference_image（1–5 张）	编辑模型名 无连字符

wan2.7-videoedit 是图像编辑视频用途；另有 wan2.7-image-pro 属于 图片 模型（走 /v1/images/generations），不在本视频端点范围内，请勿混用。历史版本 Wan2.6 见 历史版本。

​

分组介绍

Wan 与 HappyHorse 两个系列共用同一个 Wan&HappyHorse 分组——一把令牌即可同时调用两个系列。视频模型按秒计费，令牌必须同时满足两个条件才能成功路由：

1. 计费模式：选「按量优先」或「按量计费」—— 视频按秒计费，按次计费的令牌无法路由
2. 分组：选择包含 Wan&HappyHorse

创建令牌：计费模式选「按量优先」，分组选 Wan&HappyHorse（0.14x），即可调用 Wan2.7 与 HappyHorse 全部视频模型（截图中为分组旧名 Wan，现已更名 Wan&HappyHorse）

​

模型定价

​

默认价格 = 阿里云官方原价的 98％（理解简单）

控制台里 Wan&HappyHorse 分组显示倍率 0.14x，这是按人民币计价单位计的。本站统一用美元充值、固定汇率 1:7，实际折算：

0.14（人民币计价单位） × 7（固定汇率） = 0.98

也就是说，默认价格 = 阿里云官方原价的 98%（98 折）——比官方直采更省，且无需自建出海链路。

换算公式：本站每秒美元价 = 官方人民币原价 × 0.14（即 × 0.98 ÷ 7）。例如官方 1080P 原价 ¥1.0/秒 → $0.14/秒，正好等于控制台里看到的 0.14x。

​

价格明细（默认价，按秒计费）

Wan2.7 文生 / 图生 / 参考生视频同价，仅 720P / 1080P 两档（不支持 480P）：

分辨率	官方原价	本站默认价/秒	5 秒	10 秒	12 秒
720P	¥0.6/秒	$0.084/秒	$0.42	$0.84	$1.01
1080P	¥1.0/秒	$0.14/秒	$0.70	$1.40	$1.68

• wan2.7-r2v 默认 1080P，且参考素材含视频时时长上限为 10 秒。
• wan2.7-videoedit（视频编辑）输出时长跟随源视频，按实际输出秒数计费，不由 duration 决定。
• 表中为 默认价（官方 98%）；叠加充值加赠最高档约为表中价 ÷ 1.2（例：1080P 5 秒 $0.70 → 约 $0.58）。

​

叠加充值加赠，折扣进一步走低

参与 充值加赠活动 后，到账额度最高可放大约 1.2 倍，等效价格进一步下探：

0.98 ÷ 1.2 ≈ 0.816

即大客户最低可做到 官方原价的约 81.6%（约 82 折）。

档位	等效价格（对比阿里云官方原价）	算法
默认	98%（98 折）	倍率 0.14x × 固定汇率 7
叠加充值加赠（大客户最高档）	约 81.6%（约 82 折）	0.98 ÷ 1.2

• 计费维度 = 分辨率档位 × 时长（秒），失败任务不计费。
• 1:7 为固定结算汇率（不是优惠汇率），所有美元充值统一适用。
• 充值加赠的最高加赠档位与适用渠道见 充值加赠活动。最新倍率以 控制台 为准。

​

⚠️ 端点选择（最重要）

API易 同时挂载两条路径，只有 DashScope 透传端点对 Wan 全部能力完整可用：

路径	协议风格	i2v / r2v 可用性	结论
/v1/videos	OpenAI 扁平风格	❌ 媒体字段会被丢弃	不要用
/wan/api/v1/services/aigc/video-generation/video-synthesis	DashScope 原生透传	✅ 完整可用	始终用这条

看到任何文档/示例里写 /v1/videos 提交 Wan 视频任务，直接忽略。该路径对 i2v / r2v 的 media 字段适配不完整，会导致上游报 [InvalidParameter] Field required: input.media。所有 Wan 视频创建请求都走 /wan/api/v1/...video-synthesis。

​

异步调用流程

整套流程是异步的三步：创建任务 → 轮询状态 → 下载视频。

1. 创建任务

   POST /wan/api/v1/services/aigc/video-generation/video-synthesis，请求头带 X-DashScope-Async: enable，立刻返回 task_id。

2. 轮询状态

   GET /v1/tasks/{task_id}（带 Authorization），每 5–10 秒查一次（不要小于 3 秒），直到 status 变为 completed。

3. 下载视频

   从响应的 result_url 直接 GET 下载 mp4，不要带 Authorization 头（它是 OSS 签名直链，带 Auth 反而 403）。

​

任务状态说明

GET /v1/tasks/{task_id} 响应顶层的 status 字段（API易 已统一收口）：

状态	含义	下一步操作
submitted	已提交，排队中	继续轮询
in_progress	生成中	继续轮询（progress 常停在 30%，是上游汇报粒度粗，不是卡住）
completed	成功	从 result_url 下载
failed	失败	看 error.message / fail_reason

​

完整 Python 客户端

import json, time, urllib.request

BASE = "https://api.apiyi.com"
KEY  = "sk-your-api-key"   # 你的 API易 Key

def post(path, body):
    h = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json",
         "X-DashScope-Async": "enable"}
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode(), headers=h, method="POST")
    return json.loads(urllib.request.urlopen(req).read())

def get(path):
    req = urllib.request.Request(BASE + path, headers={"Authorization": f"Bearer {KEY}"})
    return json.loads(urllib.request.urlopen(req).read())

# 1. 创建任务（切换玩法只改 model 和 media）
r = post("/wan/api/v1/services/aigc/video-generation/video-synthesis", {
    "model": "wan2.7-t2v",
    "input": {"prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，海鸟叫声"},
    "parameters": {"resolution": "720P", "duration": 5, "prompt_extend": True, "watermark": True}
})
task_id = r["output"]["task_id"]
print("task_id:", task_id)

# 2. 轮询（5–10 秒一次）
while True:
    info = get(f"/v1/tasks/{task_id}")
    status = info["status"]
    print("status:", status, "progress:", info.get("progress"))
    if status == "completed":
        url = info["result_url"]
        break
    if status == "failed":
        raise RuntimeError(info.get("error") or info.get("fail_reason"))
    time.sleep(10)

# 3. 下载（不要带 Authorization！result_url 是 OSS 签名直链）
urllib.request.urlretrieve(url, "out.mp4")
print("saved out.mp4")

​

关键参数详解

提交时 body 为 DashScope 嵌套结构：{ model, input: { prompt, media[] }, parameters: {...} }。

​

input 字段

字段	类型	必填	说明
prompt	string	✓	自然语言描述，wan2.7-r2v 支持「图1 / 视频1」标识指代参考素材
negative_prompt	string		反向提示词，≤500 字符
media	array	i2v/r2v/edit 必填	媒体素材数组，见下

​

media[] 类型

type	用途	适用模型
first_frame	首帧图（≤1 张）	i2v、r2v
reference_image	参考图（保持主体/场景）	r2v、videoedit
reference_video	参考视频（主体/音色参考）	r2v
driving_audio	驱动音频（对口型）	仅 i2v
video	输入视频	videoedit
reference_voice	音色参考（附在 reference_image/video 上）	r2v

每个媒体对象至少含 type + url，url 必须是公网可直接 GET 的 https 链接（本地文件先上传到 OSS / CDN）。

​

parameters 字段

字段	类型	取值	说明
resolution	string	720P / 1080P	大写，建议显式指定
ratio	string	16:9 / 9:16 / 1:1 / 4:3 / 3:4	宽高比；传了首帧图时自动忽略
duration	int	2–15	秒数（整数），常用 5 / 10；含参考视频时上限为 10
prompt_extend	bool	true / false	智能改写 prompt，强烈推荐 true
watermark	bool	true / false	右下角「AI 生成」水印
seed	int	0–2147483647	固定可提升可复现性

duration 必须是 整数 5 而不是字符串 "5"，否则报 cannot unmarshal string into Go struct field ... of type int。resolution 写 大写 720P 更稳。

​

如何选择 Wan 还是 HappyHorse

Wan 和 HappyHorse 都是阿里系视频模型、共用同一端点和 schema（只改 model 名即可互换），但能力侧重不同：

维度	Wan2.7	HappyHorse-1.1
音频驱动对口型（i2v）	✅ wan2.7-i2v 支持 driving_audio	❌ 不支持，i2v 仅首帧
参考图生视频上限	参考图 + 参考视频合计 ≤5	参考图最多 9 张
视频编辑参考图	≤5 张	≤5 张
主体一致性风格	多主体互动、音色参考	偏「高度还原动态画面」，主体保持稳

需要对口型 / rap / 数字人口播 → 选 wan2.7-i2v（唯一支持音频驱动）。 需要多张参考图保持主体一致 → 考虑 HappyHorse r2v（≤9 张）。

​

最佳实践

1. 先用 720P / 5 秒联调

   开发期用低分辨率短视频快速验证 prompt 与镜头方向，定型后再放大到 720P / 1080P 与更长时长，降低单价与等待时间。

2. 始终开 prompt_extend

   prompt_extend: true 对短 prompt 的画质提升明显，代价只是多几秒生成时间。

3. 轮询 5–10 秒一次

   不要小于 3 秒（会被限流），也不要长任务死等。720P / 5 秒典型耗时 70–140 秒，1080P / 长视频可能超 5 分钟。

4. 客户端超时设 20 分钟兜底

   1080P 或 10 秒以上视频显著更慢，给轮询循环设置 20 分钟兜底超时。

5. 拿到 result_url 立即下载落地

   result_url 默认 24 小时过期，且是 OSS 签名直链，下载时不要带 Authorization 头。生产场景务必转存到自己的 OSS / CDN。

6. 做好幂等

   失败任务不扣费，但重复提交相同任务会重复计费。业务层维护「业务 ID → task_id」映射避免误扣。

​

错误码与重试

错误来自两个阶段，处理方式不同：

来源	特征	处理
创建阶段（API易 拒）	HTTP 4xx/5xx，type 为 task_error / parse_request_failed / build_request_failed	改 body 重试（多为字段类型错、缺 media、用错端点）
执行阶段（上游阿里云拒）	任务最终 status=failed，error.message 以 [InvalidParameter] / [InvalidImageUrl] 等方括号前缀打头	看方括号提示，多为媒体 URL 不可达或 prompt 涉敏

建议客户端：HTTP 5xx / 网络错误做指数退避重试（1s / 4s / 16s）；HTTP 4xx 立刻 surface 不重试；任务 failed 含 [InvalidImageUrl] 可重试（可能临时网络），含 [InvalidParameter] / 敏感词不重试。

​

常见问题

为什么不能用 /v1/videos 提交 Wan 任务？

/v1/videos 是 OpenAI 扁平风格端点，对 Wan 的 i2v / r2v 适配不完整：media 等媒体字段会被丢弃，上游阿里云会报 [InvalidParameter] Field required: input.media。所有 Wan 视频创建请求都走 /wan/api/v1/services/aigc/video-generation/video-synthesis，查询统一走 /v1/tasks/{task_id}。

X-DashScope-Async: enable 这个头是干啥的？必须带吗？

它告诉端点「这是异步任务，立刻返回 task_id 不要堵塞」。所有创建请求都必须带，缺失会报 current user api does not support synchronous calls。查询任务（GET）不需要带这个头。

查任务为什么是 /v1/tasks/{id} 而不是 /wan/api/v1/tasks/{id}？

API易 把所有视频任务查询统一收口到了 /v1/tasks/{task_id}。不管你用哪个路径创建，查任务都走这一个端点，响应顶层的 status / progress / result_url / error 字段一致。

result_url 下载报 403 / SignatureDoesNotMatch 怎么办？

去掉 Authorization 头。result_url 已经是阿里云 OSS 签好名的直链，再带 API易 Key OSS 反而会拒：

curl -L -o out.mp4 "$RESULT_URL"          # ✅ 对
curl -L -H "Authorization: Bearer $KEY" -o out.mp4 "$RESULT_URL"   # ❌ 错

result_url 过期了怎么办？

链接默认有效期 24 小时。过期后重新 GET /v1/tasks/{task_id} 通常会得到新的 result_url，但 task_id 本身查询有效期也是 24 小时（超时返回 UNKNOWN）。需要长期保存请尽快下载到自己的存储。

progress 一直停在 30% 是卡住了吗？

不是。阿里云上游汇报的 progress 是粗粒度的（只有 0% / 10% / 30% / 100% 几档）。只要 status 还是 in_progress 就继续等，通常 30% 到 100% 之间直接跳过。

一个 Key 能并发跑几个任务？

实测可同时提交 4–8 个任务不报限流。生产建议同时活跃任务 ≤10 个，超出排队。查询接口默认 RPS 较高，但轮询间隔仍建议 5–10 秒。

失败任务扣费吗？

status=failed 不扣费。但需注意：重复提交相同任务会重复计费，做好幂等。测试期可关掉 prompt_extend、用 720P / 5 秒 / 短 prompt 降低单价。

wan2.6 还能用吗？

可以。Wan2.6 系列（含 wan2.6-r2v-flash）仍在可调用列表，协议与 Wan2.7 一致，只改 model 名即可。详见 历史版本。

​

相关文档

文生视频 Playground

wan2.7-t2v 在线调试 + 代码示例

图生视频 Playground

wan2.7-i2v 首帧 + 驱动音频

参考图生视频 Playground

wan2.7-r2v 多主体参考 + 音色

视频编辑 Playground

wan2.7-videoedit 换装 / 换背景

历史版本（Wan2.6）

Wan2.6 系列与迁移说明

HappyHorse 系列

同为阿里系，选型对照

阿里云官方文档（参考）：help.aliyun.com/zh/model-studio/text-to-video-api-reference。如有问题或建议，欢迎在 API易控制台 工单中反馈。