Uma configuração prática para gerar imagens no n8n com uma API gratuita. Crie o token, salve-o como credencial, monte o POST, o loop de consulta com Wait e Switch, salve o arquivo e mantenha os lotes dentro do limite de cinco tarefas para que execuções em massa terminem sem erros.
Você consegue conectar uma API gratuita de geração de imagens ao n8n em cerca de vinte minutos, e a parte que costuma dar problema não é a requisição. É a espera. As tarefas de imagem na API da PicassoIA são assíncronas, então um único nó HTTP Request devolve um ID de tarefa em vez de uma imagem, e tudo o que vem depois depende de quão bem você faz a consulta, as novas tentativas e o salvamento do resultado. Este passo a passo monta o fluxo completo: um gatilho, um prompt, um POST que cria a predição, um par Wait e IF que consulta até a tarefa terminar, e uma etapa de download que transforma a saída em um arquivo real dentro do seu fluxo.
Se você já usou a API do Replicate, vai se sentir em casa. Se não usou, tudo bem também: cada chamada deste artigo mostra a URL, o cabeçalho e o corpo exatos de que você precisa, além das expressões do n8n que conectam os nós.
A PicassoIA expõe uma API para desenvolvedores que funciona como a API de predições do Replicate. Você cria uma tarefa, consulta o status e lê a saída. Não há streaming nem callback por webhook para configurar, o que é, na verdade, uma boa notícia para o n8n, porque consultar é algo que o editor faz muito bem.
A URL base é https://api.picassoia.com/v1, e cada requisição leva um token bearer que começa com pia_sk_. Quatro endpoints cuidam de todo o ciclo de vida de uma tarefa:
| Ação | Método e caminho | Para que você usa |
|---|---|---|
| Criar uma tarefa | POST /v1/models/{owner}/{name}/predictions | Iniciar uma geração |
| Consultar uma tarefa | GET /v1/predictions/{id} | Consultar o status e ler a saída |
| Cancelar uma tarefa | POST /v1/predictions/{id}/cancel | Parar uma tarefa que você não precisa mais |
| Listar tarefas | GET /v1/predictions | Auditar execuções recentes |
Para imagens estáticas, dois modelos importam. picassoia/picassoia-image é o modelo de texto para imagem, documentado na página PicassoIA Image. Ele é ilimitado, oferece sete proporções, aceita uma seed e gera saída em JPG, PNG ou WebP. picassoia/picassoia-image-editor-pro cuida de edições em imagens existentes e fica em PicassoIA Image Editor Pro. Dois modelos de vídeo seguem o mesmo estilo de endpoint, o que se torna útil quando seu fluxo de imagens já está estável e você quer movimento a partir do mesmo gatilho.
Antes de desenhar qualquer coisa, anote estes números em um post-it:
O limite de simultaneidade molda seu fluxo mais do que qualquer outra coisa. Voltaremos a ele na seção de falhas, porque uma planilha com 200 linhas ultrapassa cinco tarefas em cerca de dois segundos se você deixar.
💡 Confira seu plano antes de prometer "gratuito" a um cliente. As páginas da API dizem que as predições estão atualmente gratuitas e não usam créditos, mas a documentação também menciona um plano Infinite para acesso à API, e a página de preços lista o acesso à API em vários níveis. Essas afirmações não batem perfeitamente, então confirme o que a sua conta permite antes de montar uma entrega para cliente com base nisso.
Execute seu prompt no navegador primeiro. Não custa nada, leva dez segundos e mostra se a redação está certa antes de você passar uma tarde depurando nós.
Os campos do navegador correspondem um a um ao corpo da requisição, então nada se perde na tradução:
| Campo | Padrão | Observações |
|---|---|---|
prompt | nenhum (obrigatório) | Descrição em linguagem simples, até 4.000 caracteres |
aspect_ratio | 1:1 | Também 16:9, 9:16, 4:3, 3:4, 3:2 e 2:3 |
seed | aleatória | Inteiro, defina para uma saída repetível |
output_format | jpg | jpg, png ou webp |
output_quality | 80 | De 0 a 100, vale apenas para JPG e WebP |
num_outputs | 1 | Uma ou duas imagens por chamada |
💡 Escrever quarenta prompts à mão cansa rápido. Rascunhe variações em um modelo de chat como GPT 5 Mini ou Claude 4.5 Haiku, guarde as melhores e cole na planilha que o seu fluxo lê.
A maioria das configurações falha aqui, não no fluxo. Dedique dois minutos a isto e você não vai mais pensar em autenticação.
Abra a página da API na sua conta da PicassoIA e crie um token. Ele vai começar com pia_sk_. Copie-o imediatamente para um gerenciador de senhas. Como uma conta tem no máximo dois tokens, use um para o n8n de produção e guarde o segundo para testes locais, assim você pode revogar qualquer um sem quebrar o outro.
Teste-o pelo terminal antes de envolver o n8n:
curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
-H "Authorization: Bearer $PICASSOIA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input":{"prompt":"Ceramic mug on linen, window light from the left, 50mm","aspect_ratio":"16:9"}}'
Uma resposta JSON com um id significa que o token funciona. Consulte com GET https://api.picassoia.com/v1/predictions/<id> até o status mostrar succeeded, depois observe a estrutura do campo output. Você vai precisar dessa estrutura em um minuto.
No n8n, abra Credentials, crie uma nova credencial Header Auth e preencha assim:
AuthorizationBearer pia_sk_ seguido do seu token, com um único espaço depois de "Bearer"PicassoIA APINunca cole o token em um nó Set nem direto em um campo do HTTP Request. Ele acaba nos logs de execução e em qualquer fluxo que você exporte ou compartilhe. Uma credencial salva fica fora dos dois. Em uma instância self-hosted você também pode injetá-lo por variável de ambiente, mas o armazenamento de credenciais é mais simples e basta para a maioria das equipes.
Aqui está a estrutura completa. Oito nós, um loop:
| # | Nó | Função |
|---|---|---|
| 1 | Schedule Trigger ou Webhook | Inicia a execução |
| 2 | Edit Fields (Set) | Guarda prompt, proporção e formato |
| 3 | HTTP Request (POST) | Cria a predição |
| 4 | Wait | Pausa por alguns segundos |
| 5 | HTTP Request (GET) | Lê o status da tarefa |
| 6 | Switch ou IF | Direciona por succeeded, failed ou "ainda rodando" |
| 7 | HTTP Request (GET, arquivo) | Baixa a imagem pronta |
| 8 | Drive, S3 ou Write Files | Armazena onde você precisar |
Comece com um Schedule Trigger se o trabalho for rotineiro, ou com um Webhook se outra ferramenta precisar poder pedir imagens. Depois coloque um nó Edit Fields que defina três campos de texto: prompt, aspect_ratio e output_format. Mantê-los em um único nó significa mudar uma configuração uma vez, não em cinco lugares.
Adicione um nó HTTP Request e dê a ele o nome Create prediction. Defina o método como POST e a URL como https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions. Em autenticação, escolha Generic Credential Type, depois Header Auth e sua credencial PicassoIA API. Ative Send Body, escolha JSON e use este corpo:
{
"input": {
"prompt": "{{ $json.prompt }}",
"aspect_ratio": "{{ $json.aspect_ratio }}",
"output_format": "{{ $json.output_format }}",
"num_outputs": 1
}
}
Se seus prompts puderem conter aspas ou quebras de linha, monte o corpo como uma expressão: {{ JSON.stringify({ input: { prompt: $json.prompt, aspect_ratio: $json.aspect_ratio, output_format: $json.output_format, num_outputs: 1 } }) }}. Essa única mudança evita o erro clássico de "invalid JSON" em prompts como a sign that says "OPEN".
A resposta inclui o id da tarefa. É o único valor de que o restante do fluxo realmente precisa.
Adicione um nó Wait configurado para retomar após um intervalo de tempo, cinco segundos para começar. Depois, um segundo nó HTTP Request chamado Check prediction, com o método GET e esta URL:
https://api.picassoia.com/v1/predictions/{{ $('Create prediction').item.json.id }}
Leve o resultado para um nó Switch que lê {{ $json.status }} e envia succeeded para a etapa de download, failed para o seu ramo de erro, e todo o resto de volta ao nó Wait. Essa conexão para trás é o seu loop.
Dois hábitos mantêm o loop seguro. Primeiro, conte as tentativas. Um pequeno nó Code que incrementa um campo attempts e para em 30 vai salvar você de uma tarefa que nunca termina. Segundo, não consulte mais rápido do que o trabalho leva. Imagens ficam prontas depressa, então um intervalo de três a cinco segundos basta, e bater no endpoint de status a cada meio segundo só gasta execuções.
Agora a saída. Adicione um terceiro nó HTTP Request, método GET, com a URL apontando para o endereço da imagem na tarefa concluída. Para uma saída única isso costuma ser {{ $json.output[0] }}, mas rode o loop uma vez com um prompt de teste e confira a estrutura no painel de execução antes de confiar nessa expressão. Nas Options do nó, adicione Response, defina Response Format como File e deixe a propriedade binária como data.
A partir daqui a imagem é um arquivo binário normal do n8n. Envie para o Google Drive, S3, um endpoint de mídia do WordPress, Slack ou uma pasta local. Salve o próprio arquivo, e não o link do resultado, para que seu acervo nunca dependa de uma URL que siga ativa.
Um fluxo que funciona uma vez é uma demonstração. Um fluxo que aguenta 200 linhas numa segunda-feira de manhã é uma ferramenta. A diferença está quase toda nesta seção.
Aqui está a armadilha. A chamada POST retorna em uma fração de segundo, então um nó HTTP Request alimentado com 50 linhas vai iniciar 50 tarefas quase de imediato, muito antes de a primeira terminar. Só cinco podem rodar ao mesmo tempo, e as demais serão rejeitadas ou enfileiradas, dependendo de como a API responder.
A solução é um nó Loop Over Items com o tamanho de lote definido como 5, colocado antes da etapa de criação. Cada lote cria cinco tarefas, consulta até que as cinco estejam prontas, salva os arquivos e só então volta para o próximo grupo de cinco. Lembre que o limite é compartilhado por toda a sua conta, incluindo as conexões MCP. Se um colega estiver gerando imagens por um assistente conectado ao mesmo tempo, vocês dividem as mesmas cinco vagas.
Um status failed nem sempre é culpa sua. Direcione-o para um nó Wait curto (dez segundos funcionam), depois envie o mesmo prompt mais uma vez. Se a segunda tentativa também falhar, pare de tentar e avise alguém pelo nó Slack, Gmail ou Telegram. Tentar para sempre só esconde um prompt ruim.
Para oscilações simples de rede, abra a aba Settings do nó HTTP Request e ative Retry On Fail com três tentativas e uma pausa de dois segundos. Isso cuida de conexões caídas sem mexer na lógica do loop.
Os prompts são limitados a 4.000 caracteres. Se seus prompts vierem de entrada de usuários ou de um modelo de linguagem, corte-os em um nó Code com $json.prompt.slice(0, 4000) antes de chegarem à API. O limite de 10 MB no corpo não vai incomodar para geração de imagem só com texto, mas passa a importar quando você começar a enviar fotos de origem para o modelo de edição.
Quando algo quebrar mesmo assim, esta tabela lista os suspeitos habituais:
| Sintoma | Causa provável | Correção |
|---|---|---|
| 401 Unauthorized | Falta o prefixo Bearer ou o token está errado | Digite o valor da credencial de novo como Bearer pia_sk_... |
| Tarefas rejeitadas em execuções em massa | Mais de 5 predições ao mesmo tempo | Loop Over Items com tamanho de lote 5 |
output[0] is undefined | Saída lida antes de o status ser succeeded | Direcione apenas o ramo succeeded para o nó de download |
| Nó de download retorna JSON | Response Format deixado no padrão | Defina Response Format como File |
| Prompt rejeitado | Mais de 4.000 caracteres | Corte o prompt em um nó Code |
| Fluxo nunca termina | Sem limite de tentativas de consulta | Pare após 30 consultas e avise alguém |
Os códigos de erro exatos vêm da própria API, então abra a execução com falha e leia o corpo da resposta antes de supor qualquer coisa.
O mesmo loop serve para trabalhos bem diferentes. Troque o gatilho e o destino, mantenha o meio.
Aponte um Schedule Trigger para um nó Google Sheets que retorne linhas marcadas com todo. Monte o prompt com o título do artigo mais uma linha de estilo fixa: "fotografia documental, luz natural, 35mm, sem texto". Gere em 16:9, envie para sua biblioteca de mídia e grave a URL do arquivo de volta na linha, com o status done. Um editor pode enfileirar vinte títulos à noite e encontrar vinte cabeçalhos prontos de manhã.
Uma linha por produto, com colunas para nome, material e cenário. Gere em 1:1, defina num_outputs como 2 para poder escolher o melhor quadro, e mantenha uma seed por linha de produto para que a iluminação fique consistente em todo o catálogo. Para fotos que precisam de ajuste em uma foto existente, em vez de invenção, envie essa foto pelo modelo PicassoIA Image Editor Pro com um segundo nó HTTP Request. Confira a página do modelo para ver os campos exatos de entrada que ele espera.
Deixe um formulário, um comando do Slack ou outro fluxo chamar seu nó Webhook com um briefing curto. Use o nó Respond to Webhook para responder na hora com "recebido", depois rode a geração em segundo plano e publique a imagem 9:16 pronta no canal quando a tarefa der certo. As pessoas ficam satisfeitas porque nada trava enquanto a imagem é renderizada.
No momento em que escrevo, a API expõe quatro modelos: dois para imagens e dois para vídeo. Para o seu fluxo no n8n, o par de imagens é a decisão inteira.
| Modelo | Melhor para | Onde se encaixa no n8n |
|---|---|---|
| PicassoIA Image | Imagens novas a partir de um prompt, execuções ilimitadas | O nó padrão de Create prediction |
| PicassoIA Image Editor Pro | Alterar ou corrigir uma foto que você já tem | Um segundo ramo que recebe uma imagem de origem |
O restante do catálogo continua útil, só que não pela API hoje. Modelos como P Image e FLUX Schnell valem ser testados no navegador para comparar estilos, e a plataforma também oferece remoção de fundo, upscaling e uma grande biblioteca de efeitos de vídeo pela página de todos os modelos. Um padrão prático: teste um visual no navegador e depois reproduza o prompt e a seed vencedores no n8n.
Agora você tem tudo para um loop funcional: um token guardado com segurança, um POST que cria a tarefa, um Wait e Switch que a consultam, um download de File que salva o resultado e lotes de cinco que respeitam o limite de simultaneidade. A forma mais rápida de provar que funciona é manter a primeira versão minúscula. Um nó Edit Fields, um prompt, sem planilha, sem loop over items. Quando essa única imagem aparecer na sua pasta, acrescente os lotes e o agendamento.
Abra o PicassoIA Image no navegador, escreva um prompt sobre algo que você realmente precisa esta semana e gere. Depois copie esse prompt exato, a proporção e a seed para o fluxo do n8n descrito acima. Experimente um cabeçalho 16:9, um card de produto quadrado e um story vertical a partir do mesmo prompt e veja qual deles sua equipe usa primeiro. Tudo o que você testar está a um clique no Picasso IA, então só falta apertar o botão de executar.
Escolha seu idioma
