Documentation Index
Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
Use this file to discover all available pages before exploring further.
概述
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,视频 + 参考图做换装、换背景等编辑。为什么选 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 张) | 编辑模型名 无连字符 |
分组介绍
Wan 与 HappyHorse 两个系列共用同一个Wan 分组——一把令牌即可同时调用两个系列(如图令牌名 Wan2.7&HappyHorse)。视频模型按秒计费,令牌必须同时满足两个条件才能成功路由:
- 计费模式:选「按量优先」或「按量计费」—— 视频按秒计费,按次计费的令牌无法路由
- 分组:选择包含
Wan

模型定价
默认价格 = 阿里云官方原价的 98%(理解简单)
控制台里Wan 分组显示倍率 0.14x,这是按人民币计价单位计的。本站统一用美元充值、固定汇率 1:7,实际折算:
换算公式:本站每秒美元价 = 官方人民币原价 × 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 倍,等效价格进一步下探:| 档位 | 等效价格(对比阿里云官方原价) | 算法 |
|---|---|---|
| 默认 | 98%(98 折) | 倍率 0.14x × 固定汇率 7 |
| 叠加充值加赠(大客户最高档) | 约 81.6%(约 82 折) | 0.98 ÷ 1.2 |
⚠️ 端点选择(最重要)
API易 同时挂载两条路径,只有 DashScope 透传端点对 Wan 全部能力完整可用:| 路径 | 协议风格 | i2v / r2v 可用性 | 结论 |
|---|---|---|---|
/v1/videos | OpenAI 扁平风格 | ❌ 媒体字段会被丢弃 | 不要用 |
/wan/api/v1/services/aigc/video-generation/video-synthesis | DashScope 原生透传 | ✅ 完整可用 | 始终用这条 |
异步调用流程
整套流程是异步的三步:创建任务 → 轮询状态 → 下载视频。创建任务
POST /wan/api/v1/services/aigc/video-generation/video-synthesis,请求头带 X-DashScope-Async: enable,立刻返回 task_id。任务状态说明
GET /v1/tasks/{task_id} 响应顶层的 status 字段(API易 已统一收口):
| 状态 | 含义 | 下一步操作 |
|---|---|---|
submitted | 已提交,排队中 | 继续轮询 |
in_progress | 生成中 | 继续轮询(progress 常停在 30%,是上游汇报粒度粗,不是卡住) |
completed | 成功 | 从 result_url 下载 |
failed | 失败 | 看 error.message / fail_reason |
完整 Python 客户端
关键参数详解
提交时 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 | 固定可提升可复现性 |
如何选择 Wan 还是 HappyHorse
Wan 和 HappyHorse 都是阿里系视频模型、共用同一端点和 schema(只改model 名即可互换),但能力侧重不同:
| 维度 | Wan2.7 | HappyHorse-1.0 |
|---|---|---|
| 音频驱动对口型(i2v) | ✅ wan2.7-i2v 支持 driving_audio | ❌ 不支持,i2v 仅首帧 |
| 参考图生视频上限 | 参考图 + 参考视频合计 ≤5 | 参考图最多 9 张 |
| 视频编辑参考图 | ≤5 张 | ≤5 张 |
| 主体一致性风格 | 多主体互动、音色参考 | 偏「高度还原动态画面」,主体保持稳 |
最佳实践
拿到 result_url 立即下载落地
result_url 默认 24 小时过期,且是 OSS 签名直链,下载时不要带 Authorization 头。生产场景务必转存到自己的 OSS / CDN。错误码与重试
错误来自两个阶段,处理方式不同:| 来源 | 特征 | 处理 |
|---|---|---|
| 创建阶段(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 提交 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 这个头是干啥的?必须带吗?
X-DashScope-Async: enable 这个头是干啥的?必须带吗?
它告诉端点「这是异步任务,立刻返回 task_id 不要堵塞」。所有创建请求都必须带,缺失会报
current user api does not support synchronous calls。查询任务(GET)不需要带这个头。查任务为什么是 /v1/tasks/{id} 而不是 /wan/api/v1/tasks/{id}?
查任务为什么是 /v1/tasks/{id} 而不是 /wan/api/v1/tasks/{id}?
API易 把所有视频任务查询统一收口到了
/v1/tasks/{task_id}。不管你用哪个路径创建,查任务都走这一个端点,响应顶层的 status / progress / result_url / error 字段一致。result_url 下载报 403 / SignatureDoesNotMatch 怎么办?
result_url 下载报 403 / SignatureDoesNotMatch 怎么办?
去掉
Authorization 头。result_url 已经是阿里云 OSS 签好名的直链,再带 API易 Key OSS 反而会拒:result_url 过期了怎么办?
result_url 过期了怎么办?
链接默认有效期 24 小时。过期后重新 GET
/v1/tasks/{task_id} 通常会得到新的 result_url,但 task_id 本身查询有效期也是 24 小时(超时返回 UNKNOWN)。需要长期保存请尽快下载到自己的存储。progress 一直停在 30% 是卡住了吗?
progress 一直停在 30% 是卡住了吗?
不是。阿里云上游汇报的 progress 是粗粒度的(只有 0% / 10% / 30% / 100% 几档)。只要
status 还是 in_progress 就继续等,通常 30% 到 100% 之间直接跳过。一个 Key 能并发跑几个任务?
一个 Key 能并发跑几个任务?
实测可同时提交 4–8 个任务不报限流。生产建议同时活跃任务 ≤10 个,超出排队。查询接口默认 RPS 较高,但轮询间隔仍建议 5–10 秒。
失败任务扣费吗?
失败任务扣费吗?
status=failed 不扣费。但需注意:重复提交相同任务会重复计费,做好幂等。测试期可关掉 prompt_extend、用 720P / 5 秒 / 短 prompt 降低单价。wan2.6 还能用吗?
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易控制台 工单中反馈。