Cómo usar claw-code con modelos WaveSpeed AI a través de la API

Imagina esto: Tu agente de IA no solo piensa — crea.

Razona paso a paso, luego llama sin problemas a un potente modelo de generación de imágenes para producir un visual impresionante, cambia a un modelo de video para añadir movimiento, analiza los resultados y continúa el flujo de trabajo — todo sin que muevas un dedo ni reescribas una sola línea de código.

Eso es exactamente lo que ahora es posible con los modelos de WaveSpeed AI y claw-code — reconstruido desde cero en Python al estilo de sala limpia, y publicado como código abierto por un desarrollador coreano justo después de la filtración de Claude Code.

En esta guía, descubrirás cómo aprovechar esta potente combinación para construir agentes que no solo charlan… crean, iteran y producen resultados multimedia reales dentro de un único bucle inteligente.

Tanto si eres creador, desarrollador o entusiasta de la IA que está harto de cambiar entre herramientas, este es tu atajo hacia flujos de trabajo multimedia verdaderamente agénticos.

¿Listo para hacer que tus agentes de IA sean visualmente poderosos? Empecemos.

Requisitos previos: Lo que necesitas antes de comenzar

Antes de tocar una sola línea de configuración, resuelve estas dos cosas. Saltarte cualquiera de ellas te costará horas de mensajes de error crípticos.

Configuración de claw-code y el entorno

claw-code funciona con Python 3.11+. A partir de marzo de 2026, la rama principal es Python-first (72.9% Rust, 27.1% Python según el desglose de lenguajes del propio proyecto, pero la entrada CLI que usarás día a día es Python). Instálalo desde el repositorio oficial:

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

También querrás establecer tu clave de Anthropic como variable de entorno — claw-code admite tanto ANTHROPIC_API_KEY como ANTHROPIC_AUTH_TOKEN, siguiendo los patrones de autenticación de la API de Anthropic de su documentación oficial.

export ANTHROPIC_API_KEY="your-key-here"

Vale la pena señalar que el port a Rust todavía está en progreso en una rama separada. Para flujos de trabajo de video/imagen, el harness de Python es suficientemente estable. La migración a Rust está orientada a rutas de ejecución críticas para el rendimiento — no es algo que necesites para este caso de uso ahora mismo.

Clave API y acceso al proveedor de modelos

Las cuentas nuevas obtienen $1 en créditos de prueba gratuitos — suficiente para probar algunas generaciones de imágenes y confirmar que tu pipeline funciona de extremo a extremo antes de gastar dinero real.

El catálogo de modelos de WaveSpeed a partir de marzo de 2026 cubre más de 700 modelos de generación de imágenes, video, audio y 3D, todos detrás de una única clave de API unificada. Eso importa mucho una vez que empiezas a construir flujos de trabajo de agentes con múltiples modelos — no querrás gestionar cinco encabezados de autenticación diferentes.

Conectar APIs de modelos externos en un flujo de trabajo de claw-code

Aquí es donde las cosas se vuelven genuinamente interesantes. claw-code no es solo un asistente de programación — implementa una capa completa de ejecución de herramientas con 19 herramientas con control de permisos y un modelo de plugins que puedes extender. Eso es lo que hace que integrar una API externa como la de WaveSpeed sea realmente viable.

Cómo claw-code gestiona las llamadas a herramientas externas

El sistema de herramientas de claw-code funciona a través de definiciones de esquema JSON generadas en la capa Rust, con Python gestionando el lado de la orquestación del agente. Cada herramienta tiene sus propios controles de acceso definidos en permissions.py. Cuando añades una herramienta personalizada, el agente puede decidir de forma autónoma cuándo llamarla basándose en el contexto de la tarea — que es exactamente lo que quieres cuando un prompt como “escríbeme un script y genera una miniatura a juego” debería activar tanto una tarea de texto como una llamada de generación de imágenes.

La lógica de reintentos integrada en el cliente de la API de Anthropic de claw-code usa backoff exponencial para respuestas 408, 429 y 5xx. Este mismo patrón es el que replicarás para tus llamadas a WaveSpeed.

Añadir una API de modelo como herramienta en el harness

Crea un archivo llamado wavespeed_tool.py en el directorio de herramientas 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()

Registra esto en el registro de herramientas de claw-code y el agente podrá llamar a generate_image durante cualquier sesión que tenga creación de imágenes en su alcance.

Llamar a modelos de generación de imágenes y video desde dentro de un flujo de trabajo de agente

Esta es la sección que seguía queriendo encontrar cuando estaba configurando esto por primera vez — y no podía. Así que aquí está, tan claramente como puedo escribirla.

Patrón de llamada a la API REST

WaveSpeed usa un patrón REST consistente en todos los modelos. La llamada base tiene este aspecto (usando WAN 2.7 text-to-video como ejemplo):

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

Para imágenes (como Flux Dev o Seedream v4.5), la respuesta llega de forma síncrona con una URL de salida. Para modelos de video — WAN 2.7, Kling 2.6, Hailuo 2.3 — es asíncrono, lo que significa que necesitas hacer polling.

Gestionar la generación asíncrona y el polling

La generación de video en WaveSpeed típicamente tarda entre 30 segundos y varios minutos dependiendo del modelo y la duración. La API devuelve un request_id inmediatamente; haces polling a un endpoint de estado hasta que el trabajo se completa.

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)  # Polling cada 5 segundos
    
    raise TimeoutError("Generation timed out")

Dentro de un bucle de agente de claw-code, envuelverías este polling en la función de ejecución de la herramienta para que el agente espere el resultado antes de continuar al siguiente paso.

Gestionar límites de velocidad y fallbacks en un contexto agéntico

Los límites de velocidad dentro de un bucle de agente son más complicados que en un script simple — el agente puede disparar múltiples llamadas a herramientas en rápida sucesión si la tarea es paralelizable. Aquí está el patrón de fallback que estoy usando, adaptado de la propia lógica de reintentos 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 exponencial
                time.sleep(wait)
            elif e.response.status_code >= 500:
                # Intentar modelo de fallback si está 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 documentación de la API de WaveSpeed detalla los niveles de límite de velocidad por nivel de cuenta — las cuentas Silver (recarga única de $100) obtienen límites de concurrencia sustancialmente más altos que el nivel Bronze predeterminado, lo que importa una vez que comienzas a ejecutar agentes que disparan múltiples solicitudes de generación por sesión.

Patrones multi-modelo: Por qué el acceso agregado importa en pipelines agénticos

Quiero dedicar un momento a explicar por qué esta arquitectura vale el esfuerzo de configuración — porque no es obvio hasta que realmente has experimentado la fricción de gestionar cuentas de API separadas para cada modelo que quieres probar.

Cambio de modelo sin reescribir el flujo de trabajo

La API unificada de WaveSpeed significa que puedes cambiar wavespeed-ai/flux-dev por wavespeed-ai/seedream-v4-5 con un único cambio de cadena. Sin nuevo flujo de autenticación, sin esquema de respuesta diferente que analizar, sin cambio de SDK. Para un flujo de trabajo agéntico donde quieres que el agente elija el modelo adecuado para la tarea (miniatura fotorrealista vs. ilustración estilizada vs. clip de video corto), esto es genuinamente útil — puedes pasar el ID del modelo como variable y dejar que el agente razone sobre cuál encaja mejor.

Aquí hay una tabla simple de comparación de modelos basada en las especificaciones de generación de marzo de 2026 del catálogo de WaveSpeed:

Modelo	Tipo	Salida	Mejor para
Flux Dev	Imagen	Hasta 4K	Fotorrealista, rápido
Seedream v4.5	Imagen	Hasta 4K	Artístico, estilizado
WAN 2.7 T2V	Video	720p/1080p	Text-to-video, cinematográfico
Kling 2.6 Pro	Video	720p	Control de movimiento, animación
Hailuo 2.3 Fast	Video	720p	I2V optimizado para velocidad

Facturación unificada y gestión de claves

Este me sorprendió más de lo que esperaba. Gestionar claves de API separadas para Runway, Kling, FLUX y WAN — cada una con diferentes paneles de facturación, diferentes comportamientos de límite de velocidad, diferentes formatos de error — es un impuesto operativo significativo cuando estás construyendo flujos de trabajo agénticos. Una sola clave, un panel de facturación y esquemas de error consistentes en todos los modelos es una mejora real en la calidad de vida que se refleja en cuán mantenible sigue siendo el código de tu agente con el tiempo.

La guía de seguridad de la cadena de suministro de software de OWASP vale la pena leerla antes de desplegar cualquier agente de terceros en producción — especialmente relevante dado el incidente de la cadena de suministro que afectó a las instalaciones de Claude Code basadas en npm en marzo de 2026 (claw-code en sí no se vio afectado, pero el ecosistema más amplio merece precaución).

Limitaciones y cosas que verificar

Me estaría perdiendo la parte más útil de esta revisión si omitiera los aspectos ásperos.

Advertencias sobre la estabilidad de claw-code

A partir de abril de 2026, claw-code no está a la par en características con Claude Code. El port a Rust todavía está en progreso. Las integraciones con IDE no existen — esto es solo terminal. La orquestación multi-agente está documentada en la arquitectura pero no ha sido probada a escala. El proyecto tiene más de 48k estrellas en GitHub y avanza rápido, pero “arquitectura interesante” y “listo para producción” son barras genuinamente diferentes.

El estado legal del proyecto también está sin resolver. claw-code alega estado de sala limpia como defensa contra la presión DMCA de Anthropic — es una reescritura, no una copia del código fuente filtrado — pero esa cuestión legal no está resuelta. Si estás construyendo algo para un cliente o a escala, ten en cuenta esa incertidumbre.

Qué requiere pruebas manuales

Antes de confiar en este flujo de trabajo en producción, deberías verificar manualmente:

Comportamiento del timeout de polling: El intervalo de polling de 5 segundos que estoy usando es conservador. Prueba con tu modelo de video real y duración para ajustar max_wait.
Registro de herramientas: El registro de herramientas de claw-code está en desarrollo activo. La API de registro exacta puede cambiar entre commits — revisa el CHANGELOG del repositorio antes de fijar una versión.
Contexto de permisos: claw-code implementa ejecución de herramientas con control de permisos. Confirma que tus herramientas generate_image y generate_video tienen el nivel de acceso correcto en permissions.py.
Cambios en el esquema de respuesta: WaveSpeed ocasionalmente actualiza los esquemas de salida de los modelos. Añade validación alrededor del campo de URL de salida en lugar de asumir la estructura.

Preguntas frecuentes

P: ¿Puede claw-code llamar a APIs de generación de imágenes de forma nativa?

No de forma predeterminada — no hay ninguna herramienta integrada de WaveSpeed o generación de imágenes en la instalación predeterminada. Pero el sistema de herramientas está diseñado exactamente para este tipo de extensión. Una vez que registras una herramienta personalizada con el esquema JSON correcto (como se muestra arriba), el agente puede llamarla de forma autónoma dentro de cualquier sesión.

P: ¿Admite claw-code llamadas a herramientas asíncronas?

El harness de Python gestiona la ejecución de herramientas de forma síncrona dentro del bucle del agente. Para la generación asíncrona (como los modelos de video), el patrón que recomendaría es: disparar la solicitud inicial, obtener el request_id, luego hacer polling dentro de la función de ejecución de la herramienta hasta que se complete antes de devolver el control al agente. Esto mantiene el razonamiento del agente lineal y evita condiciones de carrera en el estado de la sesión.

P: ¿Está este flujo de trabajo listo para producción?

Honestamente, ¿todavía no, para la mayoría de los equipos? claw-code avanza rápido pero conlleva incertidumbre legal y no ha sido endurecido para uso agéntico a escala de producción. El lado de la API de WaveSpeed está listo para producción — SLA de disponibilidad del 99.99%, sin arranques en frío, facturación por segundo — pero el harness de claw-code que lo envuelve todavía está en una etapa temprana. Usaría esto para herramientas internas, prototipado y exploración ahora mismo, y lo revisaría para producción orientada al cliente una vez que el proyecto se estabilice.

Publicaciones anteriores: