跳转到主要内容

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一段文本 prompt5–15 秒短视频
图生视频wan2.7-i2v首帧图 + prompt(可选驱动音频)让静态图”动起来”,配音频可做对口型 / rap
参考图生视频wan2.7-r2v1–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 张)编辑模型名 无连字符
wan2.7-videoedit 是图像编辑视频用途;另有 wan2.7-image-pro 属于 图片 模型(走 /v1/images/generations),不在本视频端点范围内,请勿混用。历史版本 Wan2.6 见 历史版本

分组介绍

Wan 与 HappyHorse 两个系列共用同一个 Wan 分组——一把令牌即可同时调用两个系列(如图令牌名 Wan2.7&HappyHorse)。视频模型按计费,令牌必须同时满足两个条件才能成功路由:
  1. 计费模式:选「按量优先」或「按量计费」—— 视频按秒计费,按次计费的令牌无法路由
  2. 分组:选择包含 Wan
创建令牌界面:计费模式选「按量优先」,分组下拉中选择 Wan(倍率 0.14x),令牌可同时用于 Wan2.7 与 HappyHorse

模型定价

默认价格 = 阿里云官方原价的 98%(理解简单)

控制台里 Wan 分组显示倍率 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/videosOpenAI 扁平风格❌ 媒体字段会被丢弃不要用
/wan/api/v1/services/aigc/video-generation/video-synthesisDashScope 原生透传✅ 完整可用始终用这条
看到任何文档/示例里写 /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 字段

字段类型必填说明
promptstring自然语言描述,wan2.7-r2v 支持「图1 / 视频1」标识指代参考素材
negative_promptstring反向提示词,≤500 字符
mediaarrayi2v/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 + urlurl 必须是公网可直接 GET 的 https 链接(本地文件先上传到 OSS / CDN)。

parameters 字段

字段类型取值说明
resolutionstring720P / 1080P大写,建议显式指定
ratiostring16:9 / 9:16 / 1:1 / 4:3 / 3:4宽高比;传了首帧图时自动忽略
durationint2–15秒数(整数),常用 5 / 10;含参考视频时上限为 10
prompt_extendbooltrue / false智能改写 prompt,强烈推荐 true
watermarkbooltrue / false右下角「AI 生成」水印
seedint0–2147483647固定可提升可复现性
duration 必须是 整数 5 而不是字符串 "5",否则报 cannot unmarshal string into Go struct field ... of type intresolution大写 720P 更稳。

如何选择 Wan 还是 HappyHorse

Wan 和 HappyHorse 都是阿里系视频模型、共用同一端点和 schema(只改 model 名即可互换),但能力侧重不同:
维度Wan2.7HappyHorse-1.0
音频驱动对口型(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,typetask_error / parse_request_failed / build_request_failed改 body 重试(多为字段类型错、缺 media、用错端点)
执行阶段(上游阿里云拒)任务最终 status=failederror.message[InvalidParameter] / [InvalidImageUrl] 等方括号前缀打头看方括号提示,多为媒体 URL 不可达或 prompt 涉敏
建议客户端:HTTP 5xx / 网络错误做指数退避重试(1s / 4s / 16s);HTTP 4xx 立刻 surface 不重试;任务 failed[InvalidImageUrl] 可重试(可能临时网络),含 [InvalidParameter] / 敏感词不重试。

常见问题

/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}
它告诉端点「这是异步任务,立刻返回 task_id 不要堵塞」。所有创建请求都必须带,缺失会报 current user api does not support synchronous calls。查询任务(GET)不需要带这个头。
API易 把所有视频任务查询统一收口到了 /v1/tasks/{task_id}。不管你用哪个路径创建,查任务都走这一个端点,响应顶层的 status / progress / result_url / error 字段一致。
去掉 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"   # ❌ 错
链接默认有效期 24 小时。过期后重新 GET /v1/tasks/{task_id} 通常会得到新的 result_url,但 task_id 本身查询有效期也是 24 小时(超时返回 UNKNOWN)。需要长期保存请尽快下载到自己的存储。
不是。阿里云上游汇报的 progress 是粗粒度的(只有 0% / 10% / 30% / 100% 几档)。只要 status 还是 in_progress 就继续等,通常 30% 到 100% 之间直接跳过。
实测可同时提交 4–8 个任务不报限流。生产建议同时活跃任务 ≤10 个,超出排队。查询接口默认 RPS 较高,但轮询间隔仍建议 5–10 秒。
status=failed 不扣费。但需注意:重复提交相同任务会重复计费,做好幂等。测试期可关掉 prompt_extend、用 720P / 5 秒 / 短 prompt 降低单价。
可以。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易控制台 工单中反馈。