API経由でWaveSpeed AIモデルとclaw-codeを使う方法

想像してみてください。あなたのAIエージェントは、考えるだけでなく — 創造するのです。

ステップバイステップで推論し、強力な画像生成モデルをシームレスに呼び出して印象的なビジュアルを生成し、動画モデルに切り替えてモーションを追加し、結果を分析して、ワークフローを継続する — すべて、あなたが指一本動かすことも、コードを一行書き直すこともなく。

これがまさに今、WaveSpeed AI モデルと claw-code で可能になったことです。claw-codeはPythonでクリーンルームスタイルでゼロから再構築され、Claude Codeのリーク直後に韓国の開発者によってオープンソース化されました。

このガイドでは、このパワフルな組み合わせを活用して、単にチャットするだけでなく… 創造し、反復し、成果を届けるエージェントを構築する方法を探ります。単一のインテリジェントループの中で、リアルなマルチメディア出力を実現します。

クリエイター、開発者、またはツールを切り替えることに疲れたAI愛好家の方にとって、これは真にエージェント的なマルチメディアワークフローへの近道です。

AIエージェントを視覚的にパワフルにする準備はできていますか？さっそく始めましょう。

前提条件：始める前に必要なもの

設定ファイルに触れる前に、この2つを準備しておきましょう。どちらかを省略すると、不可解なエラーメッセージに何時間も費やすことになります。

claw-codeのセットアップと環境

claw-codeはPython 3.11+で動作します。2026年3月時点で、mainブランチは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キーをEnvironment変数として設定する必要もあります — 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のモデルカタログは、画像、動画、音声、3D生成にわたる700以上のモデルをカバーしており、すべてが単一の統一されたAPIキーの背後にあります。マルチモデルエージェントワークフローの構築を始めると、これが非常に重要になります — 5つの異なる認証ヘッダーを管理したくないですよね。

claw-codeワークフローで外部モデルAPIを接続する

ここが本当に面白くなるところです。claw-codeは単なるコーディングアシスタントではありません — 19の権限ゲート付きツールと拡張可能なプラグインモデルを持つ完全なツール実行レイヤーを実装しています。これこそが、WaveSpeedのような外部APIの組み込みを実際に実現可能にしているものです。

claw-codeが外部ツール呼び出しを処理する方法

claw-codeのツールシステムは、Rustレイヤーで生成されたJSONスキーマ定義を通じて動作し、Pythonがエージェントオーケストレーション側を処理します。各ツールはpermissions.pyで定義された独自のアクセス制御を持っています。カスタムツールを追加すると、エージェントはタスクコンテキストに基づいて自律的にいつ呼び出すかを決定できます — これは、「スクリプトを書いてマッチするサムネイルを生成して」というプロンプトがテキストタスクと画像生成呼び出しの両方をトリガーすべき場合に、まさに望ましい動作です。

claw-codeのAnthropic APIクライアントに組み込まれたリトライロジックは、408、429、5xxレスポンスに対して指数バックオフを使用します。このバックオフの考え方はWaveSpeedの結果ポーリングにのみ使います。タスク送信リクエストは1回だけ送信し、自動で再試行することはありません（後述）。

ハーネスへのモデルAPIのツールとしての追加

claw-codeのツールディレクトリに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}", 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}",
        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を返し、ジョブが完了するまでステータスエンドポイントをポーリングします。

import os
import time
import httpx

TRANSIENT = {429, 500, 502, 503, 504}


def poll_until_done(request_id: str) -> dict:
    headers = {"Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}"}
    url = f"https://api.wavespeed.ai/api/v3/predictions/{request_id}/result"
    failures = 0

    while True:
        try:
            resp = httpx.get(url, headers=headers, timeout=30)
        except httpx.TransportError:  # network error or per-request timeout
            resp = None

        if resp is None or resp.status_code in TRANSIENT:
            failures += 1
            retry_after = resp.headers.get("Retry-After", "") if resp is not None else ""
            time.sleep(int(retry_after) if retry_after.isdigit() else min(2 ** failures, 60))
            continue
        if resp.status_code != 200:
            raise RuntimeError(f"Task {request_id}: unexpected HTTP {resp.status_code}")
        failures = 0

        data = resp.json()["data"]
        status = data.get("status")
        if status == "completed":
            return data
        if status in {"failed", "cancelled", "timeout", "deleted"}:
            raise RuntimeError(f"Task {request_id} {status}: {data.get('error')}")

        time.sleep(2)  # poll every 2 seconds

claw-codeエージェントループ内では、このポーリングをツールのexecute関数でラップして、エージェントが次のステップに進む前に結果を待つようにします。

エージェント的コンテキストでのレート制限とフォールバックの管理

エージェントループ内のレート制限は、シンプルなスクリプトよりも厄介です — タスクが並列化可能な場合、エージェントは複数のツール呼び出しを素早く連続して発火させる可能性があります。私が使用しているパターンはこちらです。送信は1回だけ行い、再試行するのはポーリングのリクエストのみ、フォールバックモデルは送信が明確に拒否された場合にのみ使います：

import httpx

FALLBACK_MODELS = {
    "wavespeed-ai/wan-2.7-t2v": "wavespeed-ai/wan-2.6-t2v",
}


def submit_once(model_id: str, inputs: dict) -> str:
    """Send the submit POST exactly once and return the task id."""
    try:
        return call_wavespeed(model_id, inputs)["data"]["id"]
    except httpx.HTTPStatusError as e:
        if e.response.status_code < 500:
            raise  # 4xx: the request was rejected, no task was created
        unknown = e
    except httpx.HTTPError as e:  # timeout, dropped connection, no response
        unknown = e
    raise RuntimeError(
        f"Submit to {model_id} has an unknown outcome ({unknown!r}). A task may "
        "exist and be billed: check History in the WaveSpeed dashboard before resubmitting."
    ) from unknown


def generate(model_id: str, inputs: dict) -> dict:
    try:
        task_id = submit_once(model_id, inputs)
    except httpx.HTTPStatusError as e:
        fallback = FALLBACK_MODELS.get(model_id)
        # Only a 429 is a clear "not accepted" signal; try the fallback once.
        if e.response.status_code != 429 or fallback is None:
            raise
        task_id = submit_once(fallback, inputs)
    return poll_until_done(task_id)

重要なルール：タスク送信のPOSTは自動で再試行しないでください。5xxエラーやタイムアウトで失敗した場合、タスクが作成（および課金）されたかどうか分からないため、再送信する前にWaveSpeedダッシュボードの履歴（History）を確認してください。429のような明確な拒否だけは、タスクが作成されていないため安全に対処できます。ポーリングのGETリクエストは繰り返しても安全です。一時的なエラーを許容し、タスクが終了ステータスに達するまで続けます。

WaveSpeed APIドキュメントにはアカウントレベル別のレート制限ティアが記載されています — Silverアカウント（一回限りの$100チャージ）はデフォルトのBronzeティアよりもかなり高い同時実行制限を持っており、セッションごとに複数の生成リクエストを発火するエージェントを実行し始めると重要になります。

マルチモデルパターン：エージェント的パイプラインで統合アクセスが重要な理由

このアーキテクチャがセットアップの手間に値する理由について少し触れたいと思います — テストしたいすべてのモデルに対して個別のAPIアカウントを管理するという摩擦を実際に経験するまで、その価値は明らかではないからです。

ワークフローの書き直しなしでモデルを切り替える

WaveSpeedの統一APIにより、wavespeed-ai/flux-devをwavespeed-ai/seedream-v4-5に文字列一つの変更で交換できます。新しい認証フロー、解析すべき異なるレスポンススキーマ、SDKの切り替えは必要ありません。エージェントにタスクに適したモデルを選択させたいエージェント的ワークフロー（フォトリアリスティックなサムネイルvsスタイライズされたイラストvsショートビデオクリップ）にとって、これは本当に有用です — モデル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	スピード最適化I2V

統一された課金とキー管理

これは予想以上に驚かされたポイントです。Runway、Kling、FLUX、WANそれぞれの個別APIキーを管理する — それぞれ異なる課金ダッシュボード、異なるレート制限の挙動、異なるエラーフォーマット — は、エージェント的ワークフローを構築する際に意味のある運用上の負担です。1つのキー、1つの課金ダッシュボード、すべてのモデルにわたる一貫したエラースキーマは、エージェントコードが時間をかけてどれだけ保守可能であり続けるかという点で、本物の生活品質の向上です。

本番環境でサードパーティエージェントをデプロイする前に、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で正しいアクセスレベルを付与されていることを確認してください。
• レスポンススキーマの変更：WaveSpeedはモデル出力スキーマを時々更新します。構造を前提とせず、出力URLフィールドの周りにバリデーションを追加してください。

よくある質問

Q: claw-codeはネイティブに画像生成APIを呼び出せますか？

デフォルトのインストールにはWaveSpeedや画像生成ツールは組み込まれていません。しかし、ツールシステムはまさにこの種の拡張のために設計されています。正しいJSONスキーマでカスタムツールを登録すれば（上記参照）、エージェントはどんなセッションでも自律的にそれを呼び出せます。

Q: claw-codeは非同期ツール呼び出しをサポートしていますか？

Pythonハーネスはエージェントループ内でツール実行を同期的に処理します。非同期生成（動画モデルなど）の場合、私が推奨するパターンは：最初のリクエストを発火してrequest_idを取得し、ツールのexecute関数内でエージェントに返す前に完了するまでポーリングすることです。これにより、エージェントの推論がリニアに保たれ、セッション状態での競合状態を回避できます。

Q: このワークフローは本番対応ですか？

正直に言うと？ほとんどのチームにとって、まだそうではありません。claw-codeは急速に進歩していますが、法的な不確実性を抱えており、本番スケールのエージェント的使用に向けて硬化されていません。WaveSpeed API側は本番対応です — 99.99%のアップタイムSLA、コールドスタートなし、秒単位の課金 — しかし、それをラップするclaw-codeハーネスはまだ初期段階です。今は内部ツール、プロトタイピング、探索にこれを使い、プロジェクトが安定してからクライアント向けの本番環境に再検討することをお勧めします。

関連記事：

• MaxClawのセットアップ方法：ステップバイステップ初心者ガイド（2026年）
• MaxClawのユースケース：AIエージェントを活用する7つの方法
• API経由でSeedance 2.0を使う方法：非同期ジョブ、リトライ、結果処理
• WaveSpeedでSeedance 2.0をクイックスタート：10分で最初の動画を作成
• Z-Image-Turbo画像対画像ガイド：強度パラメーター詳細解説