Comment utiliser claw-code avec les modèles WaveSpeed AI via l'API

Imaginez ceci : votre agent IA ne se contente pas de réfléchir — il crée.

Il raisonne étape par étape, puis appelle de manière transparente un puissant modèle de génération d’images pour produire un visuel époustouflant, passe à un modèle vidéo pour le mouvement, analyse les résultats et poursuit le workflow — tout cela sans que vous ayez à lever le petit doigt ni à réécrire une seule ligne de code.

C’est exactement ce qui est désormais possible avec les modèles WaveSpeed AI et claw-code — reconstruit de zéro en Python dans un style chambre blanche, et rendu open-source par un développeur coréen juste après la fuite de Claude Code.

Dans ce guide, vous découvrirez comment exploiter cette puissante combinaison pour construire des agents qui ne se contentent pas de discuter… ils créent, itèrent et livrent de véritables sorties multimédias au sein d’une seule boucle intelligente.

Que vous soyez créateur, développeur ou bidouilleur d’IA fatigué de jongler entre les outils, voici votre raccourci vers de véritables workflows multimédias agentiques.

Prêt à rendre vos agents IA visuellement puissants ? Plongeons-y.

Prérequis : Ce Dont Vous Avez Besoin Avant de Commencer

Avant de toucher à la moindre ligne de configuration, réglez ces deux points. Ignorer l’un ou l’autre vous coûtera des heures de messages d’erreur cryptiques.

Configuration de claw-code et Environnement

claw-code fonctionne sur Python 3.11+. En mars 2026, la branche principale est Python-first (72,9% Rust, 27,1% Python selon la répartition linguistique du projet, mais l’entrée CLI que vous utiliserez quotidiennement est Python). Installez-le depuis le dépôt officiel :

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

Vous voudrez également définir votre clé Anthropic comme variable d’environnement — claw-code prend en charge à la fois ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN, correspondant aux modèles d’authentification de l’API Anthropic de leur documentation officielle.

export ANTHROPIC_API_KEY="votre-clé-ici"

Un point à signaler : le portage Rust est encore en cours sur une branche séparée. Pour les workflows vidéo/image, le harnais Python est suffisamment stable. La migration Rust vise les chemins d’exécution critiques pour les performances — ce n’est pas quelque chose dont vous avez besoin pour ce cas d’usage en ce moment.

Clé API et Accès au Fournisseur de Modèles

Les nouveaux comptes reçoivent 1 $ en crédits d’essai gratuits — suffisant pour tester quelques générations d’images et confirmer que votre pipeline fonctionne de bout en bout avant de dépenser quoi que ce soit.

Le catalogue de modèles de WaveSpeed en mars 2026 couvre plus de 700 modèles dans les domaines de la génération d’images, vidéos, audio et 3D, tous accessibles via une seule clé API unifiée. Cela compte beaucoup une fois que vous commencez à construire des workflows d’agents multi-modèles — vous ne voulez pas gérer cinq en-têtes d’authentification différents.

Connexion d’APIs de Modèles Externes dans un Workflow claw-code

C’est là que les choses deviennent véritablement intéressantes. claw-code n’est pas seulement un assistant de codage — il implémente une couche d’exécution d’outils complète avec 19 outils à accès contrôlé et un modèle de plugin que vous pouvez étendre. C’est ce qui rend le câblage d’une API externe comme celle de WaveSpeed réellement réalisable.

Comment claw-code Gère les Appels d’Outils Externes

Le système d’outils de claw-code fonctionne via des définitions de schéma JSON générées dans la couche Rust, avec Python gérant le côté orchestration des agents. Chaque outil possède ses propres contrôles d’accès définis dans permissions.py. Lorsque vous ajoutez un outil personnalisé, l’agent peut décider de manière autonome quand l’appeler en fonction du contexte de la tâche — ce qui est exactement ce que vous voulez lorsqu’une invite « écris-moi un script et génère une vignette correspondante » devrait déclencher à la fois une tâche textuelle et un appel de génération d’image.

La logique de réessai intégrée dans le client API Anthropic de claw-code utilise le backoff exponentiel pour les réponses 408, 429 et 5xx. C’est ce même modèle que vous allez reproduire pour vos appels WaveSpeed.

Ajout d’une API de Modèle comme Outil dans le Harnais

Créez un fichier appelé wavespeed_tool.py dans le répertoire des outils de claw-code :

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()

Enregistrez ceci dans le registre d’outils de claw-code et l’agent pourra désormais appeler generate_image lors de toute session dans laquelle la création d’images est dans la portée.

Appel des Modèles de Génération d’Images et Vidéos depuis un Workflow d’Agent

C’est la section que je cherchais désespérément quand je configurais cela pour la première fois — et que je ne trouvais pas. La voici donc, aussi clairement que je peux l’écrire.

Modèle d’Appel à l’API REST

WaveSpeed utilise un modèle REST cohérent pour tous les modèles. L’appel de base ressemble à ceci (en utilisant WAN 2.7 texte-vers-vidéo comme exemple) :

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()

Pour les images (comme Flux Dev ou Seedream v4.5), la réponse revient de manière synchrone avec une URL de sortie. Pour les modèles vidéo — WAN 2.7, Kling 2.6, Hailuo 2.3 — c’est asynchrone, ce qui signifie que vous devez interroger l’état.

Gestion de la Génération Asynchrone et du Polling

La génération vidéo sur WaveSpeed prend généralement de 30 secondes à quelques minutes selon le modèle et la durée. L’API renvoie immédiatement un request_id ; vous interrogez un point de terminaison de statut jusqu’à ce que le travail soit terminé.

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)  # Interroger toutes les 5 secondes
    
    raise TimeoutError("Generation timed out")

Dans une boucle d’agent claw-code, vous encapsuleriez ce polling dans la fonction d’exécution de l’outil afin que l’agent attende le résultat avant de passer à l’étape suivante.

Gestion des Limites de Débit et des Replis dans un Contexte Agentique

Les limites de débit dans une boucle d’agent sont plus complexes que dans un simple script — l’agent peut déclencher plusieurs appels d’outils en succession rapide si la tâche est parallélisable. Voici le modèle de repli que j’utilise, adapté de la propre logique de réessai de 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  # Backoff exponentiel
                time.sleep(wait)
            elif e.response.status_code >= 500:
                # Essayer le modèle de repli si disponible
                model_id = fallback_models.get(model_id, model_id)
                time.sleep(2)
            else:
                raise
    raise RuntimeError(f"All retries exhausted for {model_id}")

La documentation de l’API WaveSpeed détaille les niveaux de limite de débit par niveau de compte — les comptes Silver (recharge unique de 100 $) bénéficient de limites de concurrence nettement plus élevées que le niveau Bronze par défaut, ce qui compte dès lors que vous commencez à exécuter des agents qui déclenchent plusieurs demandes de génération par session.

Modèles Multi-Modèles : Pourquoi l’Accès Agrégé est Important dans les Pipelines Agentiques

Je veux prendre un moment pour expliquer pourquoi cette architecture vaut l’effort de configuration — parce que ce n’est pas évident tant que vous n’avez pas réellement rencontré la friction de la gestion de comptes API séparés pour chaque modèle que vous souhaitez tester.

Changement de Modèle Sans Réécriture du Workflow

L’API unifiée de WaveSpeed signifie que vous pouvez remplacer wavespeed-ai/flux-dev par wavespeed-ai/seedream-v4-5 en modifiant une seule chaîne de caractères. Pas de nouveau flux d’authentification, pas de schéma de réponse différent à analyser, pas de changement de SDK. Pour un workflow agentique où vous souhaitez que l’agent choisisse le bon modèle pour la tâche (vignette photoréaliste vs illustration stylisée vs court clip vidéo), c’est véritablement utile — vous pouvez passer l’ID du modèle comme variable et laisser l’agent raisonner sur celui qui convient le mieux.

Voici un tableau de comparaison simple des modèles basé sur les spécifications de génération de mars 2026 du catalogue WaveSpeed :

Modèle	Type	Sortie	Idéal Pour
Flux Dev	Image	Jusqu’à 4K	Photoréaliste, rapide
Seedream v4.5	Image	Jusqu’à 4K	Artistique, stylisé
WAN 2.7 T2V	Vidéo	720p/1080p	Texte-vers-vidéo, cinématique
Kling 2.6 Pro	Vidéo	720p	Contrôle du mouvement, animation
Hailuo 2.3 Fast	Vidéo	720p	I2V optimisé pour la vitesse

Facturation Unifiée et Gestion des Clés

Celui-ci m’a surpris plus que je ne m’y attendais. Gérer séparément des clés API pour Runway, Kling, FLUX et WAN — chacune avec des tableaux de bord de facturation différents, des comportements de limite de débit différents, des formats d’erreur différents — représente une taxe opérationnelle significative lorsque vous construisez des workflows agentiques. Une seule clé, un seul tableau de bord de facturation et des schémas d’erreur cohérents pour tous les modèles constituent une véritable amélioration de la qualité de vie qui se manifeste dans la maintenabilité de votre code d’agent au fil du temps.

Le guide de sécurité de la chaîne d’approvisionnement logicielle de l’OWASP vaut la peine d’être lu avant de déployer un agent tiers en production — particulièrement pertinent compte tenu de l’incident de chaîne d’approvisionnement qui a affecté les installations Claude Code basées sur npm en mars 2026 (claw-code lui-même n’a pas été affecté, mais l’écosystème plus large justifie la prudence).

Limitations et Points à Vérifier

Je passerais à côté de la partie la plus utile de cette revue si j’omettais les aspérités.

Mises en Garde sur la Stabilité de claw-code

En avril 2026, claw-code n’est pas à parité de fonctionnalités avec Claude Code. Le portage Rust est encore en cours. Les intégrations IDE n’existent pas — c’est uniquement en terminal. L’orchestration multi-agents est documentée dans l’architecture mais n’a pas été éprouvée à grande échelle. Le projet compte plus de 48 000 étoiles GitHub et évolue rapidement, mais « architecture intéressante » et « prêt pour la production » sont des barres véritablement différentes.

Le statut juridique du projet est également non résolu. claw-code revendique le statut de chambre blanche comme défense contre la pression DMCA d’Anthropic — c’est une réécriture, pas une copie du code source ayant fuité — mais cette question juridique n’est pas réglée. Si vous construisez quelque chose pour un client ou à grande échelle, tenez compte de cette incertitude.

Ce Qui Nécessite des Tests Manuels

Avant de faire confiance à ce workflow en production, vous devriez vérifier manuellement :

Comportement du délai d’expiration du polling : L’intervalle de polling de 5 secondes que j’utilise est conservateur. Testez avec votre modèle vidéo et votre durée réels pour affiner max_wait.
Enregistrement des outils : Le registre d’outils de claw-code est en développement actif. L’API d’enregistrement exacte peut changer entre les commits — vérifiez le CHANGELOG du dépôt avant de fixer une version.
Contexte de permission : claw-code implémente l’exécution d’outils à accès contrôlé. Confirmez que vos outils generate_image et generate_video se voient accorder le niveau d’accès correct dans permissions.py.
Changements de schéma de réponse : WaveSpeed met parfois à jour les schémas de sortie des modèles. Ajoutez une validation autour du champ d’URL de sortie plutôt que de supposer une structure fixe.

FAQ

Q : claw-code peut-il appeler des APIs de génération d’images nativement ?

Pas prêt à l’emploi — il n’y a pas d’outil WaveSpeed ou de génération d’images intégré dans l’installation par défaut. Mais le système d’outils est conçu exactement pour ce type d’extension. Une fois que vous enregistrez un outil personnalisé avec le schéma JSON correct (comme indiqué ci-dessus), l’agent peut l’appeler de manière autonome dans n’importe quelle session.

Q : claw-code prend-il en charge les appels d’outils asynchrones ?

Le harnais Python gère l’exécution des outils de manière synchrone dans la boucle de l’agent. Pour la génération asynchrone (comme les modèles vidéo), le modèle que je recommande est : déclencher la requête initiale, obtenir le request_id, puis interroger l’état dans la fonction d’exécution de l’outil jusqu’à la complétion avant de retourner à l’agent. Cela maintient le raisonnement de l’agent linéaire et évite les conditions de concurrence dans l’état de la session.

Q : Ce workflow est-il prêt pour la production ?

Honnêtement ? Pas encore, pour la plupart des équipes. claw-code évolue rapidement mais comporte une incertitude juridique et n’a pas été durci pour une utilisation agentique à l’échelle de la production. L’API WaveSpeed est prête pour la production — SLA de disponibilité à 99,99%, pas de démarrages à froid, facturation à la seconde — mais le harnais claw-code qui l’entoure est encore à un stade précoce. J’utiliserais cela pour des outils internes, du prototypage et de l’exploration pour l’instant, et je réévaluerais pour une production côté client une fois le projet stabilisé.

Articles précédents :