Cosa ti serve prima di iniziare
Un'istanza n8n (cloud o self-hosted) e una chiave API di questo servizio. Se non hai ancora una chiave, la pagina chiave API ti guida alla registrazione con Google o con email e password. I nuovi utenti possono richiedere $0,50 di credito di prova con un solo clic su quella pagina, valido per 7 giorni e senza carta.
Tre valori vanno inseriti in n8n:
- URL base:
https://api.onekeyllmapi.com/v1 - Chiave API: inviata come
Authorization: Bearer <key>, che n8n fa per te - ID modello:
uncensored
Il servizio è un'API LLM ospitata, solo testo, che segue il formato delle richieste OpenAI per /v1/chat/completions, /v1/responses e /v1/models. Non è l'API ufficiale di alcun fornitore di modelli, quindi qualsiasi cosa n8n invii all'endpoint chat di OpenAI funziona qui finché si tratta di una richiesta di testo.
Fase 1: Crea le credenziali
In n8n, apri Credenziali, scegli Crea credenziale e cerca OpenAI API. Compilalo in questo modo:
- Incolla la tua chiave nel campo API Key.
- Lascia vuoto Organization ID.
- Sostituisci il Base URL predefinito con
https://api.onekeyllmapi.com/v1. Mantieni/v1alla fine e non aggiungere/chat/completions. - Salva. n8n esegue una piccola chiamata di test quando salvi; se fallisce, passa alla sezione risoluzione dei problemi di seguito.
Mantieni una credenziale per ambiente. Se esegui n8n di staging e produzione, assegna a ciascuno la propria chiave in modo da poter vedere le spese separatamente e revocare una senza toccare l'altra.
Fase 2: Crea un semplice workflow di chat
Inizia con la cosa più piccola che dimostra la connessione: un trigger manuale e una chiamata al modello.
- Aggiungi un nodo Manual Trigger.
- Aggiungi un nodo OpenAI (o il sotto-nodo OpenAI Chat Model in una Basic LLM Chain, a seconda della versione di n8n) e seleziona le credenziali dal passaggio 1.
- Per il modello, cerca un modo per inserire un ID manualmente. Le versioni recenti di n8n offrono una modalità By ID accanto all'elenco. Digita
uncensoredlì. L'elenco potrebbe essere vuoto o mostrare solo nomi OpenAI, perché n8n lo filtra dal suo lato. - Aggiungi un prompt come Riassumi questo ticket di supporto in due frasi ed esegui il nodo.
Se la tua versione di n8n insiste per scegliere da un elenco, usa l'approccio HTTP Request nella sezione successiva. Funziona sempre perché controlli l'intera richiesta.
Chiamata all'API con il nodo HTTP Request
Il nodo HTTP Request è il modo più prevedibile per chiamare questa API da n8n ed espone ogni parametro accettato dall'API, inclusi seed, stop, top_p e tools. Configuralo così:
- Metodo:
POST - URL:
https://api.onekeyllmapi.com/v1/chat/completions - Autenticazione: Generic Credential Type con Header Auth, nome
Authorization, valoreBearer YOUR_KEY - Invia Body: on, content type JSON
Body (passa il campo a Expression se vuoi inserire dati da nodi precedenti):
{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Summarize this support ticket in two sentences."}
],
"temperature": 0.4
}
Il testo della risposta si trova in choices[0].message.content. Nel nodo successivo puoi riferirti ad esso con {{ $json.choices[0].message.content }}.
Per testare la stessa richiesta prima fuori da n8n, esegui questo in un terminale:
curl https://api.onekeyllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello in five words."}]}'
Se curl funziona e n8n no, il problema è nelle impostazioni del nodo, non nella tua chiave o nel saldo.
Modalità JSON per i workflow che analizzano l'output
I flussi di lavoro si interrompono quando un modello racchiude i dati in una prosa amichevole. La modalità JSON chiede all'API di restituire un oggetto JSON valido, che puoi passare direttamente a un nodo Imposta o SE. Aggiungi response_format al corpo:
{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object with keys sentiment and summary."},
{"role": "user", "content": "The delivery was late but support fixed it fast."}
]
}
Due abitudini rendono questo affidabile. Primo, scrivi la parola JSON e nomina le chiavi nel prompt, perché la modalità JSON garantisce la sintassi, non il tuo schema. Secondo, la risposta arriva comunque come stringa in message.content, quindi aggiungi un nodo Code o un'espressione con JSON.parse() prima di leggere i campi. Nel nodo OpenAI, lo stesso interruttore appare come opzione Response Format sotto le opzioni del nodo.
Gestione degli errori 429 e altri errori
n8n esegue gli elementi in parallelo, quindi un batch di 50 righe può superare i limiti rapidamente. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto; una chiave di prova ne permette 2 e 60. Quando superi i limiti, l'API risponde con HTTP 429 e il codice rate_limited (troppe al minuto) o concurrency (troppe contemporaneamente). In caso di sovraccarico temporaneo ricevi 429 con l'intestazione Retry-After: 5.
Impostazioni pratiche in n8n:
- Apri il nodo, vai a Impostazioni, abilita Riprova in caso di errore, imposta Numero massimo di tentativi a 3 o 4 e Attesa tra i tentativi a 5000 ms.
- Posiziona un nodo Ciclo su elementi (dimensione batch da 4 a 6) prima della chiamata al modello in modo da restare sotto le 8 richieste parallele.
- Nelle impostazioni del nodo Impostazioni, In caso di errore può essere impostato per continuare con un output di errore, in modo che una riga difettosa non interrompa l'esecuzione.
Per approfondire i due tipi di limite, leggi la documentazione API. Altri errori sono semplici: un 401 significa che la chiave è errata o che l'intestazione manca della parola Bearer, e un 404 indica solitamente un errore di battitura nel Base URL o un segmento di percorso extra.
Lista di controllo per la risoluzione dei problemi
La maggior parte dei guasti proviene da un breve elenco di cause. Procedi dall'alto verso il basso prima di sospettare il servizio.
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| 401 al salvataggio o all'esecuzione | Chiave errata o intestazione senza Bearer | Incolla di nuovo la chiave; in Header Auth il valore deve iniziare con Bearer |
| 404 | L'URL base ha un errore di battitura o un percorso extra | Usa esattamente https://api.onekeyllmapi.com/v1 nelle credenziali |
| Modello non trovato | L'ID del modello non è digitato come uncensored | Passa a Per ID, oppure usa il nodo Richiesta HTTP |
| 429 con concorrenza | Più di 8 esecuzioni parallele (2 su una chiave di prova) | Batch con Ciclo su Elementi e aggiungi i tentativi |
| Errore di analisi JSON a valle | La risposta è una stringa, oppure il prompt non ha indicato le chiavi | Analizza con JSON.parse() e descrivi le chiavi nel prompt di sistema |
Quando contatti il supporto, includi l'intestazione di risposta X-Request-Id della chiamata fallita. In n8n puoi vedere le intestazioni attivando Includi intestazioni di risposta e stato nelle opzioni del nodo Richiesta HTTP.
Testare spendendo poco
Usa il credito di prova mentre sviluppi. Con 2 richieste concorrenti e 60 richieste al minuto, una chiave di prova è lenta per i batch, ma è più che sufficiente per verificare una credenziale, un prompt e la logica di analisi. Passa a una chiave completa quando sposti il flusso di lavoro in una pianificazione.
Costi e un design del flusso di lavoro sensato
La tariffazione è a consumo: $0,15 per 1M di token di input e $0,50 per 1M di token di output, da credito prepagato. Un flusso di lavoro che classifica 1.000 email al giorno con 600 token di input e 100 token di output ciascuno utilizza 0,6M di token di input ($0,09) e 0,1M di token di output ($0,05), per circa $0,14 al giorno. Le richieste fallite o rifiutate non vengono addebitate, quindi i tentativi in caso di errori non raddoppiano il conto. I dettagli sono nella pagina dei prezzi.
Mantieni i prompt brevi, invia solo i campi di cui il modello ha bisogno e imposta max_tokens quando sai che la risposta è breve. Se esegui anche modelli sulla tua macchina, consulta l'articolo su l'utilizzo di un LLM locale tramite un'API in stile OpenAI, che utilizza le stesse impostazioni del client.
