> ## 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 張參考圖 + 編輯指令 | 換裝、換背景等編輯後的影片 |
**🎬 核心亮點**：四種能力共用同一個非同步端點和同一套請求結構，**切換玩法只改 `model` 欄位**。原生支援 720P / 1080P 解析度與 2–15 秒整數時長，`wan2.7-i2v` 還支援驅動音訊做對口型。適合短影片生產、電商素材、數字人口播、創意運營等場景。
`wan2.7-t2v`，純文本提示詞生成影片，最簡單的入口。
`wan2.7-i2v`，首幀圖 + 可選驅動音訊，做對口型 / rap。
`wan2.7-r2v`，參考圖/影片保持主體特徵，支援音色參考。
`wan2.7-videoedit`，影片 + 參考圖做換裝、換背景等編輯。
在 iCover 視覺化測試工具裡直接除錯本介面，無需寫程式碼。
在 API易後臺檢視已提交的影片任務、下載影片連結（API 之外的查詢入口）。
## 為什麼選 API易 的 Wan
無需註冊阿里雲、無需配置地域和環境變數。一把 API易 Key 即可呼叫 Wan2.7 全部四種能力以及 [HappyHorse 系列](/zh-Hant/api-capabilities/happyhorse/overview)。
直連 `api.apiyi.com`，國內機房、家寬網路均可訪問，省去為阿里雲配置地域 Endpoint 的麻煩。
任務進入 `failed` 狀態（媒體 URL 不可達、prompt 涉敏、上游容量等）**不計費**，可放心重試。
請求體與阿里雲 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 見 [歷史版本](/zh-Hant/api-capabilities/wan/historical-versions)。
## 分組介紹
Wan 與 [HappyHorse](/zh-Hant/api-capabilities/happyhorse/overview) 兩個系列**共用同一個 `Wan&HappyHorse` 分組**——一把令牌即可同時呼叫兩個系列。影片模型按**秒**計費，令牌必須同時滿足兩個條件才能成功路由：
1. **計費模式**：選「按量優先」或「按量計費」—— 影片按秒計費，**按次計費的令牌無法路由**
2. **分組**：選擇包含 `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）。
### 疊加充值加贈，折扣進一步走低
參與 [充值加贈活動](/zh-Hant/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 |
* 計費維度 = **解析度檔位 × 時長（秒）**，失敗任務不計費。
* 1:7 為**固定結算匯率**（不是優惠匯率），所有美元充值統一適用。
* 充值加贈的最高加贈檔位與適用渠道見 [充值加贈活動](/zh-Hant/faq/recharge-promotions)。最新倍率以 [控制台](https://api.apiyi.com/token) 為準。
## ⚠️ 端點選擇（最重要）
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`。
## 非同步呼叫流程
整套流程是非同步的三步：**建立任務 → 輪詢狀態 → 下載影片**。
`POST /wan/api/v1/services/aigc/video-generation/video-synthesis`，請求頭帶 `X-DashScope-Async: enable`，立刻返回 `task_id`。
`GET /v1/tasks/{task_id}`（帶 `Authorization`），每 5–10 秒查一次（**不要小於 3 秒**），直到 `status` 變為 `completed`。
從響應的 `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 客戶端
```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 | 固定可提升可復現性 |
`duration` 必須是 **整數** `5` 而不是字串 `"5"`，否則報 `cannot unmarshal string into Go struct field ... of type int`。`resolution` 寫 **大寫** `720P` 更穩。
## 如何選擇 Wan 還是 HappyHorse
Wan 和 [HappyHorse](/zh-Hant/api-capabilities/happyhorse/overview) 都是阿里系影片模型、共用同一端點和 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 張）](/zh-Hant/api-capabilities/happyhorse/reference-to-video)。
## 最佳實踐
開發期用低解析度短影片快速驗證 prompt 與鏡頭方向，定型後再放大到 720P / 1080P 與更長時長，降低單價與等待時間。
`prompt_extend: true` 對短 prompt 的畫質提升明顯，代價只是多幾秒生成時間。
不要小於 3 秒（會被限流），也不要長任務死等。720P / 5 秒典型耗時 70–140 秒，1080P / 長影片可能超 5 分鐘。
1080P 或 10 秒以上影片顯著更慢，給輪詢迴圈設定 20 分鐘兜底超時。
`result_url` 預設 **24 小時過期**，且是 OSS 簽名直鏈，下載時**不要帶 Authorization 頭**。生產場景務必轉存到自己的 OSS / CDN。
失敗任務不扣費，但重複提交相同任務會重複計費。業務層維護「業務 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` 是 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 反而會拒：
```bash theme={null}
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` 名即可。詳見 [歷史版本](/zh-Hant/api-capabilities/wan/historical-versions)。
## 相關文件
`wan2.7-t2v` 線上除錯 + 程式碼示例
`wan2.7-i2v` 首幀 + 驅動音訊
`wan2.7-r2v` 多主體參考 + 音色
`wan2.7-videoedit` 換裝 / 換背景
Wan2.6 系列與遷移說明
同為阿里系，選型對照
阿里雲官方文件（參考）：`help.aliyun.com/zh/model-studio/text-to-video-api-reference`。如有問題或建議，歡迎在 [API易控制台](https://api.apiyi.com) 工單中反饋。