« API key not valid. Please pass a valid API key. » — les cinq problèmes que Gemini désigne ainsi

Ce message est le fourre-tout de Google : la clé envoyée n’a pas pu être utilisée pour cet appel. Cela ne signifie pas nécessairement que la clé est incorrecte, et quatre des cinq causes laissent la clé elle-même parfaitement valide — c’est pourquoi la recopier est généralement inutile.

L’erreur

response (HTTP 400)

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [{ "reason": "API_KEY_INVALID" }]
  }
}

Causes et solutions en bref

Cause	Solution
La Generative Language API n’est pas activée sur le projet de la clé	Activez-la pour ce projet, puis attendez une minute — les API fraîchement activées refusent les requêtes pendant une courte période.
Un identifiant Vertex AI envoyé au point de terminaison AI Studio	Vertex utilise OAuth auprès d’un hôte régional ; generativelanguage.googleapis.com attend une clé API AI Studio. Ils ne sont pas interchangeables.
La clé comporte des restrictions HTTP-referrer ou IP	Les appels côté serveur n’envoient aucun référent. Limitez la clé par IP ou créez une clé sans restriction pour l’utilisation côté serveur.
Clé envoyée au mauvais endroit	Gemini lit `x-goog-api-key` ou `?key=`. Un en-tête `Authorization: Bearer` est ignoré ; la requête arrive donc sans clé.
Clé supprimée ou provenant d’un autre compte Google que prévu	C’est la seule cause pour laquelle réémettre la clé peut aider. Vérifiez le compte avec lequel AI Studio est connecté.

Prouvez d’abord que la clé fonctionne isolément

Avant de modifier votre application, utilisez la clé dans une requête minimale. Si celle-ci fonctionne et que votre application échoue, la clé est correcte et le problème vient de la manière dont votre application la transmet — ce qui élimine d’un coup les trois causes les plus fréquentes.

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

Vérifiez quel en-tête votre client envoie réellement

La plupart des SDK de style OpenAI placent les identifiants dans `Authorization: Bearer`. L’API native de Gemini ne lit pas cet en-tête ; diriger directement un client OpenAI vers generativelanguage.googleapis.com produit donc exactement cette erreur avec une clé parfaitement valide. Utilisez le SDK de Google ou appelez un point de terminaison compatible OpenAI qui attend le format 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)

Distinguez 400 de 403

Si la raison devient PERMISSION_DENIED une fois la clé correctement transmise, cela signifie que la clé est désormais lue mais refusée pour des raisons de portée — un problème différent qui nécessite une autre correction (les permissions du projet, et non le format de la clé). Passer de 400 à 403 est un progrès, pas une régression.

Si vous appelez via Kunavo

Sur Kunavo, Gemini est exposé derrière le même point de terminaison de style OpenAI et la même clé `sk-kn-` que le reste, envoyée comme un token bearer standard — les causes de mauvais en-tête et de confusion Vertex/AI Studio décrites ci-dessus ne peuvent donc tout simplement pas se produire. Il n’y a aucun projet Google à activer ni aucune politique de référent par clé à déclencher. Il vous incombe toujours de vérifier que la clé est active et que le portefeuille est approvisionné ; une requête refusée n’est pas facturée. Les tarifs Gemini par token sont indiqués dans notre guide des tarifs Gemini.

Questions fréquentes

Je viens de créer la clé et elle est toujours signalée comme invalide.

Les API nouvellement activées et les clés fraîchement créées peuvent être refusées pendant une à deux minutes. Si le problème persiste au-delà, le projet ne dispose presque certainement pas de la Generative Language API, plutôt que la clé ne soit incorrecte.

Cela signifie-t-il que j’ai épuisé mon quota ?

Non. L’épuisement du quota correspond à 429 RESOURCE_EXHAUSTED et les problèmes de facturation apparaissent en 403. Un 400 API_KEY_INVALID ne signifie jamais que votre crédit est épuisé.

Pourquoi la même clé fonctionne-t-elle dans AI Studio mais pas dans mon code ?

AI Studio effectue les appels depuis l’origine de Google. Une clé limitée par référent l’autorise et refuse votre serveur, qui n’envoie aucun référent.

Guides associés

La sémantique détaillée des erreurs est disponible dans référence des erreurs ; obtenir une clé prend une minute via inscription et la guide d’authentification.