n8n

n8n è uno strumento di automazione dei workflow. SpicyAPI gli offre modelli di immagini, video, audio e chat dietro un’unica API e un unico saldo prepagato. Ci sono tre modi per collegarli, e si possono combinare nello stesso workflow:

Tutti e tre usano lo stesso account, la stessa chiave, gli stessi modelli e gli stessi prezzi. Per i contenuti multimediali, il nodo e i template HTTP Request verificano il prezzo prima dell’invio. Reinviare la stessa richiesta multimediale accettata con il suo Idempotency-Key originale restituisce l’attività esistente.

Per iniziare con le immagini, consulta la guida ai workflow di immagini NSFW con n8n: scelta del modello, modifica con riferimento, primo ritratto ed esempi di costo. I passaggi seguenti collegano il workflow alla tua istanza n8n.

Prima di cominciare

• Una chiave API. Creala nella console; inizia con sk-spicy-. Se non hai ancora un account, vedi Configura il tuo account.
• Un saldo. Aggiungi fondi in Billing nella console prima della prima generazione. Workflow n8n, Studio e API usano lo stesso saldo dell’account. Vedi Fatturazione per la liquidazione degli addebiti.
• Una chiave per automazione. I workflow possono girare molto più spesso di quanto una persona faccia clic. Crea una chiave separata per n8n e impostale un tetto di spesa giornaliero o mensile, così un errore in un ciclo ha un limite massimo. Vedi Autenticazione.
• n8n deve poter raggiungere api.spicyapi.ai. Le chiamate le fa il server di n8n, non il tuo browser.

Opzione 1: il community node SpicyAPI

Il nodo è open source (MIT) su github.com/spicyapi-ai/n8n-nodes-spicyapi ed è pubblicato su npm come @spicyapi/n8n-nodes-spicyapi. Non ha dipendenze a runtime e comunica solo con api.spicyapi.ai.

Esistono altri pacchetti npm con nomi simili, ma appartengono a servizi non correlati. Questo è il pacchetto chiamato @spicyapi/n8n-nodes-spicyapi, e la sua credenziale si chiama SpicyAPI (spicyapi.ai) API.

Installazione

cd ~/.n8n/nodes
npm install @spicyapi/n8n-nodes-spicyapi

Operazioni

Genera immagini, video e audio

Le tre operazioni Generate condividono gli stessi campi:

1. Model. Scegli dall’elenco, che mostra i modelli della risorsa selezionata con il loro prezzo di partenza, oppure inserisci a mano un ID modello. Tutti i modelli e i loro parametri sono elencati su spicyapi.ai/models.
2. Prompt. L’input di testo principale del modello. Per i modelli vocali è il testo da pronunciare. Lascialo vuoto per i modelli senza prompt, come gli upscaler.
3. Media Inputs. Immagini, video o audio che il modello legge. Scegli il campo (l’elenco mostra gli input file del modello selezionato), poi usa un campo binario del nodo precedente o un URL. I file binari vengono caricati automaticamente su SpicyAPI. Aggiungi più input per lo stesso campo per riempire i campi di tipo elenco, come le immagini di riferimento.
4. Model Parameters. Un modulo generato dallo schema del modello selezionato: formato, risoluzione, durata, seed e così via. I campi che lasci vuoti non vengono inviati, quindi il modello usa il proprio valore predefinito.
5. Additional Parameters (JSON). Qualsiasi altro campo di input come oggetto JSON. Sovrascrive i campi sopra.

L’output contiene il record dell’attività (taskId, state, cost, settled, output). Con Download Output attivo, come è per impostazione predefinita, i file vengono allegati anche come dati binari in data, data_1 e così via. I link in output.assets[].url scadono dopo circa 20 minuti; le copie binarie no.

I video di grandi dimensioni restano in memoria, a meno che n8n non conservi i dati binari su disco. Su n8n self-hosted, imposta N8N_DEFAULT_BINARY_DATA_MODE=filesystem quando lavori con i video.

Controllo dei costi e nuovi tentativi

• Ogni elemento viene quotato prima. Il nodo chiede un preventivo. Se il preventivo supera Max Cost per Item (USD), che per impostazione predefinita è $2, si ferma con un errore prima che venga creato qualcosa, e non viene addebitato nulla. Imposta il limite a 0 per eliminarlo.
• L’attività viene creata con il prezzo quotato. Se il prezzo cambia tra il preventivo e l’invio, il nodo chiede di nuovo il preventivo, ricontrolla il limite e reinvia.
• I nuovi tentativi non addebitano due volte. Vedi Limiti di costo e nuovi tentativi.

Attività di lunga durata

Vedi Attività video di lunga durata per le opzioni e per quando usare ciascuna.

Opzione 2: template HTTP Request

Due workflow importabili usano solo nodi integrati di n8n, quindi funzionano su n8n self-hosted e su n8n Cloud, senza community node. Si trovano nella cartella degli esempi del repository del nodo.

Come è costruito il template per le immagini

Gli stessi passaggi funzionano per qualsiasi modello multimediale, quindi puoi copiare lo schema nel tuo workflow.

Le forme di richieste e risposte sono descritte in Attività, Preventivi e compatibilità di protocollo e Media. I file che un modello legge, come un’immagine iniziale, possono essere un URL pubblico o un file spicy:// caricato.

Opzione 3: modelli di chat in AI Agent e altri nodi AI

L’endpoint di chat di SpicyAPI è compatibile con OpenAI, quindi i nodi OpenAI di n8n possono usarlo. Per questo non serve il community node, e funziona su n8n Cloud.

https://api.spicyapi.ai/v1

Da sapere:

• L’elenco dei modelli include modelli di immagini e video. Con un Base URL personalizzato n8n mostra tutto ciò che restituisce /v1/models, e l’elenco di SpicyAPI comprende tutti i suoi modelli. Scegline uno che termina con /chat, oppure digita l’ID in modalità espressione. I modelli di immagini e video non sono modelli di chat e in un agente falliranno.
• Use Responses API. Le versioni recenti del nodo OpenAI Chat Model possono inviare le richieste a /v1/responses invece che a /v1/chat/completions. SpicyAPI supporta /v1/responses, ma non previous_response_id. Se una richiesta dell’agente fallisce con Responses API attivo, disattiva Use Responses API nel nodo.
• Impostazioni di campionamento. Se imposti un’opzione che il modello non dichiara, come temperature su un modello con ragionamento, SpicyAPI la ignora invece di fallire ed elenca i nomi ignorati nell’header di risposta X-Spicy-Ignored-Params; un valore fuori dall’intervallo del modello viene cambiato in quello accettato più vicino ed elencato in X-Spicy-Adjusted-Params. Gli altri campi non dichiarati restituiscono comunque 400.
• Strumenti e output JSON dipendono dal modello. Controlla i supported_parameters del modello in /v1/models.
• I modelli con ragionamento contano i token di ragionamento in max_tokens. Con un valore molto piccolo, come 20, un modello con ragionamento può consumare tutto il budget pensando e non restituire alcun testo (upstream_failed: «the output budget was spent on reasoning»). Aumenta max_tokens o abbassa reasoning_effort. I valori di reasoning_effort cambiano da modello a modello.
• Streaming e costi. La chat viene fatturata a token dopo la chiamata. La pagina testo e streaming ha i dettagli, e Ricette di chat ha esempi di richieste.

Limiti di costo e nuovi tentativi

Limiti di spesa

• Usa una chiave separata per n8n con un tetto di spesa giornaliero o mensile nella console, e un elenco di modelli consentiti se il workflow ne richiede solo pochi. Quando un tetto viene raggiunto, la chiamata fallisce con 40202 e per essa non viene addebitato nulla.
• Per i modelli multimediali, quota prima. Il nodo lo fa per te; i template lo fanno con i nodi Get Quote e If. Il preventivo è il prezzo esatto di quella richiesta, comprese le voci extra come gli addebiti per immagine di riferimento, quindi un controllo del prezzo basato su un preventivo è affidabile, mentre uno basato sulla tabella del catalogo no.
• I normali errori e le attività scadute liberano l’intero importo riservato. Alcuni rifiuti di contenuto vengono addebitati solo quando la pagina del modello lo indica esplicitamente. Leggi settled e cost per l’importo finale; vedi Fatturazione.

Perché un nuovo tentativo non addebita due volte

Ogni chiamata che crea un’attività porta un Idempotency-Key. Se la stessa chiave arriva di nuovo con la stessa richiesta, SpicyAPI restituisce l’attività che ha già creato invece di crearne una seconda, quindi non avviene alcun secondo blocco né addebito. In n8n questo conta perché una richiesta può essere inviata due volte senza che tu faccia nulla: Retry On Fail su un nodo, oppure un timeout in cui la prima richiesta era invece andata a buon fine.

• Il community node costruisce la chiave dall’esecuzione, dal nodo, dall’elemento e dal suo input. Un nuovo tentativo del nodo riusa la stessa chiave. Una nuova esecuzione, un input modificato o un altro passaggio in un ciclo sono lavoro nuovo e ottengono una chiave nuova.
• I template la costruiscono dall’ID dell’esecuzione e dall’indice dell’elemento, per esempio n8n-<execution id>-<item index>. Se copi lo schema in un ciclo, aggiungi alla chiave il contatore del ciclo, altrimenti ogni passaggio restituirà l’attività del primo.
• Non usare un valore casuale che cambia a ogni tentativo, come $now: farebbe sembrare ogni nuovo tentativo lavoro nuovo.

Altro in Idempotenza.

Attività video di lunga durata

I modelli di immagini e audio di solito terminano in una sola richiesta. Un video può richiedere minuti. Hai tre modi per gestirlo, dal più semplice al più leggero per n8n:

Se il nodo smette di attendere, l’attività continua su SpicyAPI e viene addebitata se ha successo. Recuperala più tardi con Task > Get; non inviarla di nuovo. Puoi trovarla anche sotto Logs nella console.

I risultati vengono conservati per un tempo limitato e i link di download durano circa 20 minuti. Salva i file nel workflow, per esempio su uno storage cloud, se ti servono più a lungo. Vedi Conservazione e distruzione.

Risoluzione dei problemi

Gli errori di SpicyAPI terminano con un request_id o un ID attività. Comunicalo al supporto e la richiesta si potrà trovare con precisione. I codici di errore sono spiegati in Errori, e una checklist più ampia è in Risoluzione dei problemi.

L’uso dei modelli è soggetto ai termini di SpicyAPI e ai termini dell’edizione di n8n che esegui.