PiAPI no n8n em 2026: guia de arquitetura para mídia por API

Resumo rápido: este guia mostra como planejar no n8n uma fila para mídia da PiAPI: receber pedido, criar task, salvar task_id, consultar status e armazenar o asset. Reserve cerca de 45 minutos para o desenho inicial, sem contar o teste. Você precisa de conta PiAPI, chave ativa, créditos e n8n. O consumo depende do modelo; confira o painel antes de gerar.

Resposta curta: o fluxo mínimo de PiAPI com 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 PiAPI se apresenta como um hub para modelos generativos de imagem, vídeo, áudio, 3D e LLM. O n8n entra como a camada que recebe dados, chama a API e encaminha o resultado. O node HTTP Request do n8n permite configurar método, URL, headers e body para qualquer API REST.

O erro comum é tratar isso como um único request. Em geração de mídia, a primeira resposta pode criar uma tarefa e devolver somente um identificador. O workflow precisa esperar, consultar o resultado e decidir o que fazer se a tarefa falhar ou demorar além do limite.

Esta é a Fila Multimodal: um padrão de automação em que imagem, vídeo e áudio passam pela mesma esteira operacional. Você muda a modalidade, o modelo e os campos exigidos; não precisa reinventar a arquitetura toda vez.

Este material é um guia de arquitetura, não um tutorial executado ponta a ponta. Não há task real, asset gerado ou tempo medido pelo Runzos nesta versão. Portanto, confirme endpoint, autenticação, modelo, payload e estados de status na documentação e na conta antes de copiar qualquer configuração para produção.

Um fluxo inicial pode seguir esta ordem:

1. Webhook, formulário ou gatilho manual recebe o prompt.
2. Um node Set/Edit Fields separa media_type, model e prompt.
3. O HTTP Request cria a task na PiAPI.
4. O n8n guarda o task_id e aguarda.
5. Outro HTTP Request consulta o status.
6. Se houver sucesso, o workflow salva a URL ou arquivo final.
7. Se falhar, registra o erro e tenta um fallback controlado.

Para entender quando um workflow visual vale mais que outro, veja o comparativo n8n vs Make. Aqui, vamos usar o HTTP Request porque ele deixa a integração auditável mesmo quando o catálogo ou os templates de um provedor mudam.

Antes de automatizar: calcule o Custo por Mídia Aprovada

Preço por request não é o custo final de uma automação criativa. Uma imagem pode exigir três variações. Um vídeo pode falhar, ficar fora do tom ou precisar de outra duração. Por isso, use o Custo por Mídia Aprovada: o valor de uma saída que você realmente vai usar, somando tentativas, refações e falhas.

Referência operacional histórica, não preço vigente. A tabela usa cotação de R$ 5,50 por US$ 1 e valores registrados na pesquisa em 3 de agosto de 2026.

Em 4 de agosto de 2026, a página de preços da PiAPI mostrava Free (US$ 0/mês), Creator (US$ 15/mês, US$ 10 em créditos de bônus) e Pro (US$ 60/mês, US$ 60 em créditos de bônus).

A página também informava que assinatura não substitui créditos PAYG ou assentos HYA. Preço e disponibilidade por modelo devem ser conferidos nos preços oficiais da PiAPI e no painel da conta antes do teste.

A PiAPI trabalha com créditos pay-as-you-go e, para alguns modelos ou APIs, Host-Your-Account (HYA). Portanto, assinatura e consumo não são sinônimos. Não trate o valor mensal como garantia de que todos os modelos estão incluídos. Confirme regras e créditos na página de preços e no painel da sua conta.

O ponto prático é simples: defina um teto por job. Se um vídeo tem orçamento de R$ 8,00 e já consumiu três tentativas, o workflow deve encerrar, pedir revisão do prompt ou trocar de rota. Loop infinito de geração não é criatividade; é vazamento de margem.

Quer testar a centralização de modelos antes de montar uma operação maior? Veja a PiAPI pela oferta do Runzos.

Como preparar a PiAPI: conta, API key e modelo

Crie a conta e obtenha a chave conforme a documentação oficial da PiAPI. A PiAPI também oferece uma CLI para operar modelos de imagem, vídeo, áudio, 3D e chat, mas o objetivo deste guia é manter a automação no n8n.

Onde guardar a API key no n8n

Nunca cole a chave no prompt, no node Set, em uma URL ou em um print. Use credenciais do n8n ou uma variável de ambiente disponível ao workflow. A credencial deve preencher o header de autenticação sem expor o segredo no histórico de execução.

Também vale separar uma chave de teste de uma chave de produção. Assim, um workflow em desenvolvimento não consome o saldo destinado a jobs de cliente.

Como escolher modalidade e modelo

Não deixe modelo e modalidade escondidos dentro de um prompt longo. Crie campos separados:

• media_type: image, video ou audio;
• model: o identificador escolhido no catálogo atual;
• task_type: por exemplo, txt2img ou txt2video;
• prompt: a instrução criativa;
• attempt: número da tentativa;
• prompt_hash: identificador para cache e idempotência.

O catálogo muda. A PiAPI pode facilitar acesso a modelos difíceis de integrar diretamente, mas não é prudente codificar a aplicação como se um modelo estivesse disponível para sempre. Deixe o identificador em um node de configuração ou em uma tabela externa fácil de alterar.

Como desenhar o HTTP Request no n8n

Crie um node HTTP Request depois do node que organiza os campos. Em 4 de agosto de 2026, a conferência editorial conseguiu abrir a página pública de preços, mas o host docs.piapi.ai não resolveu neste ambiente. Por isso, esta versão não afirma um endpoint, header, payload ou rota de consulta como contrato vigente e não simula uma execução sem credencial.

Use esta checklist ao conferir a documentação oficial e a sua conta:

• Método de criação: confirme se a operação exige POST;
• URL: copie o endpoint exibido na referência vigente do modelo escolhido;
• Autenticação: guarde a chave em credencial segura e confirme o nome exato do header;
• Consulta: confirme a rota, o parâmetro de identificação e os estados retornados;
• Body: valide campos obrigatórios, valores aceitos e formato de saída para aquele modelo.

Como referência conceitual, um pedido de imagem costuma separar modelo, tipo de tarefa e um objeto de entrada. Nesse objeto entram o prompt e a proporção. Os nomes, a hierarquia e os valores permitidos não são confirmados neste guia.

No n8n, substitua valores fixos por expressões dos campos criados antes somente depois de cruzar cada campo com a referência vigente. Assim, o fluxo separa regra de negócio e credencial sem prometer compatibilidade com um modelo que pode ter mudado.

Registro de conferência editorial em 4 de agosto de 2026

A página pública de preços da PiAPI respondeu nesta data e atualizou o trecho de custos. A documentação técnica em docs.piapi.ai não resolveu no ambiente de redação.

Sem API key de teste e sem a referência técnica acessível, não houve criação de task, task_id, status, asset, tempo medido ou custo próprio a registrar. Essa limitação torna o post um guia conceitual.

Antes de publicar ou executar, registre data da consulta, endpoint, header, payload, task_id, estado final, URL do asset, duração e custo efetivo.

Separe prompt, modelo e provider

Inclua também media_provider. Mesmo que o primeiro provider seja PiAPI, esse campo evita lock-in no desenho do workflow. Se uma task falhar repetidamente, você poderá redirecionar a próxima tentativa para outra rota sem reconstruir toda a automação.

O hub simplifica a entrada, mas adiciona uma camada entre seu workflow e o modelo original. Isso é vantajoso para protótipos e fluxos multimodais. Em operações críticas, registre provider, modelo e versão do payload em cada job. Esse histórico torna uma troca futura menos dolorosa.

Imagem, vídeo e áudio: o que conferir por modalidade

Os exemplos abaixo são moldes de estrutura. Eles mostram como organizar uma chamada, não substituem a referência atual da API. Os nomes de modelos, task_type e parâmetros precisam ser validados na sua conta antes de executar.

Molde 1: imagem

Para imagem, o fluxo costuma receber prompt, proporção e, quando suportado pelo modelo, referências visuais. Comece com poucas variáveis. Isso ajuda a descobrir se uma variação de resultado vem do prompt ou da configuração.

No seu teste, registre o identificador do modelo escolhido, prompt, proporção, parâmetros opcionais e a resposta recebida. Essa comparação mostra se uma mudança de saída veio do prompt, da configuração ou do próprio modelo.

Guarde o prompt usado, a proporção e a URL final. Quando alguém pedir uma nova versão, você terá base para comparar a saída em vez de começar do zero.

Molde 2: vídeo curto

Vídeo exige mais controle de custo. Na referência de Seedance 2.0 usada na pesquisa, cinco segundos no modo fast equivaleriam a US$ 0,50, ou R$ 2,75 na cotação operacional adotada. A duração, resolução e modelo podem alterar o preço e a disponibilidade.

No teste de vídeo, confirme na documentação os campos de prompt, duração, resolução e modelo. Registre o custo por tentativa e o tempo até o estado final. São esses dados que revelam se a rota cabe no orçamento, não um exemplo estático.

Não prometa uma latência fixa ao usuário final. Mídia generativa é naturalmente assíncrona e a fila pode mudar. Defina um timeout no n8n e devolva um status controlado se o processamento superar esse limite.

Molde 3: áudio ou música

Para áudio, defina claramente duração, presença de vocal e estilo. Se o destino for um vídeo comercial, registre também direitos de uso e a política atual do modelo. No teste, confirme o identificador vigente e os campos aceitos para duração, vocal e estilo.

O identificador do modelo deve vir do catálogo disponível na sua conta. Não leve um fluxo para produção sem essa conferência.

Como planejar task_id, polling e resultado final

Muitas APIs de mídia devolvem um identificador de task antes de entregar o asset. Se a referência vigente da PiAPI usar task_id, salve-o logo após a criação. Ele será a chave para consultar status, diagnosticar erro e evitar que a mesma solicitação seja criada duas vezes.

A sequência recomendada no n8n é:

Webhook ou Manual Trigger
→ Set/Edit Fields
→ HTTP Request: criar task
→ salvar task_id
→ Wait de 10 a 30 segundos
→ HTTP Request: consultar task pela rota vigente
→ IF estado final de sucesso: salvar asset e responder
→ IF estado final de falha ou timeout: fallback ou erro controlado

Use Wait entre consultas. A documentação do n8n recomenda configurar Retry On Fail e Wait Between Tries para lidar com rate limits. Isso não significa repetir indefinidamente. Limite quantidade de tentativas, tempo total e custo máximo por job.

Quando houver sucesso, a API pode devolver uma URL, não o arquivo em si. Nesse caso, faça download e salve o asset em um storage estável antes de enviar a resposta ao cliente ou alimentar outro node. A documentação de dados binários no n8n ajuda a estruturar essa etapa.

Como saber se o seu teste funcionou

Não use o desenho do node como prova. Registre uma execução real, datada, em uma planilha ou banco de logs. O teste só está completo quando você consegue apontar: o identificador retornado pela API, cada estado observado, a URL ou o arquivo final, o tempo entre criação e conclusão, o custo debitado e qualquer erro. Se a documentação usar nomes de campos diferentes, guarde a resposta bruta mascarando segredos. Sem esses seis itens, trate o workflow como não validado.

O que fazer quando falhar

Primeiro, classifique o erro pelo retorno documentado: autenticação, payload inválido, limite, processamento ou timeout. Erro de autenticação pede revisão da credencial; repetir em outro provider não resolve. Em timeout ou indisponibilidade, aplique o teto de tentativas e avalie fallback. Não cobre do cliente um job até ter asset salvo, custo registrado e estado final rastreável.

PiAPI vs Kie.ai, WaveSpeedAI, Replicate e OpenRouter

PiAPI não precisa vencer em todas as categorias para ser útil. A proposta mais interessante é servir como hub de acesso multimodal quando integrar vários serviços isolados seria caro em tempo de desenvolvimento.

A página da PiAPI sobre Kling reconhece um ponto importante: para modelos sem API pública oficial, a camada intermediária pode abrir acesso e também aumentar o risco de mudança. Isso não invalida a ferramenta. Apenas exige fallback e expectativa realista.

Para comparar uma rota de custo multimodal, consulte a oferta de Kie.ai no Runzos. Se a necessidade evoluir para GPU, controle de runtime ou infraestrutura própria, a rota correta é RunPod pelo Runzos, não um hub de API por conveniência.

Workflow de produção: retry, cache, fallback e logs

Um protótipo precisa criar a task. Produção precisa evitar duplicação e ter rastreabilidade. Use esta checklist antes de liberar o workflow:

• API key guardada em credencial ou variável, nunca em texto aberto.
• Endpoint e campos validados na documentação atual da PiAPI.
• media_type, model, task_type e prompt separados.
• prompt_hash usado para localizar jobs idênticos.
• task_id salvo antes do polling.
• Polling com timeout e número máximo de consultas.
• Retry com espera, sem loop infinito.
• Fallback definido por modalidade e erro.
• Asset final salvo antes de responder.
• Custo estimado, tentativas e status registrados.
• Logs sem dados pessoais ou segredos.

O cache por prompt_hash ajuda em dois cenários: o usuário clica duas vezes e um webhook é reenviado. Em ambos, o workflow deve reutilizar uma tarefa em andamento ou um resultado já aprovado, quando isso fizer sentido para seu produto.

O fallback não deve ser automático para qualquer erro. Um 401 indica problema de credencial. Repetir em outro provider não resolve. Já um timeout ou indisponibilidade pode justificar outra rota. Separe erros de autenticação, validação, rate limit e processamento antes de gastar em uma nova geração.

Quando usar PiAPI e quando não usar

Use PiAPI quando variedade e velocidade de integração têm mais valor que falar diretamente com cada modelo. Ela tende a fazer sentido para protótipos, automações de conteúdo e produtos que combinam modalidades diferentes em uma única fila.

Não use como resposta automática para tudo. Para LLM puro, OpenRouter é mais alinhado ao problema. Para um modelo open-source específico, Replicate pode ser a escolha natural. Para exigência de infraestrutura e controle de execução, WaveSpeedAI ou uma rota de GPU podem encaixar melhor.

A posição editorial do Runzos é objetiva: PiAPI é um hub prático, não uma garantia de menor preço, uptime ou disponibilidade permanente. Escolha pela dificuldade de acesso ao modelo, pelo custo por resultado aprovado e pela facilidade de trocar de provider depois.

Problemas comuns e como resolver

401 ou 403 de API key

Revise se o header está sendo preenchido pela credencial certa e se a chave pertence ao ambiente correto. Não coloque a chave diretamente no node para “testar rápido”. Isso cria vazamento no histórico do workflow.

Task nunca termina

Confira o status retornado, limite o polling e registre o payload. Se houver timeout, encerre o job com mensagem controlada. Uma task que demora não é motivo para deixar o n8n consultar a API para sempre.

Resultado vem como URL, não como arquivo

Baixe o asset e armazene-o antes de continuar o fluxo. Uma URL temporária pode não ser um link de entrega confiável. Trabalhe com binários quando a etapa seguinte exigir upload ou anexos.

Custo ficou maior que o esperado

Olhe quantidade de tentativas, duração do vídeo, modelo e jobs duplicados. Depois ajuste o teto de custo, o cache e os critérios de aprovação. A métrica correta não é só custo unitário: é custo por mídia aprovada.

FAQ

O que é PiAPI?

PiAPI é um hub de APIs de IA generativa para acessar modelos de imagem, vídeo, áudio, 3D e LLM por uma camada de API. Consulte o site oficial da PiAPI para catálogo e disponibilidade atual.

PiAPI funciona com n8n?

Sim. O n8n pode chamar APIs REST pelo node HTTP Request. A PiAPI também tinha sinais públicos de integrações e workflows com n8n, mas usar HTTP Request mantém o fluxo independente de um template específico.

Como tratar uma resposta assíncrona no n8n?

Salve o task_id, aguarde com um node Wait e consulte o status com outro HTTP Request. Defina máximo de consultas, timeout e tratamento explícito para sucesso, falha e rate limit.

Quanto custa gerar vídeo com PiAPI?

Depende do modelo, duração, resolução e plano. Na referência de pesquisa, Seedance fast custava US$ 0,10 por segundo, mas preços de mídia generativa são dinâmicos. Confira a tabela de preço vigente antes de precificar um produto.

PiAPI é melhor que Kie.ai?

Depende do objetivo. PiAPI é interessante quando acesso e variedade de modelos pesam. Kie.ai pode ser comparada quando custo multimodal é prioridade. Faça um teste de amostra com o mesmo prompt e meça custo por mídia aprovada.

Posso usar PiAPI como único provider em produção?

Pode, mas não é a arquitetura mais resiliente. Mantenha provider, modelo e payload desacoplados; registre falhas; e defina uma alternativa para erros que façam sentido tratar com fallback.

Conclusão: PiAPI no n8n vale a pena?

PiAPI no n8n vale para quem quer uma Fila Multimodal sem abrir contas e integrar SDKs diferentes para cada mídia. O valor está em centralizar tasks, não em prometer que qualquer geração será barata ou instantânea.

Comece com uma modalidade, um teto de custo e polling limitado. Depois adicione cache, logs e fallback. Se esse modelo combina com sua automação, teste a PiAPI pela oferta do Runzos e valide um workflow pequeno antes de escalar.