Como usar o Apiframe no n8n (guia passo a passo)

Neste guia, você vai aprender como conectar Apiframe ao n8n para gerar imagens de IA (ou vídeos, músicas etc.) a partir de qualquer workflow.

Vamos ver:

1. O que vamos construir
2. Pré-requisitos
3. Criando credenciais do Apiframe no n8n
4. Workflow 1 - Geração simples de imagem usando /imagine
5. Workflow 2 - Buscar resultados com /fetch
6. Workflow 3 - Recomendado: Usando webhooks para resultados em tempo real
7. Estendendo o padrão para outros endpoints do Apiframe

Todos os exemplos vão usar o endpoint Midjourney /imagine , mas o mesmo padrão funciona para a maioria dos outros endpoints e modelos.

I. O que vamos construir

Vamos criar duas pequenas integrações no n8n:

1. Gerar uma imagem sob demanda
   • Disparo: Manual, Webhook, Google Sheets, qualquer coisa
   • HTTP Request: POST https://api.apiframe.pro/imagine
   • Receber de volta um task_id que você pode armazenar ou registrar
2. Obter as imagens finais automaticamente
   • Fazendo polling no Apiframe com /fetch até a tarefa ser concluída
   • Ou (recomendado) deixar o Apiframe chamar um Webhook do n8n quando a tarefa for concluída

Depois que as URLs das imagens chegarem ao n8n, você pode fazer qualquer coisa: enviar para o Slack, armazenar no Airtable, Google Drive, etc.

II. Pré-requisitos

Você vai precisar de:

• Uma conta Apiframe e uma chave de API. Você pode obtê-la no seu painel do Apiframe (ou Clique aqui). Essa chave de API será usada para autenticar nossas requisições por meio do cabeçalho Authorization .

• Uma instância do n8n (self-hosted ou na nuvem)
• Familiaridade básica com os nodes do n8n (HTTP Request, Webhook, Set, IF, etc.). O node HTTP Request é a forma genérica de chamar qualquer API REST no n8n.

III. Criar credenciais do Apiframe no n8n

Vamos configurar as credenciais uma vez e depois reutilizá-las em todos os nodes HTTP Request.

• Passo 1: No n8n, vá até Credentials → Create credential.

• Passo 2: Escolha Header Auth (ou "HTTP Header Auth", "API Key in Header", dependendo da sua versão)

• Passo 3: Configure:
  • Nome do cabeçalho: Authorization
  • Valor: sua chave de API do Apiframe (exatamente como aparece no seu painel)

• Passo 4: Dê um nome como Apiframe Auth e salve

O Apiframe espera:

Authorization: YOUR_API_KEY
Content-Type: application/json

IV. Workflow 1 - Geração básica de imagem com /imagine

Vamos construir um workflow simples:

1. Crie o workflow

1. No n8n, crie um New workflow.
2. Adicione um Manual Trigger node.

2. Adicione um nó "Set" para o prompt

1. Adicione um Set após o Manual Trigger.
2. Em Values → Add Field → String:
   • Name: prompt
   • Value: algo como a cinematic photo of a cyberpunk city at night, ultra detailed, 4k
3. (Opcional) Adicione outro campo do tipo string:
   • Name: aspect_ratio
   • Value: 3:2

Agora o JSON de saída do nó Set fica aproximadamente assim:

{
  "prompt": "a cinematic photo of a cyberpunk city at night, ultra detailed, 4k",
  "aspect_ratio": "3:2"
}

3. Adicione o nó HTTP Request para /imagine

1. Adicione um HTTP Request após o nó Set.
2. Configure:
   • Method: POST
   • URL: https://api.apiframe.pro/imagine
   • Para autenticação, escolha o "Generic Credential type", depois "Header Auth" e então as credenciais “Apiframe Auth” que você criou anteriormente.
   • No corpo, ative "Send body" e vamos adicionar nossos campos: prompt, aspect_ratio e, opcionalmente, webhook_url para mais tarde.

Quando você executar este nó, o Apiframe retorna algo como:

{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a"
}

Isso significa que a tarefa está na fila/em processamento. As imagens são geradas de forma assíncrona; você não recebe as URLs finais a partir do /imagine em si.

Agora você pode:

• Registrar o task_id
• Armazene-o em um BD / Google Sheets
• Passe-o adiante para um workflow de “Fetch”

V. Workflow 2 - Fazendo polling no Apiframe com /fetch

Agora vamos obter as URLs reais das imagens usando o endpoint /fetch.

O Apiframe expõe o endpoint POST https://api.apiframe.pro/fetch, que recebe um task_id e retorna ou o resultado final ou uma resposta com status: "processing".

Vamos criar um fluxo mínimo de “Esperar e depois Buscar” (Wait then Fetch).

1. Adicione um nó Wait

Após o nó /imagine de HTTP Request:

1. Adicione um nó Wait.
2. Configure-o para esperar, por exemplo, de 2–3 segundos.

Isso dá tempo para o Apiframe finalizar a geração. O tempo de geração depende da complexidade da tarefa e da carga do sistema.

2. Adicione o nó HTTP Request para /fetch

Adicione outro nó HTTP Request após o nó Wait:

• Método: POST
• URL: https://api.apiframe.pro/fetch
• Para autenticação, selecione o "Generic Credential type", depois "Header Auth" e então “Apiframe Auth”, como antes.
• Para o corpo, ative "Send body" e vamos adicionar o nosso task_id campo

Processing (tarefa ainda em execução):

{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "status": "processing",
  "percentage": "40"
}

Completed (tarefa concluída, URLs das imagens prontas):

{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "original_image_url": "https://.../grid.png",
  "image_urls": [
    "https://.../image1.png",
    "https://.../image2.png",
    "https://.../image3.png",
    "https://.../image4.png"
  ]
}

3. Lidando com “still processing”

Para uma configuração rápida de desenvolvimento, você pode:

• Apenas esperar mais tempo e buscar uma vez só.
• Ou adicionar um nó IF simples depois do Fetch:
  • Condição: status igual a "processing"
  • Se “true”: ramificar para outro Wait + Fetch
  • Se “false”: continuar com a sua lógica final (Slack, Airtable, etc.)

Em produção, o Apiframe recomenda usar webhooks em vez de polling para evitar requisições desnecessárias e receber atualizações instantâneas.

Vamos fazer isso agora.

VI. Workflow 3 - Resultados baseados em webhook (recomendado)

Esta é a arquitetura limpa e “em tempo real”:

• Workflow A: Enviar requisição de geração (com webhook_url e webhook_secret)
• Workflow B: Receber webhook do Apiframe quando a geração for concluída

1. Criar o Workflow B - O receptor de webhook

1. Crie um Novo workflow no n8n e dê a ele o nome de Apiframe – Imagem concluída.
2. Adicione um Webhook node. Configure o nó Webhook:
   • Método HTTP: POST
   • Path: algo como apiframe/midjourney-completed
   • Modo de resposta:
     • Por exemplo, When Last Node Finishes (assim você pode retornar dados de volta se quiser).

Copie a Production URL – é isso que vamos definir como webhook_url no Apiframe.

2. Proteja o webhook com "webhook_secret"

O Apiframe permite que você envie um webhook_secret na requisição /imagine; ele o enviará de volta como cabeçalho x-webhook-secret nas chamadas de webhook.

1. Adicione um nó IF depois do nó Webhook.
2. No nó IF, verifique:
   • Lado esquerdo: Expressão como ={{ $json["headers"]["x-webhook-secret"] }}
   • Condição: equals
   • Lado direito: o seu segredo, por exemplo my-super-secret
3. Se o segredo não corresponder, vá para um ramo que apenas termina (ou registra a tentativa).

Isso garante que somente os webhooks do Apiframe sejam processados.

3. Acessando as URLs das imagens no payload do webhook

O corpo do webhook terá o mesmo formato do payload de “completed” mostrado antes:

{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "original_image_url": "https://.../grid.png",
  "image_urls": [
    "https://.../image1.png",
    "https://.../image2.png",
    "https://.../image3.png",
    "https://.../image4.png"
  ]
}

Você pode acessar as URLs das imagens e então passá‑las para:

• Nó do Slack (enviar uma mensagem com a URL)
• Airtable / Notion (armazenar a URL)
• HTTP Request (enviar para o backend do seu app)

4. Atualizar o Workflow A para usar o webhook

Volte para o Workflow A (aquele que chama /imagine) e edite o corpo do nó HTTP Request para incluir:

• webhook_url
• webhook_secret

Exemplo de corpo JSON no nó HTTP Request:

{
  "prompt": "a cinematic photo of a cyberpunk city at night, ultra detailed, 4k",
  "aspect_ratio": "3:2",
  "webhook_url": "https://your-n8n-domain.com/webhook/apiframe/midjourney-completed",
  "webhook_secret": "my-super-secret"
}

Agora o fluxo é:

1. Workflow A → /imagine com webhook_url + webhook_secret
2. O Apiframe gera a imagem em segundo plano
3. Quando terminar, o Apiframe chama o seu Webhook (Workflow B) com as URLs finais
4. O Workflow B processa essas URLs e as envia para onde você quiser

Sem polling, sem requisições HTTP extras – apenas orientado a eventos.

VII. Estendendo esse padrão para outros endpoints do Apiframe

A parte boa: depois de conectar n8n → Apiframe uma vez, você pode reutilizar o mesmo padrão para tudo.

Algumas ideias:

• Variações: mude a URL para https://api.apiframe.pro/variations e envie o task_id + novo prompt.
• Upscales: mesma autenticação, endpoint/corpo diferentes.
• Faceswap: envie duas URLs de imagem (origem e destino) para o endpoint faceswap .
• Describe: crie um workflow no n8n em que você envia a URL de uma imagem e o Apiframe retorna um prompt para ela.
• Outras mídias: Flux, Ideogram, Luma, Suno etc. seguem todos o mesmo padrão REST: POST com JSON, inclua webhook_url + webhook_secret se quiser usar webhooks.

Cada um desses se torna apenas mais um nó HTTP Request (ou dois, se você também usar o /fetch) usando as mesmas credenciais de “Apiframe Auth”.

VIII. Encerramento

Agora você tem:

• Um workflow básico de /imagine para acionar o Midjourney via Apiframe no n8n
• Uma configuração de polling usando /fetch para experimentos rápidos
• Uma arquitetura baseada em webhook para pipelines em tempo real, em nível de produção