如何透過API在爪式代碼中使用WaveSpeed AI模型

想像一下：你的 AI 代理不只是思考——它創造。

它逐步推理，然後無縫呼叫強大的圖像生成模型製作驚艷的視覺效果，切換到影片模型產生動態，分析結果，並繼續執行工作流程——這一切都無需你動一根手指或重寫任何一行程式碼。

這正是現在透過 WaveSpeed AI 模型與 claw-code 所能實現的——這是一位韓國開發者在 Claude Code 洩露事件 後，以 Python 從零開始以潔淨室風格重建並開源的工具。

在本指南中，你將學會如何善用這一強大組合，打造不只是聊天的代理……它們能在單一智慧迴圈中創建、迭代並輸出真實的多媒體內容。

無論你是創作者、開發者，還是厭倦了在工具之間頻繁切換的 AI 愛好者，這是你通往真正自主多媒體工作流程的捷徑。

準備好讓你的 AI 代理擁有視覺創作能力了嗎？讓我們開始吧。

前置條件：開始前的準備工作

在動任何一行設定之前，請先確認以下兩件事。跳過任何一項都會讓你花費數小時排查難以理解的錯誤訊息。

claw-code 安裝與環境設定

claw-code 需要 Python 3.11+。截至 2026 年 3 月，主分支以 Python 為主（根據專案本身的語言統計為 72.9% Rust、27.1% Python，但你日常實際使用的 CLI 入口是 Python）。從官方倉庫安裝：

git clone https://github.com/instructkr/claw-code.git
cd claw-code
pip install -e .

你還需要將 Anthropic 金鑰設定為環境變數——claw-code 同時支援 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，與 Anthropic API 官方文件 中的認證模式一致。

export ANTHROPIC_API_KEY="your-key-here"

值得一提的是：Rust 移植版本仍在獨立分支上進行中。對於影片/圖像工作流程，Python 執行環境已足夠穩定。Rust 遷移的目標是效能關鍵的執行路徑——目前這個使用情境並不需要。

API 金鑰與模型供應商存取權限

新帳戶可獲得 $1 的免費試用額度——足以測試幾次圖像生成，並在正式投入之前確認你的流程端對端可行。

截至 2026 年 3 月，WaveSpeed 的模型目錄涵蓋 700 多個模型，橫跨圖像、影片、音訊和 3D 生成，全部通過單一統一的 API 金鑰存取。當你開始建構多模型代理工作流程時，這一點極為重要——你不會想管理五個不同的認證標頭。

在 claw-code 工作流程中連接外部模型 API

這裡才是真正令人興奮的地方。claw-code 不只是一個程式碼助理——它實作了一個完整的工具執行層，包含 19 個需要權限的工具，以及可擴充的插件模型。這正是讓接入 WaveSpeed 等外部 API 變得切實可行的原因。

claw-code 如何處理外部工具呼叫

claw-code 的工具系統透過 Rust 層生成的 JSON schema 定義運作，Python 負責處理代理協調邏輯。每個工具在 permissions.py 中都有各自的存取控制定義。當你新增自訂工具時，代理可以根據任務情境自主決定何時呼叫它——這正是你希望「幫我寫一個腳本並生成對應縮圖」的提示能同時觸發文字任務和圖像生成呼叫時所需要的行為。

claw-code Anthropic API 用戶端內建的重試邏輯對 408、429 和 5xx 回應使用指數退避。這個模式正是你在 WaveSpeed 呼叫中需要複製的。

將模型 API 作為工具加入執行環境

在 claw-code 的 tools 目錄中建立一個名為 wavespeed_tool.py 的檔案：

import httpx
import os
import time

WAVESPEED_API_KEY = os.environ.get("WAVESPEED_API_KEY")
BASE_URL = "https://api.wavespeed.ai/api/v3"

TOOL_SCHEMA = {
    "name": "generate_image",
    "description": "Generate an image using WaveSpeed AI given a text prompt.",
    "input_schema": {
        "type": "object",
        "properties": {
            "prompt": {"type": "string", "description": "Image generation prompt"},
            "model": {"type": "string", "default": "wavespeed-ai/flux-dev"},
        },
        "required": ["prompt"],
    },
}

def generate_image(prompt: str, model: str = "wavespeed-ai/flux-dev") -> dict:
    headers = {"Authorization": f"Bearer {WAVESPEED_API_KEY}"}
    payload = {"inputs": {"prompt": prompt}, "enable_safety_checker": True}
    response = httpx.post(f"{BASE_URL}/{model}/run", json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

將此工具註冊到 claw-code 的工具登錄中，代理便可在任何包含圖像創建需求的會話中呼叫 generate_image。

在代理工作流程中呼叫圖像與影片生成模型

這是我最初設定時一直想找到卻找不到的部分——所以我在這裡盡可能清楚地寫出來。

REST API 呼叫模式

WaveSpeed 在所有模型中使用一致的 REST 模式。基本呼叫如下（以 WAN 2.7 文字轉影片為例）：

import httpx

def call_wavespeed(model_id: str, inputs: dict) -> dict:
    headers = {
        "Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}",
        "Content-Type": "application/json",
    }
    payload = {"inputs": inputs}
    response = httpx.post(
        f"https://api.wavespeed.ai/api/v3/{model_id}/run",
        json=payload,
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

對於圖像模型（如 Flux Dev 或 Seedream v4.5），回應會同步傳回一個輸出 URL。對於影片模型——WAN 2.7、Kling 2.6、Hailuo 2.3——則是非同步的，這意味著你需要輪詢。

處理非同步生成與輪詢

WaveSpeed 上的影片生成通常需要 30 秒到幾分鐘，取決於模型和長度。API 會立即返回一個 request_id；你需要輪詢狀態端點直到任務完成。

def poll_until_done(request_id: str, max_wait: int = 300) -> dict:
    headers = {"Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}"}
    start = time.time()
    
    while time.time() - start < max_wait:
        resp = httpx.get(
            f"https://api.wavespeed.ai/api/v3/predictions/{request_id}/status",
            headers=headers,
        )
        data = resp.json()
        status = data.get("status")
        
        if status == "completed":
            return data
        elif status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        
        time.sleep(5)  # 每 5 秒輪詢一次
    
    raise TimeoutError("Generation timed out")

在 claw-code 代理迴圈中，你需要將這個輪詢邏輯封裝在工具的執行函式中，讓代理等待結果後再繼續下一步。

在代理情境中管理速率限制與備援

代理迴圈中的速率限制比簡單腳本中更難處理——如果任務可以並行化，代理可能會快速連續觸發多個工具呼叫。以下是我正在使用的備援模式，改編自 claw-code 自身的重試邏輯：

import time

def call_with_retry(model_id: str, inputs: dict, retries: int = 3) -> dict:
    fallback_models = {
        "wavespeed-ai/wan-2.7-t2v": "wavespeed-ai/wan-2.6-t2v",
    }
    
    for attempt in range(retries):
        try:
            return call_wavespeed(model_id, inputs)
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                wait = 2 ** attempt  # 指數退避
                time.sleep(wait)
            elif e.response.status_code >= 500:
                # 若有備援模型則切換
                model_id = fallback_models.get(model_id, model_id)
                time.sleep(2)
            else:
                raise
    raise RuntimeError(f"All retries exhausted for {model_id}")

WaveSpeed API 文件 詳細說明了各帳戶等級的速率限制——Silver 帳戶（一次性儲值 $100）的並發限制明顯高於預設的 Bronze 等級，這在你開始執行每個會話觸發多個生成請求的代理時至關重要。

多模型模式：為何聚合存取在代理流程中至關重要

我想花一點時間說明為什麼這種架構值得你付出設定的心力——因為在你真正體驗過為每個想測試的模型管理獨立 API 帳戶的摩擦之前，這一點並不顯而易見。

無需重寫工作流程即可切換模型

WaveSpeed 的統一 API 意味著你只需修改一個字串，就能將 wavespeed-ai/flux-dev 換成 wavespeed-ai/seedream-v4-5。無需新的認證流程，無需解析不同的回應 schema，也無需切換 SDK。對於希望代理根據任務選擇合適模型的工作流程（寫實縮圖 vs. 風格化插圖 vs. 短影片），這genuinely有用——你可以將模型 ID 作為變數傳入，讓代理推理哪個最適合。

以下是根據 WaveSpeed 目錄 2026 年 3 月生成規格整理的簡易模型比較表：

模型	類型	輸出	最適合
Flux Dev	圖像	最高 4K	寫實風格、速度快
Seedream v4.5	圖像	最高 4K	藝術風格、風格化
WAN 2.7 T2V	影片	720p/1080p	文字轉影片、電影感
Kling 2.6 Pro	影片	720p	動作控制、動畫
Hailuo 2.3 Fast	影片	720p	速度優先的圖像轉影片

統一計費與金鑰管理

這一點讓我比預期更感驚喜。分別管理 Runway、Kling、FLUX 和 WAN 的獨立 API 金鑰——各有不同的計費儀表板、不同的速率限制行為、不同的錯誤格式——在構建代理工作流程時是一項不小的運維負擔。一個金鑰、一個計費儀表板，以及跨所有模型一致的錯誤 schema，是切實改善生活品質的進步，體現在你的代理程式碼長期保持可維護性上。

在部署任何第三方代理到生產環境之前，OWASP 軟體供應鏈安全指南 值得一讀——這在 2026 年 3 月影響 npm 版 Claude Code 安裝的供應鏈事件背景下尤為相關（claw-code 本身未受影響，但整個生態系統值得謹慎對待）。

限制與需要驗證的事項

如果我跳過這些粗糙的地方，就會遺漏這篇評測最有價值的部分。

claw-code 穩定性注意事項

截至 2026 年 4 月，claw-code 尚未達到與 Claude Code 的功能對等。Rust 移植仍在進行中。IDE 整合不存在——這是純終端機工具。多代理協調在架構文件中有記載，但尚未在規模化場景下經過實戰驗證。該專案擁有 48k+ GitHub 星星並快速發展，但「有趣的架構」和「生產就緒」是截然不同的標準。

該專案的法律狀態也尚未解決。claw-code 以潔淨室狀態作為對抗 Anthropic DMCA 施壓的理由——它是重寫版，而非洩露原始碼的複製品——但這個法律問題尚未定案。如果你正在為客戶或規模化場景構建，請將這個不確定性納入考量。

需要手動測試的項目

在將此工作流程用於生產之前，你應該手動驗證以下事項：

• 輪詢超時行為：我使用的 5 秒輪詢間隔較為保守。請用你實際使用的影片模型和長度測試，以調整 max_wait。
• 工具註冊：claw-code 的工具登錄仍在積極開發中。確切的註冊 API 可能在提交之間發生變化——在固定版本之前請查看倉庫的 CHANGELOG。
• 權限情境：claw-code 實作了需要權限的工具執行機制。確認你的 generate_image 和 generate_video 工具在 permissions.py 中被授予了正確的存取等級。
• 回應 schema 變更：WaveSpeed 偶爾會更新模型輸出 schema。在輸出 URL 欄位周圍加入驗證，而不是假設結構不變。

常見問題

Q：claw-code 能原生呼叫圖像生成 API 嗎？

預設安裝中沒有內建的 WaveSpeed 或圖像生成工具。但工具系統正是為這類擴展而設計的。一旦你以正確的 JSON schema 註冊自訂工具（如上所示），代理便可在任何會話中自主呼叫它。

Q：claw-code 支援非同步工具呼叫嗎？

Python 執行環境在代理迴圈中同步處理工具執行。對於非同步生成（如影片模型），我推薦的模式是：發出初始請求，取得 request_id，然後在工具的執行函式內部輪詢直到完成，再返回代理。這樣可以保持代理推理的線性流程，避免會話狀態中的競爭條件。

Q：這個工作流程已準備好用於生產環境嗎？

說實話？對大多數團隊而言，目前還沒有。claw-code 發展迅速但存在法律不確定性，且尚未針對生產規模的代理使用進行強化。WaveSpeed API 方面已準備好用於生產——99.99% 正常運行時間 SLA、無冷啟動、按秒計費——但封裝它的 claw-code 執行環境仍處於早期階段。我目前會將其用於內部工具、原型開發和探索，等專案穩定後再考慮用於面向客戶的生產環境。

相關文章：

• 如何設定 MaxClaw：2026 年逐步新手指南
• MaxClaw 使用案例：讓 AI 代理為你工作的 7 種方式
• 如何透過 API 使用 Seedance 2.0：非同步任務、重試與結果處理
• Seedance 2.0 在 WaveSpeed 的快速入門：10 分鐘內完成第一個影片
• Z-Image-Turbo 圖像轉圖像指南：強度參數深度解析