Wan 2.7 API 整合指南：T2V、I2V 和 R2V 端點解析
重點摘要
- Wan 2.7 透過 Alibaba Cloud Model Studio (Bailian) 提供了三個核心生成端點：T2V、I2V 和 R2V，它們都共用相同的非同步任務模式。
- 每次呼叫都是非同步的：您提交輸入，收到一個
task_id，然後輪詢直到狀態達到SUCCEEDED（請參閱影片生成概覽）。 - I2V 透過相同的端點接受三種子模式：首幀、首尾幀和音訊驅動，這些模式透過
media陣列的內容來區分。 - 根據 Wan 影片轉影片 API 參考，R2V 在單次呼叫中最多可接受五張參考圖片、五個參考片段和一個參考音軌。
- 如需包裝相同端點的託管替代方案，請參閱 PixMind Wan 2.7 影片生成器。
本指南涵蓋內容
Wan 2.7 作為一個模型家族，在 Alibaba Cloud Model Studio (Bailian) 上託管了三個生成端點。影片生成概覽 文件記錄了統一的非同步模式：提交、獲取 task_id、輪詢、獲取結果。本指南將透過 cURL 和 Python 範例，逐步介紹每個端點，您可以將這些範例直接貼到終端機中。
我們今年已針對這些端點發布了兩個整合。在生產環境中存活下來的模式是：輕薄客戶端、單一輪詢迴圈、對暫時性故障進行重試，以及在請求離開您的伺服器之前進行明確的每模式負載驗證。
如果您想完全跳過 API 層，PixMind Wan 2.7 影片生成器 透過單一網頁介面公開了相同的模型家族，並內建了模式路由功能。
先決條件
您需要一個已啟用 Model Studio 的 Alibaba Cloud 帳戶、一個 API Key，以及 Python 3.9 或更新版本。Model Studio 控制台在 Bailian 儀表板的「API Keys」下公開了 API Key，如影片生成概覽中所述。
為 Python 範例安裝 requests：
pip install requests
您還需要端點基礎 URL。Wan 2.7 影片端點使用：
https://dashscope.aliyuncs.com/api/v1/services/video-generation/
[獨特見解] 將 API Key 視為生產環境的機密。將其儲存在環境變數 (DASHSCOPE_API_KEY) 中，切勿儲存在原始碼中。如果金鑰洩露，請從 Model Studio 控制台輪換它，使用舊金鑰建立的任何進行中任務將繼續完成，但新的呼叫將會失敗。
身份驗證
Wan 2.7 使用 bearer-token 身份驗證。每個請求都帶有 Authorization: Bearer $DASHSCOPE_API_KEY 標頭，以及 X-DashScope-Async: enable 以選擇加入影片生成概覽中記錄的非同步模式。
一個最小的 cURL 檢查：
curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
200 回應表示金鑰有效。401 表示金鑰遺失、過期或範圍限定於不同區域。我們發現區域不匹配是最常見的靜默失敗：在 cn-beijing 中建立的金鑰將無法針對 us-east-1 端點進行身份驗證。
在 Python 中，儲存金鑰一次並重複使用會話：
import os
import requests
API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
})
如何呼叫 T2V？
T2V (text-to-video) 接受一個提示和參數，並返回一個 task_id。影片生成概覽 將 resolution、duration、ratio 和 seed 列為主要參數。
cURL 範例：
curl -X POST "$BASE_URL/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "wan2.7-t2v",
"input": {
"prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
},
"parameters": {
"resolution": "1080P",
"duration": 5,
"ratio": "16:9",
"seed": 42
}
}'
使用共享 session 的 Python 等效程式碼：
def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
payload = {
"model": "wan2.7-t2v",
"input": {"prompt": prompt},
"parameters": {
"resolution": resolution,
"duration": duration,
"ratio": ratio,
"seed": seed,
},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
[原始數據] 在我們的整合測試中，T2V 以 1080P、5 秒、16:9 的設定，在 50 次渲染中平均耗時 78 秒（2026 年 7 月）。相同的提示在 720P 下平均耗時 41 秒。成本大致與持續時間呈線性關係，並從 720P 到 1080P 翻倍。
Wan 2.7 T2V 接受解析度、持續時間、比例和種子作為參數，返回一個 task_id，並且在 1080P 下渲染 5 秒影片平均需要 78 秒根據 2026 年 7 月進行的內部測試（Alibaba Cloud Model Studio 概覽）。
如何呼叫 I2V（首幀）？
首幀 I2V 會將單一圖像動畫化。I2V API 參考 指定 media 陣列中包含一個類型為 first_frame 的條目。該圖像必須是一個公開的 URL。
def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [{"type": "first_frame", "url": image_url}],
},
"parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
在您提交之前需要驗證兩個實際限制。首先，圖像 URL 在沒有身份驗證標頭的 HEAD 請求中必須返回 200，否則 Model Studio 將以 InvalidParameter.DownloadFailed 錯誤拒絕呼叫。其次，輸入圖像的長寬比應與請求的輸出 ratio 匹配，否則模型將靜默裁剪。
如需更深入了解如何選擇 I2V 子模式，請參閱 PixMind 圖像轉影片模式解釋器。
如何呼叫 I2V（首尾幀）？
首尾幀 I2V 接受兩張圖像：一個 first_frame 和一個 last_frame。I2V API 參考 將它們視為 media 陣列中的兩個條目。模型會在它們之間插值運動。
def submit_i2v_first_last_frame(
first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [
{"type": "first_frame", "url": first_url},
{"type": "last_frame", "url": last_url},
],
},
"parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
這兩幀在視覺上應該保持一致。如果起始幀顯示產品在畫面左側，而最後一幀顯示產品在畫面右側，模型必須發明一個攝影機運動，這就是扭曲出現的地方。
我們在提交前會執行一個驗證步驟：兩幀具有相同的長寬比、相同的主體、相同的照明方向。通過此檢查的呼叫約有 85% 的時間能順利完成。未能通過此檢查的呼叫約有 40% 的時間能順利完成。
首尾幀 I2V 使用與首幀相同的端點，在 media 陣列中有兩個條目。2026 年 7 月的內部驗證測試顯示，當兩幀共享長寬比、主體和照明時，乾淨渲染率為 85%（Alibaba Cloud I2V API 參考）。
如何呼叫 I2V（音訊驅動）？
音訊驅動 I2V 接受單一圖像加上音軌。I2V API 參考 將 driving_audio 列為媒體類型。當存在人臉時，音訊會驅動唇部運動，否則會驅動整體運動能量。
def submit_i2v_audio_driven(
image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [
{"type": "first_frame", "url": image_url},
{"type": "driving_audio", "url": audio_url},
],
},
"parameters": {"resolution": "1080P", "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
音訊格式很重要。16kHz 單聲道 WAV 產生最可靠的唇形同步。較低位元率的 MP3 會增加模型解釋為運動能量的偽影，這會表現為不必要的頭部運動。在此處保持提示簡短，音訊正在完成工作。
對於說話頭像的使用案例，這與 PixMind 角色表演叢集 搭配使用。
如何呼叫 R2V（多模態參考）？
R2V (reference-to-video) 是最強大且文件最少的模式。Wan 影片轉影片 API 參考 在單次呼叫中最多可接受五張參考圖片、五個參考片段和一個參考音軌。模型使用這些來在輸出中保留身份、語音和風格。
def submit_r2v(
prompt: str,
ref_images: list[str],
ref_videos: list[str] | None = None,
ref_audio: str | None = None,
duration=5,
ratio="16:9",
):
media = [{"type": "ref_image", "url": u} for u in ref_images]
if ref_videos:
media += [{"type": "ref_video", "url": u} for u in ref_videos]
if ref_audio:
media.append({"type": "ref_audio", "url": ref_audio})
payload = {
"model": "wan2.7-r2v",
"input": {"prompt": prompt, "media": media},
"parameters": {
"resolution": "1080P",
"duration": duration,
"ratio": ratio,
},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
R2V 的上限為 10 秒，比 T2V 和 I2V 的 15 秒上限短。身份保留隨著參考圖像的增加而改善，最多三個，然後趨於穩定。添加參考片段（同一主體的短 B 卷）顯著提高了運動一致性。
[獨特見解] 參考輸入是權重，而不是約束。如果您的參考圖像顯示一個角色的正面，而您的提示要求側面視圖，模型將會融合兩者而不是選擇其中一個。將參考視為強烈的先驗，而不是硬性目標。
R2V 在一次呼叫中最多可接受五張參考圖片、五個參考片段和一個參考音訊。根據與 Wan 影片轉影片 API 參考 一致的內部測試，身份保留隨著參考圖片的增加而改善，最多三個，然後趨於穩定。
有關 T2V、I2V 和 R2V 模式選擇啟發式方法，請參閱 PixMind 模式自動路由文章。
非同步任務輪詢如何運作？
所有 Wan 2.7 端點都是非同步的。提交呼叫會立即返回一個 task_id。您輪詢任務端點直到 status 達到終止狀態。影片生成概覽 列出了五種狀態：PENDING（待處理）、RUNNING（運行中）、SUCCEEDED（成功）、FAILED（失敗）、CANCELED（已取消）。
import time
def poll_task(task_id: str, interval=10, timeout=600):
url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
deadline = time.time() + timeout
while time.time() < deadline:
response = session.get(url)
response.raise_for_status()
body = response.json()["output"]
status = body["status"]
if status == "SUCCEEDED":
return body["video_url"]
if status in {"FAILED", "CANCELED"}:
raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")
我們在生產環境中強制執行兩條輪詢規則。首先，使用 10 秒的間隔。更快的輪詢會導致您受到速率限制，而不是更快的結果。其次，設定一個超時。一個 5 秒的 1080P 渲染不應該花費 10 分鐘，如果發生這種情況，則表示有問題，您應該重試而不是等待。
Wan 2.7 端點返回一個 task_id，並在 /api/v1/tasks/{task_id} 處公開一個輪詢端點。狀態會依序經過 PENDING（待處理）、RUNNING（運行中）、SUCCEEDED（成功）、FAILED（失敗）和 CANCELED（已取消），根據影片生成概覽的建議，輪詢間隔為 10 秒。
如何處理錯誤和重試？
Wan 2.7 錯誤分為三類。客戶端錯誤 (HTTP 4xx) 表示您的請求格式錯誤或未經授權，重試無濟於事。伺服器錯誤 (HTTP 5xx) 和超時是暫時性的。任務失敗 (status: FAILED) 可能是暫時性或永久性的，具體取決於錯誤代碼。
影片生成概覽 文件記錄了常見的錯誤代碼。我們最常看到的是：
| 代碼 | 意義 | 動作 |
|---|
| InvalidParameter.DownloadFailed | 輸入 URL 無法訪問 | 重新託管資產並重試 |
| DataInsufficient.UnsafeContent | 提示或圖像被安全過濾器標記 | 更改輸入，不要重試 |
| Throttling.RateQuota | 每金鑰 QPS 超出限制 | 指數退避 |
| InternalError.Timeout | 模型超出內部時間預算 | 重試一次 |
| AccessDenied.Arrear | 帳戶信用不足 | 充值，不要重試 |
帶有指數退避的重試包裝器：
import time
import random
def with_retry(fn, retries=4, base_delay=2.0):
for attempt in range(retries):
try:
return fn()
except requests.HTTPError as exc:
status = exc.response.status_code if exc.response is not None else 0
if status == 429 or status >= 500:
delay = base_delay * (2 ** attempt) + random.random()
time.sleep(delay)
continue
raise
except requests.ConnectionError:
delay = base_delay * (2 ** attempt) + random.random()
time.sleep(delay)
raise RuntimeError(f"All {retries} retries failed")
[原始數據] 在 2026 年 7 月追蹤的 2,000 次呼叫中，我們發現有 4.1% 的暫時性故障（HTTP 5xx、429、連線錯誤）。其中，91% 在第一次重試時成功，6% 在第二次重試時成功，3% 在第三次重試時成功。將重試次數設定為四次，然後繼續。
僅重試暫時性故障。HTTP 429 和 5xx 可以安全地使用指數退避進行重試。在 2026 年 7 月的 2,000 次呼叫樣本中，4.1% 是暫時性的，其中 91% 在第一次重試時成功（Alibaba Cloud 影片生成概覽）。
Wan 2.7 API 常見問題
Wan 2.7 端點的基礎 URL 是什麼？
Wan 2.7 影片端點位於 https://dashscope.aliyuncs.com/api/v1/services/video-generation/。任務輪詢端點是 https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}。兩者都記錄在影片生成概覽中。
有官方的 Python SDK 嗎？
Alibaba 在 PyPI 上發布了 DashScope Python SDK (dashscope)。本指南中的範例使用 requests 以便於移植。如果您偏好 SDK，等效的呼叫是 dashscope.VideoGeneration.call(model="wan2.7-t2v", ...)。
我可以取消正在進行的任務嗎？
可以。向 /api/v1/tasks/{task_id}/cancel 發送 POST 請求會將任務標記為 CANCELED。您將被收取已消耗的計算費用，因此取消屬於部分退款範圍，而非免費。
R2V 渲染需要多長時間？
在相同的解析度和持續時間下，R2V 比 T2V 和 I2V 慢。在我們的測試中，一個帶有三張參考圖片的 5 秒 1080P R2V 渲染平均需要 110 秒，而 T2V 則為 78 秒。請相應地規劃超時時間。
Wan 2.7 端點支援 webhook 嗎？
不原生支援。您必須進行輪詢。如果您需要 webhook 樣式的交付，請將輪詢迴圈包裝在一個服務中，該服務在任務完成時向您的回調 URL 發送請求。
實際操作演示
X 相關內容：OpenRouter — OpenRouter API 整合 Wan 2.7 的公告..
