Wan API 文件Wan API 整合指南
使用 API 金鑰生成 Wan 影片，送出與輪詢任務、下載結果，並處理計費與失敗情況。
連接 Wan API
使用 https://api.wanapi.app 作為 API 基底 URL。在 API 金鑰設定建立金鑰，並以 Authorization: Bearer YOUR_API_KEY 傳送。請將金鑰保存在伺服器端。Playground 使用您的網站登入工作階段，費用從同一帳號的餘額扣除，不需要將金鑰貼入瀏覽器。
使用服務需要已啟用且餘額充足的帳號。目前費率請見價格頁。各款模型都有獨立端點與模型頁面。
GET /v1/models 會列出您的金鑰可使用的模型。選擇較高解析度不會自動切換模型。
| 模型 | URL 中的模型 ID | 解析度值 |
|---|---|---|
| Wan 3.0 | wan3.0-video | 480p, 720p, 1080p |
| Wan 3.0 Prime | wan3.0-video-prime | 480p, 720p, 1080p |
| Wan 3.0 Pro | w3.0-video-pro | 1080p, 2k, 4k |
| Wan 3.0 Prime Pro | w3.0-video-prime-pro | 1080p, 2k, 4k |
請求欄位
四款模型共用以下 14 個原生欄位。請提供提示詞或至少一項媒體輸入。影格輸入不能與參考輸入、file 或 link 併用；file 與 link 也不能同時使用。
| 欄位 | 型別 | 規範 |
|---|---|---|
prompt | string | 最多 20,000 個字元。 |
first_frame | string | 圖片 HTTP(S) URL、圖片 data URI 或 Base64。 |
last_frame | string | 圖片 HTTP(S) URL、圖片 data URI 或 Base64。 |
reference_images | string[] | 最多 10 張圖片，可使用與影格相同的輸入形式。 |
reference_videos | string[] | 最多 5 個公開的 MP4/MOV URL；每支影片長度為 1–15 秒，參考影片總長度最多 15 秒。 |
reference_audios | string[] | 最多 5 個音訊 HTTP(S) URL。 |
file | string | 公開的文件 URL。 |
link | string | 公開的網頁 URL。 |
resolution | string | 請見模型表格。預設值：1080p。 |
ratio | string | adaptive, 16:9, 4:3, 1:1, 3:4, 9:16。預設值：adaptive。 |
duration | integer | 輸出長度為 2–30 秒，或使用 -1 自動決定長度。預設值：5。 |
audio | boolean | 生成音訊。預設值：true。停用音訊不會降低費率。 |
seed | integer | 0–2147483647。省略時採隨機生成。 |
prompt_extend | boolean | 擴充提示詞。預設值：true。 |
請使用穩定、可直接存取的媒體 URL，並確保任務完成前都能存取。影片時長檢查會透過 HTTP Range 請求讀取有限範圍的資料；影片伺服器必須支援這類讀取，並提供可讀取的 MP4/MOV 時長中繼資料。時長檢查不會跟隨重新導向，也不支援私人網路 URL。參考影片與輸出影片的合計長度不得超過 30 秒。Playground 接受的 JSON 請求主體上限為 32 MiB；較大的輸入請改用 URL。
輪詢並下載影片
各款模型的提交端點都會回傳對外使用的任務 ID。請先儲存此 ID，再進行其他操作。
{
"task_info": {
"id": "task_EXAMPLE",
"status": "pending"
}
}請使用對應模型章節中的查詢範例。建議先以 5 秒為間隔查詢，遇到暫時性錯誤後再延長間隔。請一併儲存每個任務的模型 ID 與任務 ID，勿透過其他模型的端點查詢。
原生狀態為 pending、processing、completed 與 failed。完成後的回應包含 videos 陣列，其中提供完整的 Bunny CDN 簽名 URL。
{
"task_info": { "id": "task_EXAMPLE", "status": "completed" },
"videos": ["https://reapiflexible.b-cdn.net/flexible/v1/expires/2026-11/20261113T06/wanapi-task_EXAMPLE/video.mp4?token=HS256_SIGNATURE&expires=1794550071"]
}可直接使用回傳的 URL 播放或下載，存取該 URL 不需要 API 金鑰或 Authorization 標頭。檔案沿用儲存空間既有的保留政策。重新查詢任務不會重新生成影片、再次扣款或延長檔案保存期限。需要長期保存的檔案，請另存至自己的儲存空間。查詢任務仍須使用 API 金鑰，且只能取得自己帳號的任務。
同步與背景 Responses
使用 Responses API 的用戶端，可透過 POST /v1/responses 傳入模型 ID、字串型別的 input，以及相同的原生生成欄位。請以 input 取代 prompt。reference_images 等原生媒體欄位仍放在頂層。
{
"model": "wan3.0-video",
"input": "A blue ball rolls across a white table.",
"resolution": "480p",
"duration": 2,
"background": true
}設定 background: true 時，請儲存回應 ID，並輪詢 GET /v1/responses/{response_id}。未設定 background 時，HTTP 請求會等待生成完成。stream: true 會在等待期間使用伺服器發送事件（SSE）。最終助理輸出包含簽章影片 URL；持有此連結即可存取影片，請視為私密連結，避免意外公開。生成時間較長，或代理伺服器的逾時限制較嚴格時，建議使用原生任務提交或背景 Responses。
同步請求中斷或逾時不會取消生成，任務仍保留在伺服器上。請勿自動再次送出相同的生成請求。
計費與失敗處理
費用為模型對應解析度的費率乘以計費秒數。參考影片與輸出影片的秒數均計入；文字、圖片與音訊輸入不會增加影片計費秒數。未使用參考影片的固定長度請求，會依要求的輸出長度預留款項。自動長度或含參考影片的請求，會預留最多 30 個計費秒數的款項，再依實測用量結算並返還未使用的部分。生成失敗時會解除款項預留。輪詢不會建立另一個生成任務，也不會再次收費。
- **參數無效：**修正請求後再重新送出。不明的原生欄位會遭拒絕。
- **餘額不足：**請先儲值，再送出新的付費請求。金鑰的額度上限不代表帳號已有可用餘額。
- **速率限制或暫時性輪詢失敗：**僅重試查詢，逐步延長間隔，並設定最長等待時間。
- **提交逾時、網路中斷或未取得任務 ID：**提交結果可能不明。請勿自動重複 POST，否則可能建立第二個付費任務。
- **任務失敗：**請區分顯示任務失敗與無法查詢狀態。
- **下載失敗：**先重試下載已完成任務的結果，再考慮建立另一個生成任務。
生成請求不會自動重試，也不會自動切換至其他模型。目前未公布取消任務、webhook 或冪等鍵的介面規範。若提交結果不明而需要調查，請保留任務 ID 並聯絡支援團隊。