Come usare Apiframe in n8n (guida passo per passo)

In questa guida imparerai come collegare Apiframe a n8n così da poter generare immagini (o video, musica, ecc.) con l’AI da qualsiasi workflow.

Vedremo:

1. Cosa andremo a costruire
2. Prerequisiti
3. Creare le credenziali Apiframe in n8n
4. Workflow 1 - Generazione di immagini semplice usando /imagine
5. Workflow 2 - Polling dei risultati con /fetch
6. Workflow 3 - Consigliato: Uso dei webhook per risultati in tempo reale
7. Estendere questo schema ad altri endpoint di Apiframe

Tutti gli esempi useranno l’endpoint Midjourney /imagine ma lo stesso schema funziona per la maggior parte degli altri endpoint e modelli.

I. Cosa andremo a costruire

Costruiremo due piccole integrazioni con n8n:

1. Generare un’immagine su richiesta
   • Trigger: Manuale, Webhook, Google Sheet, qualsiasi cosa
   • HTTP Request: POST https://api.apiframe.pro/imagine
   • Ricevi un task_id che puoi salvare o loggare
2. Ottenere automaticamente le immagini finali
   • Facendo polling su Apiframe con /fetch finché il task non è completato
   • Oppure (consigliato) lasciare che Apiframe chiami un Webhook di n8n quando il task è completato

Una volta che gli URL delle immagini arrivano in n8n, puoi fare qualsiasi cosa: inviarli su Slack, salvarli in Airtable, Google Drive, ecc.

II. Prerequisiti

Ti serviranno:

• Un account Apiframe e una chiave API. Puoi recuperarla dalla tua dashboard Apiframe (oppure clicca qui). Questa chiave API verrà usata per autenticare le nostre richieste tramite l’header Authorization .

• Un’istanza n8n (self-hosted o cloud)
• Familiarità di base con i nodi di n8n (HTTP Request, Webhook, Set, IF, ecc.). Il nodo HTTP Request è il modo generico per chiamare qualsiasi REST API in n8n.

III. Creare le credenziali Apiframe in n8n

Configuriamo le credenziali una sola volta, poi le riutilizzeremo in tutti i nodi HTTP Request.

• Passaggio 1: In n8n, vai su Credentials → Create credential.

• Passaggio 2: Scegli Header Auth (oppure "HTTP Header Auth", "API Key in Header" a seconda della tua versione)

• Passaggio 3: Configura:
  • Nome dell’header: Authorization
  • Valore: la tua Apiframe API key (esattamente come mostrata nella tua dashboard)

• Passaggio 4: Assegna un nome, ad esempio Apiframe Auth e salva

Apiframe si aspetta:

Authorization: YOUR_API_KEY
Content-Type: application/json

IV. Workflow 1 - Generazione di immagini di base con /imagine

Costruiremo un workflow semplice:

1. Crea il workflow

1. In n8n, crea un New workflow.
2. Aggiungi un Manual Trigger node.

2. Aggiungi un nodo "Set" per il prompt

1. Aggiungi un Set node dopo il Manual Trigger.
2. In Values → Add Field → String:
   • Name: prompt
   • Value: qualcosa tipo a cinematic photo of a cyberpunk city at night, ultra detailed, 4k
3. (Opzionale) Aggiungi un altro campo stringa:
   • Name: aspect_ratio
   • Value: 3:2

Ora l'output JSON del nodo Set appare più o meno così:

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

3. Aggiungi il nodo HTTP Request per /imagine

1. Aggiungi un HTTP Request node dopo il nodo Set.
2. Configura:
   • Method: POST
   • URL: https://api.apiframe.pro/imagine
   • Per l'autenticazione, scegli "Generic Credential type", poi "Header Auth", quindi le credenziali “Apiframe Auth” che hai creato in precedenza.
   • Per il body, attiva "Send body" e aggiungiamo i nostri campi: prompt, aspect_ratio e opzionalmente webhook_url per dopo.

Quando esegui questo nodo, Apiframe restituisce qualcosa del genere:

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

Questo significa che il task è in coda/in elaborazione. Le immagini vengono generate in modo asincrono; non ottieni gli URL finali da /imagine stesso.

Ora puoi:

• Registrare il task_id
• Conservalo in un database / Google Sheet
• Passalo a un workflow di “Fetch”

V. Workflow 2 - Polling di Apiframe con /fetch

Ora recuperiamo le effettive URL delle immagini usando l’endpoint /fetch .

Apiframe espone un endpoint POST https://api.apiframe.pro/fetch che accetta task_id e restituisce o il risultato finale oppure una risposta con status: "processing".

Imposteremo un flusso minimale “Wait then Fetch” (attendi e poi fai fetch).

1. Aggiungi un nodo Wait

Dopo il nodo HTTP Request /imagine:

1. Aggiungi un nodo Wait.
2. Imposta un’attesa, ad esempio, di 2–3 secondi.

Questo dà ad Apiframe il tempo di terminare la generazione. Il tempo di generazione dipende dalla complessità del task e dal carico di sistema.

2. Aggiungi il nodo HTTP Request per /fetch

Aggiungi un altro nodo HTTP Request dopo il nodo Wait:

• Method: POST
• URL: https://api.apiframe.pro/fetch
• Per l’autenticazione, scegli “Generic Credential type”, poi “Header Auth”, quindi “Apiframe Auth”, come prima.
• Per il body, attiva “Send body” e aggiungiamo il nostro task_id field

In elaborazione (job ancora in corso):

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

Completato (job concluso, URL delle immagini pronti):

{
  "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. Gestire il caso "ancora in elaborazione"

Per un setup veloce in fase di sviluppo, puoi:

• Semplicemente aspettare di più e fare il fetch una sola volta.
• Oppure aggiungere un semplice nodo IF dopo il Fetch:
  • Condizione: status uguale a "processing"
  • Se "true": ramifica verso un altro Wait + Fetch
  • Se "false": continua con la tua logica finale (Slack, Airtable, ecc.)

In produzione, Apiframe consiglia di usare webhook invece del polling per evitare richieste inutili e ottenere aggiornamenti istantanei.

Facciamolo subito.

VI. Workflow 3 - Risultati basati su webhook (consigliato)

Questa è l’architettura pulita e "real-time":

• Workflow A: Invia la richiesta di generazione (con webhook_url e webhook_secret)
• Workflow B: Riceve il webhook da Apiframe quando la generazione è terminata

1. Crea il Workflow B - Il ricevitore del webhook

1. Crea un Nuovo workflow in n8n e chiamalo Apiframe – Immagine completata.
2. Aggiungi un Webhook node. Configura il nodo Webhook:
   • Metodo HTTP: POST
   • Percorso: qualcosa come apiframe/midjourney-completed
   • Modalità di risposta:
     • Ad esempio, When Last Node Finishes (così puoi restituire dei dati se vuoi).

Copia la Production URL – questo è ciò che imposteremo come webhook_url in Apiframe.

2. Metti al sicuro il webhook con "webhook_secret"

Apiframe ti permette di passare un webhook_secret nella richiesta /imagine; lo rimanderà indietro come intestazione x-webhook-secret nelle chiamate webhook.

1. Aggiungi un nodo IF dopo il nodo Webhook.
2. Nel nodo IF, controlla:
   • Lato sinistro: un’espressione come ={{ $json["headers"]["x-webhook-secret"] }}
   • Condizione: equals
   • Lato destro: il tuo secret, ad es. my-super-secret
3. Se il secret non corrisponde, vai a un ramo che si limita a terminare (o registra solo il tentativo).

In questo modo ti assicuri che vengano elaborati solo i webhook di Apiframe.

3. Accedere agli URL delle immagini nel payload del webhook

Il body del webhook avrà lo stesso aspetto del payload "completed" mostrato in precedenza:

{
  "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"
  ]
}

Puoi accedere agli URL delle immagini e poi passarli a:

• nodo Slack (invia un messaggio con l’URL)
• Airtable / Notion (salva l’URL)
• HTTP Request (inoltra al backend della tua app)

4. Aggiorna il Workflow A per usare il webhook

Torna al Workflow A (quello che chiama /imagine) e modifica il body del nodo HTTP Request per includere:

• webhook_url
• webhook_secret

Esempio di body JSON nel nodo 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"
}

Ora il flusso è:

1. Workflow A → /imagine con webhook_url + webhook_secret
2. Apiframe genera l’immagine in background
3. Quando ha finito, Apiframe chiama il tuo Webhook (Workflow B) con gli URL finali
4. Il Workflow B li elabora e li inoltra ovunque tu voglia

Nessun polling, nessuna richiesta HTTP extra: tutto event-driven.

VII. Estendere questo pattern ad altri endpoint di Apiframe

La parte interessante: una volta che hai collegato n8n → Apiframe una volta, puoi riutilizzare lo stesso pattern per tutto.

Alcune idee:

• Variazioni: cambia l’URL in https://api.apiframe.pro/variations e invia il task_id + nuovo prompt.
• Upscale: stessa autenticazione, endpoint/body diversi.
• Faceswap: invia due URL di immagini (sorgente e destinazione) all’endpoint faceswap .
• Describe: crea un workflow n8n in cui inserisci un URL di immagine e Apiframe restituisce un prompt per quell’immagine.
• Altri media: Flux, Ideogram, Luma, Suno, ecc. seguono tutti lo stesso pattern REST: POST con JSON, includendo webhook_url + webhook_secret se vuoi usare i webhook.

Ognuno di questi diventa semplicemente un altro nodo HTTP Request (o due, se usi anche /fetch) che utilizza le stesse credenziali “Apiframe Auth”.

VIII. Conclusione

Ora hai:

• Un workflow /imagine di base per attivare Midjourney tramite Apiframe in n8n
• Una configurazione di polling che utilizza /fetch per esperimenti rapidi
• Un’architettura basata su webhook per pipeline in tempo reale di livello production