« API key not valid. Please pass a valid API key. » — la phrase la moins utile de Gemini. La clé EST généralement valide ; c’est quelque chose autour qui pose problème : une restriction de référent, la Generative Language API non activée ou une clé AI Studio envoyée à un endpoint Vertex. Suivez la liste ci-dessous dans l’ordre.
L’erreur
{
"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 |
|---|---|
| Restrictions de clé (référent HTTP / IP) bloquant les appels serveur | Dans Google Cloud Console → Credentials, une clé limitée par référent rejette les requêtes côté serveur. Utilisez une clé sans restriction ou restreignez-la par API. |
| Generative Language API non activée sur le projet | Activez « Generative Language API » pour les clés de type AI Studio. |
| Incompatibilité entre clé AI Studio et endpoint Vertex AI | Les clés AIza… appellent generativelanguage.googleapis.com ; Vertex utilise OAuth/des comptes de service sur un autre hôte. Ne les intervertissez pas. |
| Région non prise en charge | Les clés AI Studio ne fonctionnent pas depuis tous les pays ; vérifiez la disponibilité ou passez par une passerelle. |
| Configuration de variable d’environnement (guillemets/espaces/nom incorrect) | Exécutez print(repr(key)) dans le processus en échec ; exportez de nouveau la variable proprement. |
Testez la clé isolément
Un curl vers l’endpoint REST vous indique si la clé elle-même est correcte :
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 400Vérifiez les restrictions et les API activées
Cloud Console → APIs & Services → Credentials : ouvrez la clé. Si Application restrictions indique « HTTP referrers », les appels serveur renverront 400 — passez à None ou à une restriction par IP. Vérifiez ensuite que la Generative Language API est activée sur le même projet.
Si vous avez malgré tout besoin d’une seule clé pour de nombreux modèles
Si vous jonglez entre des clés Gemini, Claude et GPT, une passerelle compatible OpenAI les regroupe sous un seul identifiant — même code, une base_url unique, aucun projet Google Cloud requis.
Si vous appelez via Kunavo
Kunavo fournit Gemini 2.5 Flash et Pro derrière le même endpoint compatible OpenAI et la même clé sk-kn que Claude et GPT — aucun projet Google Cloud, aucune restriction de clé à déboguer, et un fonctionnement depuis les régions où les clés AI Studio ne sont pas proposées. Les tarifs sont nettement inférieurs au prix catalogue de Google, et la configuration se résume à trois champs dans n’importe quel SDK OpenAI.
Questions fréquentes
Ma clé Gemini fonctionne en local mais échoue en production — pourquoi ?
Il s’agit généralement de restrictions de référent/IP (les IP de production ne sont pas autorisées), d’un fichier d’environnement différent en production ou de l’absence de Generative Language API dans le projet de production. Comparez la représentation de la clé et l’identifiant du projet entre les environnements.
L’API Gemini est-elle gratuite ?
AI Studio propose un niveau gratuit avec des quotas stricts par minute ; le trafic de production nécessite la facturation activée (ou une passerelle). Si vous rencontrez des erreurs de quota plutôt que des erreurs de clé, consultez notre guide RESOURCE_EXHAUSTED.
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.