WAN 2.5 API 快速入門指南：身份驗證、參數和範例請求
嘿，我是Dora。本來我這週沒計畫試試WaveSpeed上的WAN 2.5 API。一個小煩惱把我推到了那裡：我需要為草稿製作一些一致的圖像變體，而我常用的工具要麼操作太繁瑣，要麼聰明得過了頭。我想要一些無聊又可靠的東西，可以編寫腳本、有版本控制、容易回滾。
所以我打開文檔，泡了杯茶，寫了一個小腳本。這是我沿途記下的東西，在2026年1月測試過，沒有任何修飾。它更多是關於那些讓工作變得輕鬆的部分，而不是”功能”。
API概觀
如果你接觸過任何現代AI API，WaveSpeed對WAN 2.5的處理會讓你感到熟悉。HTTP輸入，JSON輸出。你發送一個提示詞（有時還有圖像），它要麼返回完成的產物，要麼返回一個你可以輪詢的任務ID。
在寫任何代碼之前，我關注了幾個基本細節：
- 版本控制： WAN 2.5被公開為不同的版本，這對可重複性很重要。我堅持在URL中使用明確的版本路徑，而不是”最新”別名。這個小選擇能防止未來我遭遇無聲的行為變化。
- 模式： 某些工作流是同步的（小、快），其他的則作為任務運行。如果你在做高解析度生成或批處理工作，預計會有帶狀態端點或webhooks的非同步流程。
- 格式： JSON回應通常包括狀態、資源URL或base64負載，以及一些元數據（種子、步數、計時）。我保留元數據，當你想稍後重現某個外觀時很方便。
- 限制： 圖像大小、步數和並發性有上限。預設值足以應對草稿，但一旦我試圖提高解析度就碰到了天花板。下面會詳談速率限制。
簡單來說：如果你習慣REST，這是一條直路。竅門是把少數無聊的部分（密鑰、參數、重試）搞對，這樣你就可以忘掉它們。
這種簡單性是我們建立WaveSpeed方式的一部分。我希望WAN 2.5（和其他模型）感覺起來是可編寫腳本的、有版本控制的，以及最好的方式無聊。如果你自己連接這個，你可以在這裡探索它。
認證和密鑰
我在儀錶板中生成了一個WaveSpeed API密鑰，並把它放入環境變數。沒什麼花哨的，但它讓我不用在檔案間追逐秘密。
- 從WaveSpeed上你的帳戶設定中取得密鑰。它與你的組織/項目綁定。
- 將其在本地存儲為環境變數：
WAVESPEED_API_KEY。我在開發中使用.env檔案，在運行時使用CI的秘密儲存。 - 在頭部使用Bearer認證：
Authorization: Bearer $WAVESPEED_API_KEY。 - 如果你輪換密鑰，在低流量時段進行。我以安靜的方式學到了這一點，當一個定時輪換中斷了一個長任務時。
如果你的團隊需要作用域密鑰，請檢查儀錶板設定。對於綁定到自動化的任何東西，我更傾向於最小權限路線。一個小摩擦：如果你從多台機器運行，請按主機或服務清楚地標記密鑰，在你稍後審計使用情況時有幫助。
必需參數
確切的名稱因端點而異，但這是我在WaveSpeed上用於Wan 2.5的最小形式。把這些作為骨架，在官方文檔中確認你帳戶的欄位名稱。
- model：我明確地將其設定為
wan-2.5（或你計畫中最接近的確切字符串）。它在更新中保持行為穩定。 - input：提示詞字符串。我保持簡短而具體。WAN傾向於對清晰、簡單的措辭回應得更好，而不是形容詞堆砌。
- mode或task：圖像生成與變體/升級。如果你傳遞原始圖像，這很重要。
- output：我預設要求圖像URL。Base64就在那裡，但URL對內存更友好。
當我忘記明確設定模型時，我得到了一個合理的預設，但我的結果在運行中微妙地轉移。不是錯，只是不可重複。鎖定版本移除了那個搖晃。
可選參數
這是真正控制所在的地方。第一天我只接觸了少數幾個。
- seed：一旦我喜歡某個外觀，我就打開它。它為變體穩定了氛圍。
- steps：更高的步數可以以時間和積分成本為代價推動細節。我以小增量（例如，24 → 32）增加並觀察回報。
- guidance或cfg_scale：收緊對提示詞的遵守。太高會變得脆弱。
- size或resolution：這是成本跳躍的地方。我以小的草稿開始，然後在目標大小下重新運行最終版本。
- image：對於變體，傳遞原始圖像URL或上傳。如果支持，與strength參數配對。
- safety或moderation flags：除非你的工作流真的需要自訂處理，否則保持開啟。
- user或metadata：我添加了請求ID或項目標籤，以便稍後在日誌中追踪運行。
微小觀察：一次改變兩個旋鈕使其難以判斷什麼有幫助。我每次運行改變一件事並在註釋中保留筆記。老派，但有效。
樣本請求模式
我試了三種簡單形式：快速curl、一個小Python腳本和非同步背景任務。
同步草稿（curl）
這足以在連接其他任何東西之前sanity check我的密鑰和提示詞。
示例端點，在文檔中確認你帳戶和地區的確切路徑：
POST https://api.wavespeed.ai/wan/v2.5/generations
頭部：
- Authorization: Bearer $WAVESPEED_API_KEY
- Content-Type: application/json
主體（最小）：
{
"model": "wan-2.5",
"input": "quiet studio light, sketch on kraft paper",
"output": { "format": "url" }
}我關注的內容：
- 200加上結果和元數據 → 你沒問題。
- 202加上任務id → 切換到非同步流程。
- 4xx → 負載或認證中的某些東西不對。
小Python助手
我寫了一個小函數來處理頭部、超時和json。它要麼返回URL，要麼拋出乾淨的異常。沒什麼神奇的，只是那種你不會想兩次的包裝器。
實用位：
- 設定短連接超時和稍長的讀取超時。
- 使用重試和抖動處理429。
- 為每次運行記錄種子、步數和大小。
非同步流程（任務）
對於較大的圖像或批次，我得到了202和任務id。迴圈很簡單：
- POST任務，
- 每幾秒輪詢GET
/jobs/{id}， - 在終端狀態（成功/失敗）時停止，
- 獲取資源URL。
如果你的堆棧喜歡webhooks，WaveSpeed也公開了回調。我首先堅持輪詢，在設置期間少了一個移動部分。
錯誤代碼
我在編輯器旁邊保留了一張小地圖。它比我預期的快得多。
- 400 Bad Request：通常是欄位名稱或類型不匹配。我曾將大小作為字符串而不是對象發送。一旦我放慢速度並閱讀消息，修複就很明顯了。
- 401 Unauthorized：密鑰遺漏或格式錯誤。檢查你的Bearer頭部和尾隨空格。
- 403 Forbidden：密鑰存在但缺乏端點或模型層的作用域。
- 404 Not Found：錯誤的端點路徑或已過期的任務id。
- 409 Conflict：當更新已經結算的任務時，你有時會看到這個。再次輪詢，不要繼續推進。
- 429 Too Many Requests：你超過了每分鐘或每組織限制。使用指數重試退避。
- 500/503 Server Errors：在我的測試中很罕見，但為它們計畫。一個短重試迴圈讓我的腳本保持冷靜。
幫助的小習慣：我將錯誤代碼和請求id（如果存在）冒泡進我的日誌。當出現奇怪的事情時，支援可以使用該id來追踪它。
速率限制
一旦我在並發方面變得懶惰，我就碰到了速率限制。容易做到，更容易避免。
什麼有效：
- 尊重頭部：許多端點返回速率頭部（例如，剩餘、重置時間）。頭部名稱可能不同，檢查文檔，但它們值得閱讀。
- 使用令牌桶或簡單隊列。我限制我的腳本為小的、穩定的滴漏，而不是突發。系統呼吸得更輕鬆，我也是。
- 將草稿與最終版本分開。草稿可以以小而快的方式運行：最終版本可以在背景中逐個運行。
- 快取重複。如果你在測試提示詞，為幾分鐘保留先前的結果，這樣你就不會燃燒相同的調用。
我也建立了一個非常簡單的退避：1秒的基本延遲，每次429時翻倍，上限為30秒，最多4次重試。它感覺不匆忙，避免了對服務的狗樁。
成本護欄
這是我主要的擔憂。圖像工作可以在你泡茶時在背景中蠶食積分。
我在第一天設定的幾項保護：
- 儀錶板中的預算上限： 我設定了月度上限和電子郵件提醒，低於它一點。如果你的團隊共享密鑰，提醒可以幫助你儘早捕捉迴圈。
- 每請求上限： 我強制大小和步數在最大值下生活，除非我傳遞覆蓋標誌。它救了我免於”哎呀，4K一切”。
- 草稿優先工作流： 我運行小預覽（較低解析度、較少步數），只升級保留者。這在第一個下午將我的支出減少了一半以上。
- 種子紀律： 一旦我找到了我喜歡的方向，我固定了種子，一次改變一個參數。較少的盲目運行：更有意圖的運行。
- 帶成本的日誌：如果回應包括信用或使用欄位（某些端點確實如此），儲存它。當它不包括時，根據解析度和步數進行估計，並註明它是估計。
我也在我的腳本中放了一個軟殺開關：如果當天的使用超過了閾值，新任務暫停並在Slack中發布消息。它不優雅，但它對約束很誠實。
這起初沒有節省時間。它節省了注意力。幾次運行後，護欄消退到背景，我可以再次思考工作，而不是儀表。
