WAN 2.5 API Quickstart no WaveSpeed: Autenticação, Parâmetros e Requisições de Exemplo

Olá, sou a Dora. Originalmente, não planejava experimentar a API WAN 2.5 no WaveSpeed esta semana. Um pequeno incômodo me levou lá: eu precisava de algumas variações de imagem consistentes para um rascunho, e minhas ferramentas usuais eram muito clicáveis ou muito inteligentes para seu próprio bem. Eu queria algo chato e confiável, programável, versionado, fácil de reverter.

Então abri a documentação, preparei chá e fiz um pequeno script. Isto é o que anotei ao longo do caminho, testado em janeiro de 2026, sem brilho. É menos sobre “recursos” e mais sobre as partes que tornaram o trabalho mais leve uma vez que foram implementadas.

Visão geral da API

Se você já tocou em qualquer API de IA moderna, a abordagem do WaveSpeed para WAN 2.5 será familiar. HTTP dentro, JSON fora. Você envia um prompt (e às vezes uma imagem), e ele retorna um artefato finalizado ou um ID de trabalho que você pode consultar.

Alguns detalhes básicos que observei antes de escrever qualquer código:

Versionamento: WAN 2.5 é exposto como uma versão distinta, o que importa para reprodutibilidade. Fiquei com o caminho de versão explícita nas URLs em vez de um alias “latest”. Essa pequena escolha me poupa de mudanças de comportamento silenciosas no futuro.
Modos: Algumas cargas de trabalho são síncronas (pequenas, rápidas), outras giram como trabalhos. Se você está fazendo gerações de alta resolução ou trabalho em lote, espere um fluxo assíncrono com um endpoint de status ou webhooks.
Formatos: As respostas JSON normalmente incluem um status, uma URL de ativo ou payload base64, e alguns metadados (seed, steps, tempo). Eu mantenho os metadados, úteis quando você quer reproduzir um visual depois.
Limites: Tamanho de imagem, contagem de steps e concorrência são limitados. Os padrões eram suficientes para rascunhos, mas bati no teto quando tentei aumentar a resolução. Mais sobre limites de taxa abaixo.

A versão curta: é um caminho direto se você se sentir confortável com REST. O truque é acertar os poucos bits chatos (chaves, parâmetros, retentativas) para poder esquecê-los.

Essa simplicidade é parte do motivo pelo qual construímos o WaveSpeed do jeito que é. Eu queria que WAN 2.5 (e outros modelos) se sentisse programável, versionado e chato da melhor forma. Se você está conectando isso, pode explorar aqui.

Auth & chave

Gerei uma chave de API do WaveSpeed no painel e a coloquei em uma variável de ambiente. Nada sofisticado, mas poupou-me de caçar segredos por todos os arquivos.

Obtenha uma chave nas configurações da sua conta no WaveSpeed. Ela é vinculada à sua org/projeto.
Armazene-a localmente como uma variável de ambiente: WAVESPEED_API_KEY. Usei um arquivo .env para dev e o armazenamento de segredos do meu CI para execuções.
Use autenticação Bearer no cabeçalho: Authorization: Bearer $WAVESPEED_API_KEY.
Se você rotacionar chaves, faça durante horas de pouco tráfego. Aprendi isso da forma discreta quando uma rotação cronometrada interrompeu um trabalho longo.

Se sua equipe precisa de chaves com escopo, verifique as configurações do painel. Prefiro a rota de menor privilégio para qualquer coisa vinculada a uma automação. Um pequeno atrito: se você estiver executando de várias máquinas, rotule chaves claramente por host ou serviço, ajuda quando você audita o uso depois.

Parâmetros obrigatórios

Os nomes exatos podem diferir por endpoint, mas aqui está a forma mínima que usei para Wan 2.5 no WaveSpeed. Trate-os como um esqueleto, confirme os nomes de campo na documentação oficial para sua conta.

model: Defini isso explicitamente como wan-2.5 (ou a string exata mais próxima em seu plano). Mantém o comportamento estável em atualizações.
input: Uma string de prompt. Mantive-a curta e concreta. WAN tende a responder melhor a frases claras e simples do que a sopa de adjetivos.
mode ou task: Geração de imagem versus variação/upscale. Se você estiver passando uma imagem de origem, isso importa.
output: Pedi uma URL de imagem por padrão. Base64 está lá, mas URLs são mais gentis com a memória.

Quando esqueci de definir o modelo explicitamente, obtive um padrão sensato, mas meus resultados variaram sutilmente entre as execuções. Não estava errado, apenas não reprodutível. Bloquear a versão removeu essa oscilação.

Parâmetros opcionais

É aqui que o controle real está. Eu apenas toquei em um punhado no primeiro dia.

seed: Ligo isso uma vez que gosto de um visual. Estabiliza o clima para variações.
steps: Steps mais altos podem impulsionar detalhes ao custo de tempo e créditos. Bati em pequenos incrementos (por exemplo, 24 → 32) e observei retornos.
guidance ou cfg_scale: Aperta a aderência ao prompt. Muito alto e fica frágil.
size ou resolution: É aqui que os custos aumentam. Faço rascunhos pequenos, depois reexecuto finais nos tamanhos de destino.
image: Para variações, passe uma URL de imagem de origem ou carregue. Combine com um parâmetro de força se suportado.
safety ou moderation flags: Deixe ligado, a menos que seu fluxo de trabalho realmente precise de manipulação personalizada.
user ou metadata: Adiciono um ID de solicitação ou tag de projeto para rastrear execuções em logs depois.

Pequena observação: mudar dois controles ao mesmo tempo dificultou dizer o que ajudou. Mudei uma coisa por execução e mantive notas em comentários. À moda antiga, mas funcionou.

Padrões de solicitação de amostra

Tentei três formas simples: um curl rápido, um pequeno script Python e um trabalho em segundo plano para assíncrono.

Rascunho síncrono (curl)

Isso foi suficiente para verificar minha chave e prompt antes de conectar qualquer outra coisa.

Exemplo de endpoint, confirme o caminho exato na documentação para sua conta e região:

POST https://api.wavespeed.ai/wan/v2.5/generations

Cabeçalhos:

Authorization: Bearer $WAVESPEED_API_KEY
Content-Type: application/json

Corpo (mínimo):

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

O que observei:

200 com um resultado e metadados → você está bem.
202 com um ID de trabalho → mude para fluxo assíncrono.
4xx → algo no payload ou auth está errado.

Pequeno auxiliar Python

Escrevi uma pequena função para lidar com cabeçalhos, timeouts e json. Ela retornava uma URL ou levantava uma exceção limpa. Nada mágico, apenas o tipo de wrapper em que você não pensa duas vezes.

Bits práticos:

Defina um timeout curto de conexão e um timeout de leitura ligeiramente mais longo.
Lidar com 429 com uma retentativa e jitter.
Registre o seed, steps e tamanho para cada execução.

Fluxo assíncrono (trabalhos)

Para imagens maiores ou lotes, recebi um 202 e um ID de trabalho. O loop era simples:

Postar trabalho,

Consulte GET /jobs/{id} a cada poucos segundos,
Parar em estado terminal (sucesso/falha),
Buscar URL de ativo.

Se sua pilha gosta de webhooks, o WaveSpeed também expõe callbacks. Fiquei com polling no início, é uma peça a menos durante a configuração.

Códigos de erro

Mantive um pequeno mapa ao lado do meu editor. Compensou mais rápido do que esperava.

400 Bad Request: Normalmente uma falta de correspondência de nome de campo ou tipo. Uma vez enviei tamanho como uma string, não um objeto. O reparo foi óbvio uma vez que reduzi a velocidade e li a mensagem.
401 Unauthorized: Chave ausente ou malformada. Verifique seu cabeçalho Bearer e espaços à direita.
403 Forbidden: A chave existe, mas carece de escopo para o endpoint ou nível de modelo.
404 Not Found: Caminho de endpoint errado ou um ID de trabalho que expirou.
409 Conflict: Você às vezes verá isso ao atualizar um trabalho que já foi resolvido. Consulte novamente, não continue empurrando.
429 Too Many Requests: Você passou de um limite por minuto ou por org. Recue com retentativas exponenciais.
500/503 Server Errors: Raro em meus testes, mas planeje para isso. Um pequeno loop de retentativa manteve meus scripts calmos.

Pequeno hábito que ajudou: borbulhei o código de erro e o ID da solicitação (se presente) em meus logs. Quando algo fica estranho, o suporte pode usar esse ID para rastreá-lo.

Limites de taxa

Bati em limites de taxa uma vez que ficou preguiçoso com concorrência. Fácil de fazer, mais fácil de evitar.

O que funcionou:

Respeite os cabeçalhos: Muitos endpoints retornam cabeçalhos de taxa (por exemplo, restante, tempo de reset). Os nomes de cabeçalho podem variar, verifique a documentação, mas vale a pena ler.
Use um token bucket ou fila simples. Limitei meus scripts a um pequeno fluxo constante em vez de explosões. O sistema respirou mais fácil, e eu também.
Separe rascunhos de finais. Rascunhos podem ser executados pequenos e rápidos: finais podem ser executados um a um em segundo plano.
Cache repete. Se você está testando prompts, mantenha resultados anteriores por alguns minutos para não estar queimando a mesma chamada.

Também criei um recuo muito simples: atraso base de 1s, dobrando em cada 429, com limite de 30s e máximo de 4 retentativas. Pareceu desapressado e evitou dogpile no serviço.

Proteções de custo

Essa era minha principal preocupação. O trabalho com imagens pode roer créditos em segundo plano enquanto você está preparando chá.

Algumas proteções que coloquei em prática no primeiro dia:

Limites de orçamento no painel: Defini um limite mensal e alertas por e-mail um pouco abaixo. Se sua equipe compartilha uma chave, os alertas ajudam a capturar loops mais cedo.
Limites por solicitação: Forcei tamanho e steps a viver sob um máximo, a menos que eu passasse uma flag de substituição. Poupou-me de “ops, 4K tudo.”
Fluxo de trabalho com rascunho primeiro: Executo pequenas visualizações (resolução mais baixa, menos steps) e apenas upscale os guardiões. Isso reduziu meu gasto em mais da metade na primeira tarde.
Disciplina de seed: Uma vez que encontrei uma direção que gostei, fixei o seed e mudei um parâmetro de cada vez. Menos execuções cegas: mais intencionais.
Logs com custos: Se a resposta incluir um campo de crédito ou uso (alguns endpoints fazem), armazene-o. Quando não fizer, estime com base na resolução e steps e anote que é uma estimativa.

Também coloquei um interruptor suave kill-switch em meus scripts: se o uso do dia cruzasse um limite, novos trabalhos pausariam e postavam uma mensagem no Slack. Não é elegante, mas é honesto sobre restrições.

Isso não economizou tempo no início. Economizou atenção. Após algumas execuções, as proteções desapareceram do fundo, e eu poderia pensar no trabalho novamente em vez do medidor.