Endpoint AI Gateway e Variabili d'Ambiente

Oltre all'acquisizione con un clic degli strumenti AI pronti all’uso, puoi anche collegarti direttamente alla AI Gateway dalle tue applicazioni, script o tool AI personalizzati. In questo documento vengono illustrati i formati degli endpoint esposti dalla gateway e come connettersi tramite le chiavi virtuali.

Endpoint Proxy

Il servizio proxy della AI Gateway ascolta su http://127.0.0.1:11580. Per garantire la compatibilità con diversi SDK e strumenti dei fornitori, la gateway offre più formati di protocollo sullo stesso porto:

Formato Protocollo	Percorso Endpoint	Casistica d'Uso
Compatibile OpenAI	http://127.0.0.1:11580/v1	Qualsiasi SDK/tool che segue il formato API di OpenAI (es. /v1/chat/completions)
Compatibile Anthropic	http://127.0.0.1:11580/v1/messages	SDK Anthropic e strumenti come Claude Code
Compatibile Gemini	http://127.0.0.1:11580/v1beta	SDK Google Gemini e strumenti come Gemini CLI

Scegli semplicemente il formato compatibile con il protocollo del tuo SDK e indirizza la richiesta all'indirizzo della Gateway: in base ai permessi della chiave virtuale, la Gateway smisterà la richiesta verso il canale corretto del provider.

Autenticazione: Utilizzo delle Chiavi Virtuali

Tutte le richieste verso la gateway utilizzano esclusivamente le chiavi virtuali per l’autenticazione, non la chiave reale del provider. Prima di tutto, crea una chiave virtuale nella sezione Chiavi e copia il valore in chiaro.

Nella sezione AI Gateway → Endpoints, puoi selezionare una chiave virtuale e la piattaforma genererà direttamente i frammenti di variabili d'ambiente da copiare per i tool più comuni.

Esempi di Variabili d'Ambiente

Gli esempi seguenti presumono che tu abbia già ottenuto una chiave virtuale (indicata come <la tua chiave virtuale>).

SDK / Tool Compatibili OpenAI

export OPENAI_BASE_URL="http://127.0.0.1:11580/v1"
export OPENAI_API_KEY="<la tua chiave virtuale>"

Claude Code / Anthropic

# Nota: il protocollo Anthropic utilizza la root della gateway, senza /v1
export ANTHROPIC_BASE_URL="http://127.0.0.1:11580"
export ANTHROPIC_AUTH_TOKEN="<la tua chiave virtuale>"

Gemini

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:11580"
export GEMINI_API_KEY="<la tua chiave virtuale>"

Esempio di Chiamata (Compatibile OpenAI)

curl http://127.0.0.1:11580/v1/chat/completions \
  -H "Authorization: Bearer <la tua chiave virtuale>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Ciao"}]
  }'

Nota che il campo model deve corrispondere a un modello già configurato tra i tuoi canali e abilitato per quella chiave virtuale.

Prerequisiti

• Il servizio proxy della AI Gateway deve essere in esecuzione.
• Devi aver configurato almeno un canale funzionante e creato una chiave virtuale con i permessi necessari su quei modelli/canali.

Domande Frequenti (FAQ)

• D: Ricevo un errore di autenticazione?
  • R: Verifica di utilizzare una chiave virtuale (non la chiave reale del provider) e che la chiave sia ancora valida e non revocata.
• D: Messaggio di modello non disponibile o senza permessi?
  • R: Controlla che il modello specificato sia stato configurato almeno su un canale e che la tua chiave virtuale abbia tra i permessi il modello/canale selezionato.
• D: Quale formato di endpoint scegliere?
  • R: Scegli in base al protocollo supportato dal tuo SDK: stile OpenAI usa /v1, stile Anthropic usa /v1/messages (ma la Base URL senza /v1), stile Gemini usa /v1beta.
• D: Altri dispositivi nella LAN possono accedere alla gateway?
  • R: Di default la gateway ascolta solo su 127.0.0.1 (localhost), per motivi di sicurezza: questa impostazione è raccomandata.

Sommario

La AI Gateway offre un endpoint locale uniforme in tre formati compatibili (OpenAI, Anthropic e Gemini): in abbinamento con le chiavi virtuali puoi collegare qualsiasi applicazione o tool AI, gestendo centralmente chiavi e statistiche d’uso. Per i tool da riga di comando più comuni, ti consigliamo di usare la funzione di acquisizione con un clic per una configurazione ancora più semplice.