n8n

Il campo Base URL delle credenziali OpenAI — https://api.kunavo.com/v1, mantenendo /v1 — porta ogni OpenAI Chat Model in un flusso di lavoro n8n su Kunavo; il nodo modello non ha un campo endpoint.

Credentials  →  Create credential  →  OpenAI
  API Key                      sk-kn-...
  Organization ID (optional)   leave empty
  Base URL                     https://api.kunavo.com/v1     <- keep the /v1

Workflow  →  AI Agent or Basic LLM Chain  →  Chat Model: OpenAI Chat Model
  Credential to connect with   the OpenAI credential above
  Model                        ID mode:  claude-sonnet-5
  Use Responses API            on   → POST /v1/responses
                               off  → POST /v1/chat/completions

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. In n8n, crea una credenziale di tipo OpenAI. Inserisci la chiave in API Key, lascia vuoto Organization ID (optional) e sostituisci il valore predefinito https://api.openai.com/v1 di Base URL con https://api.kunavo.com/v1. Salva.
3. Aggiungi un nodo AI Agent o Basic LLM Chain e collegagli un sottonodo OpenAI Chat Model che usa quelle credenziali. Cambia il campo Model da From List a ID e inserisci l'ID così come compare in GET /v1/models, per esempio claude-sonnet-5. Funziona anche l'elenco, ma inserire l'ID direttamente mantiene chiaro il workflow.
4. Scegli se attivare Use Responses API: lascialo attivo, a meno che uno strumento nella tua catena non richieda Chat Completions o tu non voglia che il log di esecuzione di n8n mostri una richiesta chat completions.
5. Esegui il workflow una volta con un prompt di una riga prima di collegarlo a un trigger. Un 401 indica un problema con la chiave; un 404 con il codice missing_v1_prefix (o, nelle esecuzioni precedenti, un messaggio che inizia con <!DOCTYPE html>) indica che in Base URL manca /v1.

Verificato rispetto a Codice sorgente delle credenziali OpenAI di n8n al tag n8n@2.41.4 il 1 ottobre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in n8n.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

Perché Base URL si trova nelle credenziali

I tutorial meno recenti impostano l'endpoint nel nodo del modello. Nel codice rilasciato, l'opzione Base URL all'interno del nodo è nascosta dalla versione 1.1 in poi; un nodo aggiunto oggi quindi non dispone di quel campo e fa fede Base URL nelle credenziali. La documentazione OpenAI Chat Model di n8n e la sua pagina delle credenziali non descrivono il campo; lo fa invece il codice sorgente, con la descrizione «Sovrascrive l'URL base predefinito per l'API». Il nodo HTTP Request è un percorso del tutto diverso: funziona, ma dovresti costruire manualmente la richiesta che il nodo AI Agent prepara per te.

Responses API attivata o disattivata

• Attivata (impostazione predefinita sul nodo 1.3): le richieste vanno a /v1/responses. È l'unica modalità che mostra gli strumenti integrati del nodo: Web Search, File Search e Code Interpreter. Sono strumenti ospitati da OpenAI; nessuno li ha testati tramite Kunavo, quindi prova prima di creare un workflow che dipenda da essi.
• Disattivata: le richieste vanno a /v1/chat/completions, la forma supportata più ampiamente e quella da usare se una chiamata a uno strumento si comporta in modo anomalo con l'altra impostazione.
• Gli strumenti che colleghi a un AI Agent vengono inviati al modello come definizioni di funzioni. Questo ciclo di richiesta e risposta non faceva parte della verifica; prova quindi una chiamata a uno strumento in un workflow di test prima di farvi affidamento.

n8n e OpenRouter

n8n include un nodo OpenRouter Chat Model separato, con le proprie credenziali OpenRouter. Le credenziali hanno un campo API Key e un campo Base URL nascosto e impostato in modo fisso su https://openrouter.ai/api/v1; il test chiama il percorso /key di OpenRouter. Di conseguenza, il nodo OpenRouter può comunicare soltanto con OpenRouter. Se vuoi usare OpenRouter, usa quel nodo con una chiave OpenRouter; non ti serve nulla di questa pagina.

Qualsiasi altro endpoint compatibile con OpenAI, Kunavo compreso, passa attraverso OpenAI Chat Model e il campo Base URL delle credenziali OpenAI, come descritto sopra. Scegli in base alle differenze effettive: quali modelli ti servono, come vuoi pagare e se vuoi usare un unico saldo per n8n e gli altri strumenti, non in base al nodo. Il confronto dal lato di Kunavo è descritto in Kunavo vs OpenRouter.

Tenere sotto controllo i costi di un workflow non presidiato

• Per impostazione predefinita, Max Retries del nodo è 2 e Timeout è 60000 ms. Le richieste che vanno in timeout vengono riprovate e ogni nuovo tentativo comporta una nuova richiesta fatturata.
• Imposta Maximum Number of Tokens nei nodi eseguiti per ogni elemento: un ciclo su 1,000 righe moltiplica il costo di ogni singola chiamata.
• Usa una chiave Kunavo distinta per ogni workflow di produzione, così la pagina di utilizzo mostra quanto ha speso ciascuno; potrai anche revocare una chiave senza intervenire sulle altre.

Come si presentano gli errori

• «401 Missing or invalid API key»: l'URL in Base URL è corretto, ma la chiave non lo è. Riprodotto sulla versione 2.41.4.
• «404 <!DOCTYPE html>…», classificato da LangChain come MODEL_NOT_FOUND: l'errore è fuorviante. Il modello è corretto; in Base URL manca /v1 e la richiesta è finita sul sito web. Riprodotto sulla versione 2.41.4.
• Messaggio JSON che indica che il modello non è disponibile: l'ID del modello non corrisponde esattamente a GET /v1/models.