Como usar o claw-code com modelos WaveSpeed AI via API

Imagine isso: Seu agente de IA não apenas pensa — ele cria.

Ele raciocina passo a passo, depois chama perfeitamente um poderoso modelo de geração de imagens para produzir um visual impressionante, muda para um modelo de vídeo para movimento, analisa os resultados e continua o fluxo de trabalho — tudo sem você mover um dedo ou reescrever uma única linha de código.

É exatamente isso que agora é possível com os modelos do WaveSpeed AI e o claw-code — reconstruído do zero em Python em estilo clean-room e disponibilizado como código aberto por um desenvolvedor coreano logo após o vazamento do Claude Code.

Neste guia, você descobrirá como aproveitar essa poderosa combinação para construir agentes que não apenas conversam… eles criam, iteram e entregam saída multimídia real dentro de um único loop inteligente.

Seja você um criador, desenvolvedor ou entusiasta de IA cansado de alternar entre ferramentas, este é o seu atalho para fluxos de trabalho multimídia verdadeiramente agênticos.

Pronto para tornar seus agentes de IA visualmente poderosos? Vamos lá.

Pré-requisitos: O Que Você Precisa Antes de Começar

Antes de tocar em uma única linha de configuração, resolva essas duas questões. Pular qualquer uma delas vai te custar horas de mensagens de erro crípticas.

Configuração do claw-code e Ambiente

O claw-code roda em Python 3.11+. Em março de 2026, o branch principal é baseado em Python (72,9% Rust, 27,1% Python de acordo com o próprio detalhamento de linguagens do projeto, mas o ponto de entrada da CLI que você usará diariamente é Python). Instale-o do repositório oficial:

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

Você também vai querer definir sua chave Anthropic como variável de ambiente — o claw-code suporta tanto ANTHROPIC_API_KEY quanto ANTHROPIC_AUTH_TOKEN, correspondendo aos padrões de autenticação da API Anthropic da documentação oficial.

export ANTHROPIC_API_KEY="sua-chave-aqui"

Vale mencionar: o port em Rust ainda está em andamento em um branch separado. Para fluxos de trabalho de vídeo/imagem, o harness Python é suficientemente estável. A migração para Rust visa caminhos de runtime críticos para desempenho — algo que você não precisa para este caso de uso agora.

Chave de API e Acesso ao Provedor de Modelos

Novas contas recebem $1 em créditos de teste gratuitos — suficiente para testar algumas gerações de imagens e confirmar que seu pipeline funciona de ponta a ponta antes de gastar qualquer valor real.

O catálogo de modelos do WaveSpeed em março de 2026 cobre mais de 700 modelos de geração de imagem, vídeo, áudio e 3D, todos por trás de uma única chave de API unificada. Isso importa muito quando você começa a construir fluxos de trabalho de agentes com múltiplos modelos — você não quer gerenciar cinco cabeçalhos de autenticação diferentes.

Conectando APIs de Modelos Externos em um Fluxo de Trabalho claw-code

É aqui que as coisas ficam genuinamente interessantes. O claw-code não é apenas um assistente de codificação — ele implementa uma camada completa de execução de ferramentas com 19 ferramentas com controle de permissão e um modelo de plugin que você pode estender. É isso que torna a integração de uma API externa como a do WaveSpeed genuinamente viável.

Como o claw-code Lida com Chamadas de Ferramentas Externas

O sistema de ferramentas do claw-code funciona através de definições de esquema JSON geradas na camada Rust, com Python lidando com o lado de orquestração do agente. Cada ferramenta tem seus próprios controles de acesso definidos em permissions.py. Quando você adiciona uma ferramenta personalizada, o agente pode decidir autonomamente quando chamá-la com base no contexto da tarefa — que é exatamente o que você quer quando um prompt “escreva um script e gere uma miniatura correspondente” deve acionar tanto uma tarefa de texto quanto uma chamada de geração de imagem.

A lógica de retry integrada no cliente da API Anthropic do claw-code usa backoff exponencial para respostas 408, 429 e 5xx. Esse mesmo padrão é o que você replicará para suas chamadas WaveSpeed.

Adicionando uma API de Modelo como Ferramenta no Harness

Crie um arquivo chamado wavespeed_tool.py no diretório de ferramentas do 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": "Gera uma imagem usando WaveSpeed AI a partir de um prompt de texto.",
    "input_schema": {
        "type": "object",
        "properties": {
            "prompt": {"type": "string", "description": "Prompt de geração de imagem"},
            "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()

Registre isso no registro de ferramentas do claw-code e o agente agora pode chamar generate_image durante qualquer sessão que tenha criação de imagens no escopo.

Chamando Modelos de Geração de Imagem e Vídeo de Dentro de um Fluxo de Trabalho de Agente

Esta é a seção que eu queria encontrar quando estava configurando isso pela primeira vez — e não conseguia. Então aqui está, da forma mais clara que consigo escrever.

Padrão de Chamada da API REST

O WaveSpeed usa um padrão REST consistente em todos os modelos. A chamada base se parece com isso (usando WAN 2.7 text-to-video como exemplo):

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 imagens (como Flux Dev ou Seedream v4.5), a resposta volta de forma síncrona com uma URL de saída. Para modelos de vídeo — WAN 2.7, Kling 2.6, Hailuo 2.3 — é assíncrono, o que significa que você precisa fazer polling.

Lidando com Geração Assíncrona e Polling

A geração de vídeo no WaveSpeed tipicamente leva de 30 segundos a alguns minutos, dependendo do modelo e duração. A API retorna um request_id imediatamente; você faz polling em um endpoint de status até que o job seja concluído.

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"Geração falhou: {data.get('error')}")
        
        time.sleep(5)  # Polling a cada 5 segundos
    
    raise TimeoutError("Tempo limite de geração excedido")

Dentro de um loop de agente claw-code, você envolveria esse polling na função de execução da ferramenta para que o agente aguarde o resultado antes de continuar para o próximo passo.

Gerenciando Limites de Taxa e Fallbacks em um Contexto Agêntico

Limites de taxa dentro de um loop de agente são mais complicados do que em um script simples — o agente pode disparar múltiplas chamadas de ferramenta em rápida sucessão se a tarefa for paralelizável. Aqui está o padrão de fallback que estou usando, adaptado da própria lógica de retry do 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:
                # Tenta modelo de fallback se disponível
                model_id = fallback_models.get(model_id, model_id)
                time.sleep(2)
            else:
                raise
    raise RuntimeError(f"Todas as tentativas esgotadas para {model_id}")

A documentação da API WaveSpeed detalha os níveis de limite de taxa por nível de conta — contas Silver (recarga única de $100) têm limites de concorrência substancialmente maiores do que o nível Bronze padrão, o que importa quando você começa a executar agentes que disparam múltiplas solicitações de geração por sessão.

Padrões Multi-Modelo: Por Que o Acesso Agregado Importa em Pipelines Agênticos

Quero dedicar um momento para explicar por que essa arquitetura vale o esforço de configuração — porque não é óbvio até você realmente enfrentar o atrito de gerenciar contas de API separadas para cada modelo que você quer testar.

Troca de Modelos Sem Reescrever o Fluxo de Trabalho

A API unificada do WaveSpeed significa que você pode trocar wavespeed-ai/flux-dev por wavespeed-ai/seedream-v4-5 em uma única alteração de string. Sem novo fluxo de autenticação, sem esquema de resposta diferente para analisar, sem troca de SDK. Para um fluxo de trabalho agêntico onde você quer que o agente escolha o modelo certo para a tarefa (miniatura fotorrealista vs. ilustração estilizada vs. clipe de vídeo curto), isso é genuinamente útil — você pode passar o ID do modelo como variável e deixar o agente raciocinar sobre qual se encaixa melhor.

Aqui está uma tabela simples de comparação de modelos baseada nas especificações de geração de março de 2026 do catálogo WaveSpeed:

Modelo	Tipo	Saída	Melhor Para
Flux Dev	Imagem	Até 4K	Fotorrealista, rápido
Seedream v4.5	Imagem	Até 4K	Artístico, estilizado
WAN 2.7 T2V	Vídeo	720p/1080p	Text-to-video, cinematográfico
Kling 2.6 Pro	Vídeo	720p	Controle de movimento, animação
Hailuo 2.3 Fast	Vídeo	720p	I2V otimizado para velocidade

Faturamento Unificado e Gerenciamento de Chaves

Este me surpreendeu mais do que eu esperava. Gerenciar chaves de API separadas para Runway, Kling, FLUX e WAN — cada uma com dashboards de faturamento diferentes, comportamentos de limite de taxa diferentes, formatos de erro diferentes — é um custo operacional significativo quando você está construindo fluxos de trabalho agênticos. Uma chave, um dashboard de faturamento e esquemas de erro consistentes em todos os modelos é uma melhoria real de qualidade de vida que se reflete na manutenibilidade do seu código de agente ao longo do tempo.

O guia de segurança da cadeia de suprimentos de software da OWASP vale a leitura antes de implantar qualquer agente de terceiros em produção — especialmente relevante dado o incidente na cadeia de suprimentos que afetou instalações do Claude Code baseadas em npm em março de 2026 (o claw-code em si não foi afetado, mas o ecossistema mais amplo merece cautela).

Limitações e Coisas a Verificar

Estaria omitindo a parte mais útil desta análise se pulasse os pontos problemáticos.

Ressalvas de Estabilidade do claw-code

Em abril de 2026, o claw-code não está em paridade de recursos com o Claude Code. O port em Rust ainda está em andamento. Integrações de IDE não existem — isso é somente terminal. A orquestração multi-agente está documentada na arquitetura, mas não foi testada em escala. O projeto tem 48k+ estrelas no GitHub e está evoluindo rapidamente, mas “arquitetura interessante” e “pronto para produção” são barras genuinamente diferentes.

O status legal do projeto também não está resolvido. O claw-code alega status clean-room como sua defesa contra a pressão de DMCA da Anthropic — é uma reescrita, não uma cópia do código-fonte vazado — mas essa questão legal não está definida. Se você está construindo algo para um cliente ou em escala, leve essa incerteza em consideração.

O Que Requer Testes Manuais

Antes de confiar neste fluxo de trabalho em produção, você deve verificar manualmente:

Comportamento de timeout de polling: O intervalo de polling de 5 segundos que estou usando é conservador. Teste com seu modelo de vídeo e duração reais para ajustar o max_wait.
Registro de ferramentas: O registro de ferramentas do claw-code está em desenvolvimento ativo. A API de registro exata pode mudar entre commits — verifique o CHANGELOG do repositório antes de fixar uma versão.
Contexto de permissão: O claw-code implementa execução de ferramentas com controle de permissão. Confirme que suas ferramentas generate_image e generate_video receberam o nível de acesso correto em permissions.py.
Mudanças no esquema de resposta: O WaveSpeed ocasionalmente atualiza os esquemas de saída dos modelos. Adicione validação em torno do campo de URL de saída em vez de presumir a estrutura.

Perguntas Frequentes

P: O claw-code pode chamar APIs de geração de imagens nativamente?

Não por padrão — não há ferramenta integrada do WaveSpeed ou de geração de imagens na instalação padrão. Mas o sistema de ferramentas foi projetado exatamente para esse tipo de extensão. Assim que você registra uma ferramenta personalizada com o esquema JSON correto (conforme mostrado acima), o agente pode chamá-la autonomamente em qualquer sessão.

P: O claw-code suporta chamadas de ferramentas assíncronas?

O harness Python lida com a execução de ferramentas de forma síncrona dentro do loop do agente. Para geração assíncrona (como modelos de vídeo), o padrão que eu recomendaria é: dispare a solicitação inicial, obtenha o request_id, depois faça polling dentro da função de execução da ferramenta até a conclusão antes de retornar ao agente. Isso mantém o raciocínio do agente linear e evita condições de corrida no estado da sessão.

P: Este fluxo de trabalho está pronto para produção?

Honestamente? Ainda não, para a maioria das equipes. O claw-code está evoluindo rapidamente, mas carrega incerteza legal e não foi endurecido para uso agêntico em escala de produção. O lado da API WaveSpeed está pronto para produção — SLA de 99,99% de uptime, sem cold starts, faturamento por segundo — mas o harness claw-code que o envolve ainda está em estágio inicial. Eu usaria isso para ferramentas internas, prototipagem e exploração agora, e revisitaria para produção voltada ao cliente assim que o projeto se estabilizar.

Posts Anteriores: