"API key not valid. Please pass a valid API key." — le cinque cause indicate da Gemini

Questo messaggio è il contenitore generico di Google: la chiave inviata non può essere utilizzata per questa chiamata. Non equivale a dire che la chiave sia errata e quattro delle cinque cause lasciano la chiave perfettamente valida — per questo copiarla di nuovo è di solito tempo perso.

L’errore

risposta (HTTP 400)

{
  "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
La Generative Language API non è abilitata nel progetto della chiave	Abilitala per quel progetto, poi attendi un minuto: le API appena abilitate possono rifiutare le richieste per un breve periodo.
Una credenziale Vertex AI inviata all'endpoint AI Studio	Vertex usa OAuth verso un host regionale; generativelanguage.googleapis.com richiede una chiave API AI Studio. Non sono intercambiabili.
La chiave contiene restrizioni HTTP-referrer o IP	Le chiamate lato server non inviano alcun referrer. Limita per IP oppure crea una chiave senza restrizioni per l'uso backend.
Chiave inviata nel posto sbagliato	Gemini legge `x-goog-api-key` oppure `?key=`. Un'intestazione `Authorization: Bearer` viene ignorata, quindi la richiesta arriva senza chiave.
Chiave eliminata o appartenente a un account Google diverso da quello che pensi	È l'unica causa per cui crearne una nuova è utile. Controlla con quale account AI Studio ha effettuato l'accesso.

Dimostra prima la validità della chiave in isolamento

Prima di intervenire sull'applicazione, usa la chiave in una richiesta essenziale. Se funziona e la tua app no, la chiave è corretta e il problema riguarda il modo in cui l'app la trasmette — eliminando contemporaneamente le tre cause più comuni.

check-key.sh

curl -s -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/models" \
  | head -20

# 200 + a model list  -> the key is valid; look at your client
# 400 API_KEY_INVALID -> the key really cannot call this API

Leggi quale intestazione invia effettivamente il client

La maggior parte degli SDK con struttura OpenAI inserisce le credenziali in `Authorization: Bearer`. L'API nativa di Gemini non legge questa intestazione, quindi indirizzare un client OpenAI direttamente a generativelanguage.googleapis.com produce esattamente questo errore con una chiave perfettamente valida. Usa lo SDK di Google oppure chiama un endpoint compatibile con OpenAI che richieda il formato bearer.

openai_shape.py

from openai import OpenAI

# Bearer auth, OpenAI request shape, Gemini model names.
client = OpenAI(
    api_key=KUNAVO_API_KEY,
    base_url="https://api.kunavo.com/v1",
)

print(client.chat.completions.create(
    model="gemini-2-5-flash",
    messages=[{"role": "user", "content": "ping"}],
).choices[0].message.content)

Distingui 400 da 403

Se, dopo aver trasmesso correttamente la chiave, il motivo cambia in PERMISSION_DENIED, significa che la chiave ora viene letta e rifiutata per l'ambito: è un problema diverso, con una soluzione diversa (permessi del progetto, non formato della chiave). Passare da 400 a 403 è un progresso, non una regressione.

Se chiami tramite Kunavo

Su Kunavo, la sezione Gemini è disponibile tramite lo stesso endpoint con struttura OpenAI e la stessa chiave `sk-kn-` usata per tutto il resto, inviata come normale token bearer — quindi le cause relative all'intestazione errata e alla differenza Vertex-AI-Studio descritte sopra semplicemente non possono verificarsi. Non c'è alcun progetto Google da abilitare né alcuna policy di referrer per chiave da attivare accidentalmente. Restano a tuo carico la validità della chiave e la disponibilità di fondi nel portafoglio; una richiesta rifiutata non viene addebitata. Le tariffe Gemini per token sono disponibili in la nostra guida ai prezzi Gemini.

Domande frequenti

Ho appena creato la chiave, ma continua a indicarla come non valida.

Le API appena abilitate e le chiavi appena create possono rifiutare le richieste per uno o due minuti. Se il problema persiste oltre questo periodo, quasi certamente nel progetto manca la Generative Language API, non è la chiave a essere errata.

Significa che ho esaurito la quota?

No. L'esaurimento della quota è 429 RESOURCE_EXHAUSTED e i problemi di fatturazione vengono indicati come 403. Un 400 API_KEY_INVALID non significa mai che hai esaurito il credito.

Perché la stessa chiave funziona in AI Studio ma non nel mio codice?

AI Studio effettua le chiamate dall'origine proprietaria di Google. Una chiave con restrizioni sul referrer consente quell'origine e rifiuta il tuo server, che non invia alcun referrer.

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.