"API key not valid. Please pass a valid API key.": la frase menos útil de Gemini. La clave normalmente SÍ es válida; algo a su alrededor está mal: una restricción de referente, la Generative Language API no habilitada o una clave de AI Studio enviada a un endpoint de Vertex. Recorre la lista siguiente en orden.
El error
{
"error": {
"code": 400,
"message": "API key not valid. Please pass a valid API key.",
"status": "INVALID_ARGUMENT",
"details": [{ "reason": "API_KEY_INVALID" }]
}
}Causas y soluciones de un vistazo
| Causa | Solución |
|---|---|
| Restricciones de la clave (referente HTTP/IP) que bloquean las llamadas del servidor | En Google Cloud Console → Credentials, una clave restringida por referente rechaza las solicitudes del lado del servidor. Usa una clave sin restricciones o restríngeke por API. |
| La Generative Language API no está habilitada en el proyecto | Habilita "Generative Language API" para las claves de estilo AI Studio. |
| Incompatibilidad entre la clave de AI Studio y el endpoint de Vertex AI | Las claves AIza… llaman a generativelanguage.googleapis.com; Vertex utiliza OAuth/cuentas de servicio en otro host. No las mezcles. |
| Región no compatible | Las claves de AI Studio no funcionan desde todos los países; comprueba la disponibilidad o enruta mediante una pasarela. |
| Configuración de variables de entorno (comillas/espacios/nombre de variable incorrecto) | Ejecuta print(repr(key)) dentro del proceso que falla y vuelve a exportarla limpiamente. |
Prueba la clave de forma aislada
Un curl contra el endpoint REST indica si la clave en sí funciona:
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 400Comprueba las restricciones y las API habilitadas
Cloud Console → APIs & Services → Credentials: abre la clave. Si Application restrictions muestra "HTTP referrers", las llamadas del servidor devolverán 400; cambia a None o a restricciones basadas en IP. Después confirma que Generative Language API esté habilitada en el mismo proyecto.
Si necesitas una sola clave para muchos modelos
Si gestionas claves de Gemini + Claude + GPT, una pasarela compatible con OpenAI las unifica en una sola credencial: mismo código, un base_url y ningún proyecto de Google Cloud necesario.
Si llamas a través de Kunavo
Kunavo ofrece Gemini 2.5 Flash y Pro detrás del mismo endpoint compatible con OpenAI y la misma clave sk-kn que Claude y GPT: no necesitas un proyecto de Google Cloud ni depurar restricciones de claves, y funciona desde regiones donde no se ofrecen claves de AI Studio. Las tarifas están muy por debajo del precio de lista de Google y la configuración consta de tres campos en cualquier SDK de OpenAI.
Preguntas frecuentes
Mi clave de Gemini funciona localmente, pero falla en producción. ¿Por qué?
Normalmente se debe a restricciones de referente/IP (las IP de producción no están permitidas), a un archivo de entorno diferente en producción o a que Generative Language API no está habilitada en el proyecto de producción. Compara la representación de la clave y el ID del proyecto entre los entornos.
¿La API de Gemini es gratuita?
AI Studio tiene un nivel gratuito con cuotas estrictas por minuto; el tráfico de producción necesita la facturación habilitada (o una pasarela). Si recibes errores de cuota y no de clave, consulta nuestra guía de RESOURCE_EXHAUSTED.
Guías relacionadas
Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.