Skip to main content

概述

Wan(通義萬相) 是阿里雲推出的影片生成模型系列。API易 通過 DashScope 透傳通道 直連阿里雲百鍊,讓你用一個 sk- 開頭的 API易 Key 即可呼叫全部 Wan 影片能力,無需單獨註冊阿里雲賬號。當前主力版本為 Wan2.7,覆蓋四種核心玩法:
🎬 核心亮點:四種能力共用同一個非同步端點和同一套請求結構,切換玩法只改 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 的畫質。

支援的模型

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&HappyHorse(0.14x),即可呼叫 Wan2.7 與 HappyHorse 全部影片模型(截圖中為分組舊名 Wan,現已更名 Wan&HappyHorse)

模型定價

預設價格 = 阿里雲官方原價的 98%(理解簡單)

控制台裡 Wan&HappyHorse 分組顯示倍率 0.14x,這是按人民幣計價單位計的。本站統一用美元充值、固定匯率 1:7,實際折算:
也就是說,預設價格 = 阿里雲官方原價的 98%(98 折)——比官方直採更省,且無需自建出海鏈路。
換算公式:本站每秒美元價 = 官方人民幣原價 × 0.14(即 × 0.98 ÷ 7)。例如官方 1080P 原價 ¥1.0/秒 → $0.14/秒,正好等於控制台裡看到的 0.14x

價格明細(預設價,按秒計費)

Wan2.7 文生 / 圖生 / 參考生影片同價,僅 720P / 1080P 兩檔(不支援 480P):
  • wan2.7-r2v 預設 1080P,且參考素材含影片時時長上限為 10 秒。
  • wan2.7-videoedit(影片編輯)輸出時長跟隨源影片,按實際輸出秒數計費,不由 duration 決定。
  • 表中為 預設價(官方 98%);疊加充值加贈最高檔約為表中價 ÷ 1.2(例:1080P 5 秒 $0.70 → 約 $0.58)。

疊加充值加贈,折扣進一步走低

參與 充值加贈活動 後,到賬額度最高可放大約 1.2 倍,等效價格進一步下探:
即大客戶最低可做到 官方原價的約 81.6%(約 82 折)
  • 計費維度 = 解析度檔位 × 時長(秒),失敗任務不計費。
  • 1:7 為固定結算匯率(不是優惠匯率),所有美元充值統一適用。
  • 充值加贈的最高加贈檔位與適用渠道見 充值加贈活動。最新倍率以 控制台 為準。

⚠️ 端點選擇(最重要)

API易 同時掛載兩條路徑,只有 DashScope 透傳端點對 Wan 全部能力完整可用
看到任何文件/示例裡寫 /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易 已統一收口):

完整 Python 客戶端

關鍵引數詳解

提交時 body 為 DashScope 巢狀結構:{ model, input: { prompt, media[] }, parameters: {...} }

input 欄位

media[] 型別

每個媒體物件至少含 type + urlurl 必須是公網可直接 GET 的 https 連結(本地檔案先上傳到 OSS / CDN)。

parameters 欄位

duration 必須是 整數 5 而不是字串 "5",否則報 cannot unmarshal string into Go struct field ... of type intresolution大寫 720P 更穩。

如何選擇 Wan 還是 HappyHorse

Wan 和 HappyHorse 都是阿里系影片模型、共用同一端點和 schema(只改 model 名即可互換),但能力側重不同:
需要對口型 / 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」對映避免誤扣。

錯誤碼與重試

錯誤來自兩個階段,處理方式不同:
建議客戶端: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 反而會拒:
連結預設有效期 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易控制台 工單中反饋。