Como Usar WaveSpeedAI no n8n em 2026 — Guia para Gerar Imagens e Vídeos por API

Sim, você pode usar a WaveSpeedAI no n8n por um community node ou pelo node HTTP Request. O node acelera o primeiro workflow; HTTP dá controle sobre payload, retries e logs. Para imagem e vídeo, o ponto decisivo é entender o ciclo assíncrono: enviar a tarefa, guardar o ID, aguardar e buscar o arquivo final.

A WaveSpeedAI documenta integração com n8n para fluxos de texto para imagem, texto para vídeo, imagem para vídeo e áudio. O repositório oficial também mantém o pacote n8n-nodes-wavespeed. Este guia foca na operação: como evitar que uma automação visual vire uma caixa-preta cara. Documentação oficial · repositório do node.

Se você ainda está decidindo se a plataforma faz sentido para seu caso, leia o review completo do WaveSpeedAI. Aqui, a pergunta é outra: como colocar mídia generativa em um workflow sem depender de tentativa e erro.

Como funciona o fluxo WaveSpeedAI no n8n

💡 Vai rodar n8n numa VPS? A gente comparou o preço real em cada provedor — com renovação e requisitos — em VPS para n8n.

A API não devolve necessariamente a mídia pronta na mesma chamada. O padrão documentado é submeter uma tarefa, receber um identificador e consultar o resultado depois. Vamos chamar isso de Circuito Submit-Poll-Render: submit cria o job, poll acompanha o estado e render entrega a URL ou arquivo para o próximo node. A REST API da WaveSpeedAI descreve esse fluxo com Bearer token e consulta por ID de tarefa.

Esse circuito evita um erro comum em automações: tratar geração de vídeo como se fosse uma resposta instantânea. Imagem pode terminar rápido, mas o workflow não deve supor tempo fixo. Em vez disso, guarde o ID retornado, use um node Wait e siga apenas quando o status for terminal, como concluído, falho, cancelado ou expirado.

Dois caminhos: community node ou HTTP Request?

A recomendação prática é simples: use o node para provar que o caso funciona; migre ou complemente com HTTP Request quando precisar enxergar cada detalhe. Não é uma regra contra no-code. É uma forma de manter o workflow depurável quando um modelo muda parâmetros ou um retorno falha.

Antes de começar: conta, crédito e API key

Você precisa de uma conta WaveSpeedAI, uma API key e crédito disponível. A página de preços informa US$1 em créditos iniciais, sem cartão, e cobrança conforme o uso. Esse crédito é bom para validar o fluxo, mas não garante acesso a todos os modelos premium. Confira os preços oficiais antes de escolher um modelo.

No n8n, crie a credencial ou guarde a chave em uma variável segura. Nunca cole a chave em um node Set, em código exportado ou em screenshot. Em instâncias self-hosted, prefira variáveis de ambiente e credenciais do próprio n8n; isso reduz o risco de vazar o segredo ao compartilhar um workflow.

Se o objetivo é testar catálogo e integração, o acesso ao WaveSpeedAI pelo Runzos é o CTA certo. Ele leva à oferta com o benefício editorial de US$1 em créditos, sem jogar você em um link comercial direto.

Como instalar o WaveSpeedAI no n8n com community node

O pacote verificado no package.json do repositório oficial é n8n-nodes-wavespeed. Ele inclui nodes WaveSpeedPredictor, WaveSpeedUpload e WaveSpeedLoras, além de cobrir categorias como texto para imagem, texto para vídeo, imagem para imagem e imagem para vídeo. Veja a definição do pacote.

Instalação pela interface

1. Abra Settings no n8n.
2. Entre em Community Nodes.
3. Busque por “wavespeed”.
4. Confirme o nome do pacote antes de instalar: n8n-nodes-wavespeed.
5. Adicione um node WaveSpeed ao canvas e associe a credencial com sua API key.

A disponibilidade de community nodes depende da configuração da instância. Se o menu não aparecer, não tente contornar restrições corporativas instalando pacotes sem aprovação. Em uma instância sua, consulte a documentação de community nodes do n8n e o README do projeto antes de alterar o ambiente. Documentação do n8n.

Quando a interface não resolve

Em self-hosting, a instalação pode depender da política da instância, permissões do container ou da versão do n8n. O caminho seguro é validar primeiro se a imagem/container permite community nodes. Se não permitir, não force a dependência: use HTTP Request. A API continua sendo o caminho universal e ainda facilita logs completos quando houver um Bad request.

Como gerar uma imagem no n8n

Para uma imagem, o workflow mínimo pode ser: Manual Trigger ou Webhook → Set com prompt → WaveSpeed node ou HTTP Request → Wait → consulta de resultado → Drive, S3, WordPress ou resposta ao webhook. A WaveSpeedAI lista mais de 1.000 modelos em categorias de imagem, vídeo, áudio e 3D; escolha um endpoint e parâmetros compatíveis com o modelo, em vez de reutilizar o payload de outro modelo. Catálogo oficial de modelos.

No community node, selecione a operação de geração compatível e preencha o prompt. Guarde no output o identificador da tarefa retornado. Esse campo é a ponte entre o disparo e o resultado: sem ele, o n8n não sabe qual job consultar depois.

Onde salvar o arquivo final

Depois do polling informar conclusão, use a URL retornada pelo serviço como entrada do próximo node. Se quiser persistir a mídia, baixe o binário e envie para seu storage. Para WordPress, use o node adequado para media upload antes de criar a postagem; para S3 ou Drive, use a credencial do respectivo destino. Não presuma que uma URL temporária será um arquivo permanente da sua infraestrutura.

Como gerar vídeo no n8n

Vídeo segue o mesmo circuito, mas o custo e a espera merecem mais atenção. A FAQ oficial informa que não há endpoint dedicado de batch: você deve enviar requisições individuais respeitando limites de rate e concorrência e acompanhar cada tarefa por polling ou webhook. FAQ oficial.

Para um vídeo, crie o submit, armazene o ID e coloque um Wait entre cada consulta. Comece com um intervalo conservador, como alguns segundos, e limite o número de tentativas. Um loop sem Wait não torna o vídeo mais rápido; apenas cria tráfego desnecessário e dificulta identificar limites ou falhas.

Polling ou webhook?

Polling é mais simples para o primeiro workflow: o n8n espera, chama o endpoint de prediction e decide se volta a esperar. Webhook reduz consultas periódicas quando seu volume cresce, desde que você tenha uma URL pública e trate a correlação entre o callback e o ID original. A documentação de quick start lista webhooks, streaming, upload e modo síncrono como recursos da plataforma; escolha pelo desenho do seu processo, não por moda. Quick start oficial.

Usando HTTP Request sem community node

HTTP Request é o plano B e, muitas vezes, o plano de produção. Ele evita que você fique parado quando um node não expõe um parâmetro novo ou não deixa claro o JSON enviado. A API usa o cabeçalho Authorization: Bearer SUA_API_KEY e endpoints sob https://api.wavespeed.ai/api/v3/. Referência REST.

Node 1: submit da tarefa

Configure um HTTP Request com método POST. O modelo abaixo usa a rota mostrada na documentação para wavespeed-ai/flux-dev. Confirme os campos exigidos pela página do modelo escolhido antes de ativar o workflow: parâmetros de imagem e vídeo não são universais.

POST https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev
Authorization: Bearer {{$env.WAVESPEED_API_KEY}}
Content-Type: application/json

{
  "prompt": "uma bancada de trabalho de um desenvolvedor, luz azul, estilo editorial"
}

No node, use uma expressão para ler a variável de ambiente ou uma credencial, não uma chave literal. Em seguida, salve o ID retornado em um campo previsível do item, por exemplo predictionId. O nome exato do campo na resposta deve ser conferido na execução e na documentação atual do endpoint; isso evita mapear um caminho inexistente.

Node 2: Wait e consulta do resultado

Após o Wait, faça um GET para o endpoint de predictions usando o ID que você guardou. A documentação mostra a consulta em /api/v3/predictions/TASK_ID. Encaminhe o fluxo apenas se o status indicar conclusão; para estados em processamento, volte ao Wait; para falha, envie o payload a um node de log ou alerta. Exemplo oficial de consulta.

GET https://api.wavespeed.ai/api/v3/predictions/{{$json.predictionId}}
Authorization: Bearer {{$env.WAVESPEED_API_KEY}}

Esse desenho é mais verboso que arrastar um node, mas deixa claro onde investigar: submit, ID, status, URL de output ou destino do arquivo. É essa visibilidade que separa um protótipo de uma automação que alguém consegue manter.

Quanto custa rodar WaveSpeedAI pelo n8n?

O custo relevante não é o preço de vitrine. É o custo por execução visual: modelo multiplicado por imagens, segundos de vídeo e tentativas. A tabela usa a cotação editorial arredondada de US$1 = R$5,50, apenas como referência em 19 de julho de 2026. Preços e câmbio variam; valide ambos antes de colocar um workflow em lote. Fonte dos preços.

A tabela não transforma 100 segundos em 100 vídeos. A duração final de cada vídeo determina quantas gerações cabem nesse orçamento. Também reserve margem para retries: um prompt inválido ou uma mídia inacessível pode consumir tempo operacional mesmo quando não gera o output esperado.

A WaveSpeedAI documenta o endpoint /api/v3/model/pricing para consultar preço programaticamente com modelo e inputs. Para fluxo recorrente, coloque essa consulta antes do submit ou mantenha uma aprovação manual acima de um teto de custo. Como funciona a precificação.

Erros comuns no n8n e como resolver

A documentação oficial categoriza erros que aparecem com frequência em automações. O tratamento correto começa guardando o corpo da resposta em um log. Não faça retry cego em todos os casos: um campo ausente exige correção de payload, não cinco tentativas iguais. Códigos de erro oficiais.

O famoso Bad request normalmente cai em 1400 ou 1401: nome de campo errado, URL ausente, tipo de dado incompatível ou modelo que não aceita aquela entrada. Abra a execução do n8n, compare o JSON efetivamente enviado com a página do endpoint e reduza o payload ao mínimo antes de adicionar parâmetros. Uma discussão na comunidade n8n relata justamente falha de Bad request ao gerar vídeo, o que reforça a utilidade desse método. Discussão na comunidade n8n.

Quando usar Kie.ai como alternativa

WaveSpeedAI faz sentido quando você quer catálogo multimodal, integração documentada com n8n e uma API única. Kie.ai entra na conversa quando a prioridade é comparar o custo de modelos e testar outra rota de API. Não existe vencedora universal: compare o modelo, a unidade de cobrança, os parâmetros necessários e a disponibilidade para seu caso.

Se a economia for mais importante que o catálogo ou o node pronto, compare com Kie.ai pelo Runzos. Para referência editorial sobre a ferramenta, há também o review do Kie.ai. Evite escolher apenas pelo valor unitário: um modelo barato que exige mais retries pode sair caro no workflow completo.

Exemplos de workflows que fazem sentido

Um caso público no ecossistema n8n combina Telegram, WaveSpeed, sistema de créditos, PIX e S3 para geração de imagens. É uma referência interessante para quem quer entender a arquitetura de um produto brasileiro, mas não precisa ser o primeiro workflow a construir. Veja o template.

Outro template usa imagens do Google Drive, GPT-5.1, WaveSpeed, Submagic, Gmail e Blotato para reels diários. A lição é arquitetural: quebre o pipeline em etapas observáveis, salve IDs e outputs, e não esconda todas as decisões em um único node. Veja o workflow de reels.

Checklist antes de ativar o workflow

1. Confirmar o modelo e os campos obrigatórios na documentação atual.
2. Armazenar a API key em credencial ou variável de ambiente.
3. Registrar o ID retornado pelo submit.
4. Inserir Wait entre consultas de status.
5. Definir estados de sucesso, espera e falha.
6. Guardar resposta de erro em log.
7. Calcular custo por execução e impor teto para lote.
8. Testar uma imagem antes de rodar vídeo em volume.
9. Usar webhook apenas quando puder receber e correlacionar callbacks.
10. Salvar o arquivo final em storage que você controla.

FAQ

WaveSpeedAI tem node oficial para n8n?

A WaveSpeedAI documenta community nodes para n8n e mantém o repositório wavespeed-n8n. O pacote verificado no repositório é n8n-nodes-wavespeed. A disponibilidade na sua interface depende da política e configuração da instância n8n. Fonte oficial.

Dá para usar WaveSpeedAI sem community node?

Sim. O node HTTP Request pode chamar a REST API com Bearer token, submeter a tarefa e consultar o resultado pelo ID. Esse caminho exige mais configuração, mas dá visibilidade sobre endpoint, headers, JSON e resposta, o que ajuda muito no diagnóstico. Documentação REST.

Como calcular o custo antes de rodar?

Multiplique o preço da unidade pelo número de imagens ou segundos de vídeo e converta com uma cotação declarada. Para não depender de tabela manual, a plataforma também documenta uma consulta de pricing por API com o modelo e os inputs. Documentação de pricing.

O que fazer quando aparece Bad request?

Reduza o payload ao mínimo e compare cada campo com a documentação do endpoint do modelo escolhido. Os códigos 1400 e 1401 correspondem, respectivamente, a parâmetro ausente e inválido. Não faça retry antes de corrigir o payload: a mesma requisição inválida continuará falhando. Códigos de erro.

WaveSpeedAI aceita webhook?

A documentação de quick start lista webhooks como uma opção da plataforma. Use webhook quando seu fluxo precisar evitar polling recorrente e você tiver uma URL pública preparada para receber o callback. Para começar, polling com Wait no n8n costuma ser mais simples de observar e depurar. Quick start.

Conclusão

A forma confiável de usar WaveSpeedAI no n8n não é instalar um node e torcer. É montar o Circuito Submit-Poll-Render: enviar a tarefa, guardar o ID, esperar, consultar o status e salvar o output. Com isso, imagem e vídeo deixam de ser uma etapa opaca do workflow.

Comece pequeno, meça custo por execução e registre falhas. Quando o fluxo estiver previsível, use o WaveSpeedAI pelo Runzos para testar a API com os créditos iniciais. Se a prioridade mudar para economia, compare a alternativa Kie.ai antes de escalar.