"API key not valid. Please pass a valid API key." — la frase meno utile di Gemini. Di solito la chiave È valida; c'è qualcosa che non va intorno a essa: una restrizione per referrer, la Generative Language API non abilitata o una chiave AI Studio inviata a un endpoint Vertex. Segui l'elenco qui sotto in ordine.
L’errore
{
"error": {
"code": 400,
"message": "API key not valid. Please pass a valid API key.",
"status": "INVALID_ARGUMENT",
"details": [{ "reason": "API_KEY_INVALID" }]
}
}Cause e soluzioni in breve
| Causa | Soluzione |
|---|---|
| Le restrizioni della chiave (referrer HTTP / IP) bloccano le chiamate dal server | In Google Cloud Console → Credentials, una chiave con restrizione per referrer rifiuta le richieste lato server. Usa una chiave senza restrizioni oppure limita l'accesso per API. |
| Generative Language API non abilitata nel progetto | Abilita "Generative Language API" per le chiavi di tipo AI Studio. |
| Incompatibilità tra chiave AI Studio ed endpoint Vertex AI | Le chiavi AIza… chiamano generativelanguage.googleapis.com; Vertex usa OAuth/account di servizio su un host diverso. Non confonderle. |
| Regione non supportata | Le chiavi AI Studio non funzionano da tutti i Paesi; verifica la disponibilità oppure instrada la richiesta tramite un gateway. |
| Gestione della variabile d'ambiente (virgolette/spazi bianchi/nome errato) | Stampa repr(key) all'interno del processo che fallisce; riesporta la variabile in modo pulito. |
Testa la chiave in isolamento
Una chiamata curl verso l'endpoint REST ti dirà se la chiave in sé funziona:
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"parts":[{"text":"ping"}]}]}' | head -c 400Controlla le restrizioni e le API abilitate
Cloud Console → APIs & Services → Credentials: apri la chiave. Se Application restrictions indica "HTTP referrers", le chiamate del server restituiranno 400: passa a None o a una restrizione basata sull'IP. Poi verifica che Generative Language API sia abilitata nello stesso progetto.
Se ti serve comunque un'unica chiave per molti modelli
Se gestisci chiavi Gemini, Claude e GPT, un gateway compatibile con OpenAI le riunisce in un'unica credenziale: stesso codice, un solo base_url e nessun progetto Google Cloud richiesto.
Se chiami tramite Kunavo
Kunavo offre Gemini 2.5 Flash e Pro attraverso lo stesso endpoint compatibile con OpenAI e la stessa chiave sk-kn di Claude e GPT: nessun progetto Google Cloud, nessuna restrizione della chiave da diagnosticare e funzionamento anche nelle regioni in cui le chiavi AI Studio non sono disponibili. Le tariffe sono nettamente inferiori al listino Google e la configurazione richiede tre campi in qualsiasi SDK OpenAI.
Domande frequenti
La mia chiave Gemini funziona localmente ma fallisce in produzione: perché?
Di solito si tratta di restrizioni su referrer/IP (gli IP di produzione non sono autorizzati), di un file di ambiente diverso in produzione oppure del fatto che nel progetto di produzione non sia abilitata la Generative Language API. Confronta la rappresentazione della chiave e l'ID del progetto tra gli ambienti.
L'API Gemini è gratuita?
AI Studio offre un livello gratuito con rigidi limiti al minuto; il traffico di produzione richiede la fatturazione attiva (oppure un gateway). Se ricevi errori di quota anziché errori della chiave, consulta la nostra guida su RESOURCE_EXHAUSTED.
Guide correlate
Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.