> ## 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 视频生成（阿里云通义万相）

> 阿里云通义万相 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 张参考图 + 编辑指令 | 换装、换背景等编辑后的视频            |

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

<CardGroup cols={2}>
  <Card title="文生视频 API" icon="wand-sparkles" href="/api-capabilities/wan/text-to-video">
    `wan2.7-t2v`，纯文本提示词生成视频，最简单的入口。
  </Card>

  <Card title="图生视频 API" icon="image" href="/api-capabilities/wan/image-to-video">
    `wan2.7-i2v`，首帧图 + 可选驱动音频，做对口型 / rap。
  </Card>

  <Card title="参考图生视频 API" icon="users" href="/api-capabilities/wan/reference-to-video">
    `wan2.7-r2v`，参考图/视频保持主体特征，支持音色参考。
  </Card>

  <Card title="视频编辑 API" icon="scissors" href="/api-capabilities/wan/video-edit">
    `wan2.7-videoedit`，视频 + 参考图做换装、换背景等编辑。
  </Card>

  <Card title="可视化接口测试" icon="flask-conical" href="https://icover.ai/zh/wan-official">
    在 iCover 可视化测试工具里直接调试本接口，无需写代码。
  </Card>

  <Card title="异步任务查询 / 下载" icon="list-checks" href="https://api.apiyi.com/task">
    在 API易后台查看已提交的视频任务、下载视频链接（API 之外的查询入口）。
  </Card>
</CardGroup>

## 为什么选 API易 的 Wan

<CardGroup cols={2}>
  <Card title="一个 Key 调全部能力" icon="key">
    无需注册阿里云、无需配置地域和环境变量。一把 API易 Key 即可调用 Wan2.7 全部四种能力以及 [HappyHorse 系列](/api-capabilities/happyhorse/overview)。
  </Card>

  <Card title="国内直连 · 免出海" icon="globe">
    直连 `api.apiyi.com`，国内机房、家宽网络均可访问，省去为阿里云配置地域 Endpoint 的麻烦。
  </Card>

  <Card title="失败不计费" icon="circle-check">
    任务进入 `failed` 状态（媒体 URL 不可达、prompt 涉敏、上游容量等）**不计费**，可放心重试。
  </Card>

  <Card title="DashScope 协议透传" icon="plug">
    请求体与阿里云 DashScope 原生协议一一对齐，对照官方文档即可迁移，响应已统一收口便于轮询。
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="四合一异步端点" icon="list-check">
    t2v / i2v / r2v / video-edit 共用 `POST /wan/api/v1/...video-synthesis`，提交后返回 `task_id`，轮询 + 下载，便于批量管理。
  </Card>

  <Card title="音频驱动对口型" icon="volume-2">
    `wan2.7-i2v` 支持 `driving_audio`，让静态人像跟随音频做口型与节奏，适合 rap / 口播 / 数字人。
  </Card>

  <Card title="多主体参考" icon="users">
    `wan2.7-r2v` 支持参考图 + 参考视频混合输入（合计 ≤5），用「图1 / 视频1」标识在 prompt 里指代，支持音色参考。
  </Card>

  <Card title="多档分辨率与时长" icon="expand">
    720P / 1080P 分辨率，2–15 秒整数时长，`prompt_extend` 智能改写进一步提升短 prompt 的画质。
  </Card>
</CardGroup>

## 支持的模型

| 模型 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 张）           | 编辑模型名 **无连字符**            |

<Warning>
  `wan2.7-videoedit` 是图像编辑视频用途；另有 `wan2.7-image-pro` 属于 **图片** 模型（走 `/v1/images/generations`），不在本视频端点范围内，请勿混用。历史版本 Wan2.6 见 [历史版本](/api-capabilities/wan/historical-versions)。
</Warning>

## 分组介绍

Wan 与 [HappyHorse](/api-capabilities/happyhorse/overview) 两个系列**共用同一个 `Wan` 分组**——一把令牌即可同时调用两个系列（如图令牌名 `Wan2.7&HappyHorse`）。视频模型按**秒**计费，令牌必须同时满足两个条件才能成功路由：

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

<Frame caption="创建令牌：计费模式选「按量优先」，分组选 Wan（0.14x），即可调用 Wan2.7 与 HappyHorse 全部视频模型">
  <img src="https://mintcdn.com/apiyillc/5-SttsT0c5VQwgVz/images/wan-token-group-setup-20260523.png?fit=max&auto=format&n=5-SttsT0c5VQwgVz&q=85&s=f46887cb88777eb34d70837983f1fc49" alt="创建令牌界面：计费模式选「按量优先」，分组下拉中选择 Wan（倍率 0.14x），令牌可同时用于 Wan2.7 与 HappyHorse" width="1286" height="988" data-path="images/wan-token-group-setup-20260523.png" />
</Frame>

## 模型定价

### 默认价格 = 阿里云官方原价的 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 |

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

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

参与 [充值加赠活动](/faq/recharge-promotions) 后，到账额度最高可放大约 1.2 倍，等效价格进一步下探：

```
0.98 ÷ 1.2 ≈ 0.816
```

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

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

<Info>
  * 计费维度 = **分辨率档位 × 时长（秒）**，失败任务不计费。
  * 1:7 为**固定结算汇率**（不是优惠汇率），所有美元充值统一适用。
  * 充值加赠的最高加赠档位与适用渠道见 [充值加赠活动](/faq/recharge-promotions)。最新倍率以 [控制台](https://api.apiyi.com/token) 为准。
</Info>

## ⚠️ 端点选择（最重要）

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

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

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

## 异步调用流程

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

<Steps>
  <Step title="创建任务">
    `POST /wan/api/v1/services/aigc/video-generation/video-synthesis`，请求头带 `X-DashScope-Async: enable`，立刻返回 `task_id`。
  </Step>

  <Step title="轮询状态">
    `GET /v1/tasks/{task_id}`（带 `Authorization`），每 5–10 秒查一次（**不要小于 3 秒**），直到 `status` 变为 `completed`。
  </Step>

  <Step title="下载视频">
    从响应的 `result_url` 直接 GET 下载 mp4，**不要带 `Authorization` 头**（它是 OSS 签名直链，带 Auth 反而 403）。
  </Step>
</Steps>

### 任务状态说明

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

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

### 完整 Python 客户端

```python theme={null}
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                            | 固定可提升可复现性                     |

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

## 如何选择 Wan 还是 HappyHorse

Wan 和 [HappyHorse](/api-capabilities/happyhorse/overview) 都是阿里系视频模型、共用同一端点和 schema（只改 `model` 名即可互换），但能力侧重不同：

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

<Tip>
  **需要对口型 / rap / 数字人口播** → 选 `wan2.7-i2v`（唯一支持音频驱动）。
  **需要多张参考图保持主体一致** → 考虑 [HappyHorse r2v（≤9 张）](/api-capabilities/happyhorse/reference-to-video)。
</Tip>

## 最佳实践

<Steps>
  <Step title="先用 720P / 5 秒联调">
    开发期用低分辨率短视频快速验证 prompt 与镜头方向，定型后再放大到 720P / 1080P 与更长时长，降低单价与等待时间。
  </Step>

  <Step title="始终开 prompt_extend">
    `prompt_extend: true` 对短 prompt 的画质提升明显，代价只是多几秒生成时间。
  </Step>

  <Step title="轮询 5–10 秒一次">
    不要小于 3 秒（会被限流），也不要长任务死等。720P / 5 秒典型耗时 70–140 秒，1080P / 长视频可能超 5 分钟。
  </Step>

  <Step title="客户端超时设 20 分钟兜底">
    1080P 或 10 秒以上视频显著更慢，给轮询循环设置 20 分钟兜底超时。
  </Step>

  <Step title="拿到 result_url 立即下载落地">
    `result_url` 默认 **24 小时过期**，且是 OSS 签名直链，下载时**不要带 Authorization 头**。生产场景务必转存到自己的 OSS / CDN。
  </Step>

  <Step title="做好幂等">
    失败任务不扣费，但重复提交相同任务会重复计费。业务层维护「业务 ID → task\_id」映射避免误扣。
  </Step>
</Steps>

## 错误码与重试

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

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

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

## 常见问题

<AccordionGroup>
  <Accordion title="为什么不能用 /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}`。
  </Accordion>

  <Accordion title="X-DashScope-Async: enable 这个头是干啥的？必须带吗？">
    它告诉端点「这是异步任务，立刻返回 task\_id 不要堵塞」。**所有创建请求都必须带**，缺失会报 `current user api does not support synchronous calls`。查询任务（GET）不需要带这个头。
  </Accordion>

  <Accordion title="查任务为什么是 /v1/tasks/{id} 而不是 /wan/api/v1/tasks/{id}？">
    API易 把所有视频任务查询统一收口到了 `/v1/tasks/{task_id}`。不管你用哪个路径创建，查任务都走这一个端点，响应顶层的 `status` / `progress` / `result_url` / `error` 字段一致。
  </Accordion>

  <Accordion title="result_url 下载报 403 / SignatureDoesNotMatch 怎么办？">
    去掉 `Authorization` 头。`result_url` 已经是阿里云 OSS 签好名的直链，再带 API易 Key OSS 反而会拒：

    ```bash theme={null}
    curl -L -o out.mp4 "$RESULT_URL"          # ✅ 对
    curl -L -H "Authorization: Bearer $KEY" -o out.mp4 "$RESULT_URL"   # ❌ 错
    ```
  </Accordion>

  <Accordion title="result_url 过期了怎么办？">
    链接默认有效期 **24 小时**。过期后重新 GET `/v1/tasks/{task_id}` 通常会得到新的 `result_url`，但 task\_id 本身查询有效期也是 24 小时（超时返回 `UNKNOWN`）。需要长期保存请尽快下载到自己的存储。
  </Accordion>

  <Accordion title="progress 一直停在 30% 是卡住了吗？">
    不是。阿里云上游汇报的 progress 是粗粒度的（只有 0% / 10% / 30% / 100% 几档）。**只要 `status` 还是 `in_progress` 就继续等**，通常 30% 到 100% 之间直接跳过。
  </Accordion>

  <Accordion title="一个 Key 能并发跑几个任务？">
    实测可同时提交 4–8 个任务不报限流。生产建议同时活跃任务 ≤10 个，超出排队。查询接口默认 RPS 较高，但轮询间隔仍建议 5–10 秒。
  </Accordion>

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

  <Accordion title="wan2.6 还能用吗？">
    可以。Wan2.6 系列（含 `wan2.6-r2v-flash`）仍在可调用列表，协议与 Wan2.7 一致，只改 `model` 名即可。详见 [历史版本](/api-capabilities/wan/historical-versions)。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="文生视频 Playground" icon="wand-sparkles" href="/api-capabilities/wan/text-to-video">
    `wan2.7-t2v` 在线调试 + 代码示例
  </Card>

  <Card title="图生视频 Playground" icon="image" href="/api-capabilities/wan/image-to-video">
    `wan2.7-i2v` 首帧 + 驱动音频
  </Card>

  <Card title="参考图生视频 Playground" icon="users" href="/api-capabilities/wan/reference-to-video">
    `wan2.7-r2v` 多主体参考 + 音色
  </Card>

  <Card title="视频编辑 Playground" icon="scissors" href="/api-capabilities/wan/video-edit">
    `wan2.7-videoedit` 换装 / 换背景
  </Card>

  <Card title="历史版本（Wan2.6）" icon="history" href="/api-capabilities/wan/historical-versions">
    Wan2.6 系列与迁移说明
  </Card>

  <Card title="HappyHorse 系列" icon="horse" href="/api-capabilities/happyhorse/overview">
    同为阿里系，选型对照
  </Card>
</CardGroup>

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