如何使用 Wan 2.7 API：完整開發者指南

快速解答

Wan 2.7 是 Alibaba 的多模態影片生成套件，支援文字轉影片、圖像轉影片、參考驅動生成與編輯工作流程。透過 CometAPI 上的 Wan 2.7，開發者使用模型 ID wan2.7 搭配非同步的 POST /v1/videos 端點。整合流程分三步：提交任務、輪詢回傳的影片 ID、在完成後下載 MP4。線上路由支援 720p 與 1080p 輸出並提供每秒計價，因此時長與解析度決定預估生成成本。請先從 5 秒、720p 的文字轉影片請求開始，驗證流程後，再在基本路由穩定運作的前提下加入圖像參考或提升解析度。

重要範圍：本指南涵蓋透過 CometAPI 的 Wan 2.7 影片功能。不涉及獨立的 Wan 圖像生成模型，因此如 4K 靜態圖像輸出等僅圖像規格，並非 Wan 2.7 影片的能力範疇。

Key Takeaways

• CometAPI 以類 OpenAI 的非同步影片端點暴露 Wan 2.7，而非同步聊天回應。
• 路由使用模型 ID wan2.7 與 POST /v1/videos。
• 完整整合需保留回傳的影片 ID、輪詢狀態端點、處理終止失敗，並僅在成功後下載 MP4。
• Alibaba 原生 Wan 2.7 文字轉影片 API 支援 720P 與 1080P、2–15 秒時長；CometAPI 路由採用自有的統一欄位名稱。
• 圖像轉影片、首／尾幀與延續工作流程存在於 Alibaba 原生模型家族，但透過統一路由提供的進階欄位需依線上路由文件驗證。
• 公開基準最有力的是視訊轉視訊：Wan 2.7 於 Design Arena 類別名列前茅。該結果不應泛化到所有文字轉影片或圖像轉影片任務。
• 最有用的生產指標是「每支被接受影片的成本」，而非僅「每秒價格」。

What Is Wan 2.7?

Wan 2.7 in Plain Developer Terms

Wan 2.7 不僅是提示到影片的單一檢查點。Alibaba 將其描述為涵蓋 Wan2.7-t2v、Wan2.7-i2v、Wan2.7-r2v 與 Wan2.7-videoedit 的四部分影片家族。這些變體共同覆蓋文字生成、由圖像驅動的動畫、參考導向的主體或風格控制，以及既有影片的轉換。這對應用設計很重要：簡單的行銷片可能只需文字轉影片，而角色一致性的製作管線可能需要參考輸入、錨定幀、音訊引導與反覆編輯。

在 CometAPI 上，路由刻意將供應商特定的命名壓縮為客戶模型 ID wan2.7。底層生成能力仍是 Wan 2.7，但驗證、端點路徑與參數名稱與 Alibaba Cloud 的原生 API 不同。

Wan 2.7 Technical Specifications

規格邊界：部分目錄頁描述了架構或參數數量，但 Alibaba 的官方影片 API 文件未對每個 Wan 2.7 變體公布完整的架構規格。較安全的表述是：完整參數數量與架構未被全面披露。

Wan 2.7 能做什麼？

具時間標註的多鏡位文字轉影片。

Wan 2.7 能直接解讀寫在提示中的鏡位切換。開發者可用時間範圍描述鏡位 1、鏡位 2、鏡位 3，而非依賴獨立的鏡位控制欄位。這讓提示本身成為精簡的分鏡。

首幀與尾幀控制。

原生圖像轉影片工作流程接受首幀與尾幀媒體，模型可在兩個視覺錨點間合成運動。這對產品轉場、姿勢變化與場景變形十分有用。

影片延續。

原生輸入類型 first_clip 可作為下一段影片的條件。在此流程中，duration 應依供應商任務規則解讀，因此應用不應假定它永遠只代表新生成的片段。

音訊引導的生成。

Alibaba 文件記載音訊可作為節奏與對嘴行為的驅動來源。若未上傳音訊素材，模型可自動生成匹配的背景音樂或音效。長於請求影片時長的音訊會被截斷；較短則使剩餘影片保持靜音。

提示延伸、負面提示與浮水印。

原生 API 支援提示重寫、負面提示與 AI 生成浮水印選項。這些控制可幫助團隊標準化提示品質與出處行為，但統一的 CometAPI 欄位未必一一對應。

公開基準如何評價 Wan 2.7？

影片模型沒有等同於 LLM 的 MMLU 或 SWE-bench 這類公認的單一基準。對 Wan 2.7 而言，最清晰的外部訊號是其在 Design Arena 視訊轉視訊類別名列第一。官方發布的排名圖示顯示，該快照中 Wan 2.7 的 Elo 等級為 1335。這支撐了關於影片轉換與編輯偏好的主張；但不代表在文字轉影片、圖像轉影片、音質或延遲方面皆為領先。

基準結論

• 將 Design Arena 結果用作視訊轉視訊競爭力的證據，而非對所有模式的籠統宣稱。
• 不要重用 Wan 2.1 的基準數字作為 Wan 2.7 的結果。
• 生產選型時，用相同的提示、來源素材、解析度、時長與音訊條件跨模型比較。
• 追蹤人工接受率、運動穩定性、身份保持、延遲、失敗率與每支被接受影片的成本。

為何透過 CometAPI 使用 Wan 2.7？

統一的影片 API

CometAPI 以通用的非同步影片生命週期暴露該模型。當前 Wan 2.7 模型頁公布了客戶模型 ID、路由計價與可用的建立—輪詢—下載模式。當產品需要測試或在多個影片模型間路由時，這可減少供應商特定的整合程式碼。

POST /v1/videos GET  /v1/videos/{video_id} GET  /v1/videos/{video_id}/content

CometAPI 的建立—輪詢—下載非同步影片生成生命週期。端點來源： CometAPI API documentation**.

• 一把 API 金鑰支援多個影片模型。
• 任務建立、狀態擷取與檔案下載的一致模式。
• 集中化的用量與計費可視性。
• 減少應用程式碼對單一供應商的驗證與回應結構綁定。
• 更快的 A/B 測試，因為更換模型選擇無需替換整個任務生命週期。

必要的相容性說明

路由相容性：CometAPI 的統一 /v1/videos 結構未必暴露 Alibaba Cloud 原生 T2V、I2V、R2V 與影片編輯 API 的所有欄位。基本的文字轉影片與圖像轉影片是最安全的起點。在上線首／尾幀控制、多參考輸入、音訊驅動或影片編輯前，請核對線上路由的實際欄位與媒體限制。

開始前你需要準備什麼

建立 CometAPI 帳戶與 API 金鑰

建立或登入 CometAPI 帳戶，然後產生 API 金鑰。將其儲存在環境變數中。不要將金鑰硬編碼於原始碼、瀏覽器程式或行動應用。

export COMETAPI_KEY="your_api_key"$env:COMETAPI_KEY="your_api_key"

了解模型 ID 與端點

Model ID: wan2.7 Create endpoint: POST https://api.cometapi.com/v1/videos Status endpoint: GET https://api.cometapi.com/v1/videos/{video_id} Download endpoint: GET https://api.cometapi.com/v1/videos/{video_id}/content

安裝 Python 套件

python -m pip install --upgrade requests

範例使用原生 HTTP 請求，因為 multipart 表單、狀態輪詢與二進位下載在沒有額外 SDK 抽象時更容易理解。

如何透過 CometAPI 使用 Wan 2.7 API

步驟 1：建立文字轉影片任務

以 multipart 請求傳送模型、提示、時長與尺寸。這個 5 秒、720p 的例子是驗證憑證、路由與任務建立的最低風險方式。

curl https://api.cometapi.com/v1/videos \  -H "Authorization: Bearer $COMETAPI_KEY" \  -F "model=wan2.7" \  -F "prompt=A cinematic tracking shot of a futuristic train crossing a snowy mountain valley at sunrise, smooth camera motion, realistic light." \  -F "seconds=5" \  -F "size=1280x720"The response should include a task identifier under id or task_id. Log the full response during integration because providers and route versions may wrap status data differently.{  "id": "video_task_id",  "status": "queued",  "progress": 0 }

步驟 2：輪詢影片狀態

在狀態端點中使用回傳的 ID。對於高運算量的影片任務，每 10–15 秒輪詢通常比緊密迴圈更合適。

curl https://api.cometapi.com/v1/videos/{video_id} \  -H "Authorization: Bearer $COMETAPI_KEY"{  "id": "video_task_id",  "status": "in_progress",  "progress": 45 }

你的應用應將 completed 或 success 視為成功終止狀態，並將 failed、error 或 FAILURE 視為失敗終止狀態。保留完整的失敗回傳以便診斷。

步驟 3：下載已完成的 MP4

僅在任務達到成功終止狀態後才下載。若在未完成時儲存回應，可能產生空檔案或以 MP4 副檔名儲存的錯誤文件。

curl https://api.cometapi.com/v1/videos/{video_id}/content \  -H "Authorization: Bearer $COMETAPI_KEY" \  --output wan2_7_output.mp4

步驟 4：由圖像生成影片

對於圖像轉影片，以上傳參考圖作為 multipart 表單資料，並在提示中描述運動、鏡頭行為與時間變化。統一路由常用 input_reference。請在生產前確認其當前的檔案大小、格式與圖像數量規則。

curl https://api.cometapi.com/v1/videos \  -H "Authorization: Bearer $COMETAPI_KEY" \  -F "model=wan2.7" \  -F "prompt=The camera slowly pushes forward while the subject turns toward the warm window light; preserve identity, clothing and background composition." \  -F "input_reference=@reference.png" \  -F "seconds=5" \  -F "size=1280x720"

**圖像提示技巧：**不要把大部分提示用於重述參考中已可見的靜態內容。將提示配額用於運動、鏡頭指示、時間安排、變化與限制。

步驟 5：建置完整的 Python 工作流程

以下程式會驗證 API 金鑰、提交任務、正規化包裹的狀態回應、套用最長等待、處理終止失敗，並下載完成的檔案。

import os import time from pathlib import Path​ import requests​ API_KEY = os.environ.get("COMETAPI_KEY") BASE_URL = "https://api.cometapi.com/v1" POLL_INTERVAL = 12 MAX_WAIT_SECONDS = 900​ if not API_KEY:    raise RuntimeError("Set COMETAPI_KEY before running this script.")​ headers = {"Authorization": f"Bearer {API_KEY}"}​ def parse_task_data(payload):    return payload.get("data") or payload​ # 1. Submit the generation task. submit = requests.post(    f"{BASE_URL}/videos",    headers=headers,    files={        "model": (None, "wan2.7"),        "prompt": (            None,            "A cinematic tracking shot of a futuristic train "            "crossing a snowy mountain valley at sunrise."        ),        "seconds": (None, "5"),        "size": (None, "1280x720"),    },    timeout=60, ) submit.raise_for_status() submit_payload = submit.json() video_id = submit_payload.get("id") or submit_payload.get("task_id")​ if not video_id:    raise RuntimeError(f"No video ID in response: {submit_payload}")​ print(f"Created video task: {video_id}")​ # 2. Poll until a terminal state or timeout. deadline = time.monotonic() + MAX_WAIT_SECONDS while time.monotonic() < deadline:    response = requests.get(        f"{BASE_URL}/videos/{video_id}",        headers=headers,        timeout=30,    )    response.raise_for_status()    payload = response.json()    data = parse_task_data(payload)    status = str(data.get("status", "unknown"))    progress = data.get("progress", "unknown")    print(f"status={status}, progress={progress}")​    if status in {"completed", "success"} or progress in {100, "100", "100%"}:        break    if status in {"failed", "error", "FAILURE"}:        raise RuntimeError(f"Video generation failed: {payload}")​    time.sleep(POLL_INTERVAL) else:    raise TimeoutError(f"Task {video_id} exceeded {MAX_WAIT_SECONDS}s")​ # 3. Download the completed MP4. video = requests.get(    f"{BASE_URL}/videos/{video_id}/content",    headers=headers,      timeout=180, ) video.raise_for_status()​ output = Path("output") / f"{video_id}.mp4" output.parent.mkdir(parents=True, exist_ok=True) output.write_bytes(video.content)​ if output.stat().st_size == 0:    raise RuntimeError("Downloaded file is empty.")​ print(f"Saved {output} ({output.stat().st_size} bytes)")

步驟 6：以 JavaScript 呼叫 Wan 2.7

此 Node.js 範例使用內建的 fetch 與 FormData。請使用 Node.js 18 或以上版本；範例以 node:fs/promises 寫入結果。

import { mkdir, writeFile } from "node:fs/promises";​ const apiKey = process.env.COMETAPI_KEY; const baseUrl = "https://api.cometapi.com/v1"; const pollIntervalMs = 12_000; const maxWaitMs = 15 * 60 * 1000;​ if (!apiKey) throw new Error("Set COMETAPI_KEY first.");​ const headers = { Authorization: `Bearer ${apiKey}` }; const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));​ const form = new FormData(); form.append("model", "wan2.7"); form.append(  "prompt",  "A cinematic tracking shot of a futuristic train crossing " +    "a snowy mountain valley at sunrise." ); form.append("seconds", "5"); form.append("size", "1280x720");​ const submitResponse = await fetch(`${baseUrl}/videos`, {  method: "POST",  headers,  body: form, }); if (!submitResponse.ok) throw new Error(await submitResponse.text());​ const submitPayload = await submitResponse.json(); const videoId = submitPayload.id || submitPayload.task_id; if (!videoId) throw new Error(`No video ID: ${JSON.stringify(submitPayload)}`);​ const deadline = Date.now() + maxWaitMs; while (Date.now() < deadline) {  const statusResponse = await fetch(`${baseUrl}/videos/${videoId}`, { headers });  if (!statusResponse.ok) throw new Error(await statusResponse.text());​  const payload = await statusResponse.json();  const data = payload.data || payload;  const status = String(data.status || "unknown");  const progress = data.progress ?? "unknown";  console.log({ status, progress });​  if (["completed", "success"].includes(status) || [100, "100", "100%"].includes(progress)) {    break;  }  if (["failed", "error", "FAILURE"].includes(status)) {    throw new Error(`Generation failed: ${JSON.stringify(payload)}`);  }  await sleep(pollIntervalMs); }​ if (Date.now() >= deadline) throw new Error(`Task ${videoId} timed out.`);​ const videoResponse = await fetch(`${baseUrl}/videos/${videoId}/content`, { headers }); if (!videoResponse.ok) throw new Error(await videoResponse.text());​ await mkdir("output", { recursive: true }); const outputPath = `output/${videoId}.mp4`; await writeFile(outputPath, Buffer.from(await videoResponse.arrayBuffer())); console.log(`Saved ${outputPath}`);

Wan 2.7 API 參數有哪些？

CometAPI 與 Alibaba 原生參數對照

此對照解釋了為何直接複製 Alibaba Cloud 的範例無法原封貼入 CometAPI。模型能力相關，但存取層與結構不同。

如何撰寫更佳的 Wan 2.7 提示：範例

實用的影片提示需定義哪些應保持穩定、哪些會隨時間改變。建議結構：

Subject + action + environment + camera movement + lighting + visual style + timeline + audio direction + constraints

單鏡位提示

A red vintage roadster drives along a wet coastal highway at blue hour. The camera tracks low beside the front wheel, then rises smoothly to reveal ocean cliffs. Realistic reflections, restrained motion blur, cinematic 35mm look, no text or logos.

多鏡位提示

Create a cinematic detective sequence with consistent character identity. Shot 1 [0-2s]: a rain-soaked city street at night, neon reflected in puddles. Shot 2 [2-4s]: the detective enters an old building; slow handheld follow shot. Shot 3 [4-5s]: close-up of a clue under a narrow flashlight beam. Preserve the same coat, face and lighting palette across all shots. No captions.

圖像轉影片提示

Preserve the subject's face, clothing and background layout. The subject looks up, turns slightly toward the window and takes one step forward. Slow camera push-in, warm light gradually increases, natural hair and fabric motion, no new objects.

負面提示指引

使用負面提示來抑制反覆出現的失敗模式，而非再次描述期望場景。精煉列表如 low resolution、deformed hands、duplicated limbs、flicker、unstable face、unreadable text、watermark，通常比冗長且矛盾的段落更有用。

Wan 2.7 API 成本是多少？

目前 CometAPI 路由列出 Wan 2.7 為：720p 每秒 $0.08、1080p 每秒 $0.12。因此預估成本為生成時長與所選解析度的直接函數。

Estimated video cost = price per second x generated duration in seconds

資料來源：CometAPI live model pricing**.

定價解讀：不要在未比較相同區域、模型變體、解析度、時長、音訊模式與計費單位的情況下，宣稱聚合路由比 Alibaba Cloud 更便宜。CometAPI 清楚的每秒價格與統一計費是整合優勢；供應商價格優勢需在同等基礎上比較。

一支 1080p 的影片若未通過創意審核，實際成本將高於標示的生成價格，因為團隊必須重生。生產規劃時，請以總花費除以無需重作即可接受的影片數量來衡量。

Wan 2.7 vs Seedance 2.5 vs Vidu Q3 vs Veo 3.1

同平台上最有用的替代方案包括 Seedance 2.5、Vidu Q3 與 Veo 3.1。下表比較工作流程適配，而非宣告通用贏家。路由功能可能變動，故在生產前請驗證進階輸入。

比較結論

• 當首／尾幀控制、延續、音訊引導與廣泛可控的工作流程比單支片長更重要時，選擇 Wan 2.7。
• 當較長的多鏡位敘事與重參考創作為優先時，選擇 Seedance 2.5。
• 當快速敘事迭代、同步音訊與創作者導向的工作流程居中時，選擇 Vidu Q3。
• 當電影級品質、視覺寫實與整合音訊值得更高路由成本時，選擇 Veo 3.1。
• 不要僅從規格選出贏家。使用固定的提示與素材組進行比較，選擇能產生最低「每支被接受影片」成本的路由。

生產最佳實務

任務生命週期與可靠性

• 任務建立後立即持久化任務 ID。
• 在應用內採用冪等策略，使客戶端重試不會建立重複付費任務。
• 以 10–15 秒輪詢與最長等待，取代無界迴圈。
• 區分暫時性 HTTP 失敗與供應商宣告的生成失敗。
• 對網路或流量限制錯誤使用指數退避，但勿盲目重試內容政策失敗。
• 僅在輸出已下載且驗證非空後，將工作標記為完成。
• 不要永久依賴供應商臨時 URL；在允許情況下，將被接受的輸出複製到你自控的儲存中。

品質與成本控制

• 先以 720p 與短時長原型，再生成 1080p 母檔。
• 將提示、負面提示、模型 ID、路由、解析度、時長、任務 ID 與輸出雜湊一併保存，以便可重現。
• 建立審查規則，涵蓋提示符合度、運動、時間一致性、身份、手部、文字偽影、音訊與安全。
• 衡量每支被接受輸出的成本，而非僅每次請求成本。
• 維護小型回歸提示集，在切換路由版本或供應商前重跑。

安全與治理

• 將 API 金鑰留在伺服器端，疑似外洩時旋轉金鑰。
• 在轉送到生成路由前驗證上傳的圖像與影片。
• 對參考媒體施行同意、肖像與智慧財產控制。
• 對廣告、新聞、政治、醫療或其他高影響用途加入人工審查。
• 保留出處中繼資料並依法規與平台要求套用浮水印或揭露政策。

常見錯誤與疑難排解

最終建議

Wan 2.7 的實用價值在於其可控的廣泛影片工作流程：文字轉影片、圖像動畫、錨定幀、延續、參考驅動生成與音訊感知行為。透過 CometAPI，最快的路徑是以統一的非同步端點先驗證 5 秒、720p 的請求；待任務建立、輪詢與下載可靠後，再加入圖像輸入與 1080p 輸出。

在生產中，將進階原生功能置於明確的能力檢查之後，因為 CometAPI 的統一結構未必暴露 Alibaba 的全部欄位。以相同的提示與素材比較 Wan 2.7 與替代方案，選擇能以最低每支被核准影片成本產出的路由，而非最低標價。

FAQs

什麼是 Wan 2.7 API？

這是一個可透過 API 存取的多模態影片生成家族，涵蓋文字轉影片、圖像轉影片、參考驅動工作流程與影片編輯。CometAPI 透過模型 ID wan2.7 暴露客戶路由。

Wan 2.7 在 CometAPI 上的模型 ID 是什麼？

使用 wan2.7。除非直接呼叫 Alibaba Cloud，否則不要以 Alibaba 原生識別碼（如 wan2.7-t2v）取代。

哪個端點用來建立 Wan 2.7 影片？

將 multipart POST 請求送至 https://api.cometapi.com/v1/videos。之後查詢 /v1/videos/{video_id}，並從 /v1/videos/{video_id}/content 下載。

Wan 2.7 是否支援文字轉影片與圖像轉影片？

是。兩者皆為列示能力。圖像轉影片需加入參考圖，並應遵循路由當前的 multipart 欄位要求。

Wan 2.7 支援哪些解析度？

已發布的 Wan 2.7 影片路由支援 720p 與 1080p。原生文字轉影片文件亦列出了兩個層級在各長寬比下的輸出尺寸。

Wan 2.7 的影片最長可以多長？

Alibaba 原生 Wan 2.7 文字轉影片 API 允許 2 到 15 秒的整數時長，預設為 5 秒。請依你所呼叫的 CometAPI 路由文件使用對應數值。

Wan 2.7 會生成音訊嗎？

Alibaba 文件記載音訊引導與在缺少音訊資產時自動匹配的背景音樂或音效。統一路由實際暴露的音訊欄位請在上線前驗證。

Wan 2.7 能使用首幀與尾幀嗎？

原生圖像轉影片家族支援首幀與首＋尾幀工作流程。請在 CometAPI 上確認對應的統一路由欄位後再依賴。

Wan 2.7 API 是同步還是非同步？

非同步。任務建立會回傳 ID；你的應用需輪詢狀態並在完成後下載結果。

Wan 2.7 在 CometAPI 上的價格是多少？

已發布路由為 720p 每秒 $0.08、1080p 每秒 $0.12。5 秒影片分別約為 $0.40 或 $0.60。

我應該選擇 Wan 2.7、Seedance 2.5、Vidu Q3 還是 Veo 3.1？

當你需要廣泛的可控性時選 Wan 2.7；較長、重參考的敘事選 Seedance 2.5；快速敘事迭代、同步音訊選 Vidu Q3；追求高端電影質感選 Veo 3.1。請以受控的 A/B 測試驗證選擇。

Wan 2.7 能延續既有影片嗎？

在原生模型家族中可以，透過 first_clip 工作流程。其在 CometAPI 統一路由上的可用性與參數對應需另行確認。