«API key not valid. Please pass a valid API key.»: las cinco cosas que Gemini quiere decir

Este mensaje es el cajón de sastre de Google: la clave enviada no se pudo usar para esta llamada. No significa lo mismo que decir que la clave sea incorrecta; cuatro de las cinco causas dejan la clave perfectamente válida, por lo que volver a copiarla suele ser una pérdida de tiempo.

El error

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" }]
  }
}

Causas y soluciones de un vistazo

Causa	Solución
La Generative Language API no está habilitada en el proyecto de la clave	Habilítala para ese proyecto y espera un minuto: las API recién habilitadas rechazan solicitudes durante un breve periodo.
Se ha enviado una credencial de Vertex AI al endpoint de AI Studio	Vertex usa OAuth contra un host regional; generativelanguage.googleapis.com necesita una clave de AI Studio. No son intercambiables.
La clave tiene restricciones de HTTP-referrer o de IP	Las llamadas desde el servidor no envían ningún referente. Restringe por IP o crea una clave sin restricciones para el backend.
La clave se ha enviado en el lugar equivocado	Gemini lee `x-goog-api-key` o `?key=`. Ignora el encabezado `Authorization: Bearer`, por lo que la solicitud llega sin clave.
La clave se ha eliminado o procede de una cuenta de Google distinta de la que crees	Es la única causa en la que emitir una nueva clave ayuda. Comprueba en qué cuenta ha iniciado sesión AI Studio.

Demuestra primero la clave de forma aislada

Antes de tocar tu aplicación, prueba la clave en una solicitud básica. Si funciona y tu aplicación no, la clave está bien y el error está en la forma en que la aplicación la transmite; así eliminas de una vez las tres causas más comunes.

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

Lee qué encabezado envía realmente tu cliente

La mayoría de los SDK con formato de OpenAI ponen las credenciales en `Authorization: Bearer`. La API nativa de Gemini no lee ese encabezado, por lo que dirigir un cliente de OpenAI directamente a generativelanguage.googleapis.com produce este error exacto con una clave perfectamente válida. Usa el SDK de Google o llama a un endpoint compatible con OpenAI que espere el 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)

Distingue 400 de 403

Si el motivo cambia a PERMISSION_DENIED una vez transmitida correctamente la clave, significa que la clave ya se está leyendo y se rechaza por el alcance: es otro problema con otra solución (permisos del proyecto, no formato de la clave). Pasar de 400 a 403 es progreso, no una regresión.

Si llamas a través de Kunavo

En Kunavo, la sección de Gemini está detrás del mismo endpoint con formato de OpenAI y de la misma clave `sk-kn-` que todo lo demás, enviada como un token bearer normal; por eso las causas de incompatibilidad de encabezado y de Vertex frente a AI Studio descritas arriba simplemente no pueden producirse. No hay ningún proyecto de Google que habilitar ni ninguna política de referentes por clave con la que tropezar. Lo que sigue siendo responsabilidad tuya es que la clave esté activa y la cartera tenga fondos; una solicitud rechazada no se cobra. Las tarifas de Gemini por token están en nuestra guía de precios de Gemini.

Preguntas frecuentes

Acabo de crear la clave y sigue apareciendo como no válida.

Las API recién habilitadas y las claves recién creadas pueden rechazar solicitudes durante uno o dos minutos. Si persiste después de ese tiempo, casi con toda seguridad al proyecto le falta la Generative Language API, no es que la clave esté mal.

¿Significa que me quedé sin cuota?

No. El agotamiento de la cuota es 429 RESOURCE_EXHAUSTED y los problemas de facturación aparecen como 403. Un 400 API_KEY_INVALID nunca significa que te hayas quedado sin crédito.

¿Por qué la misma clave funciona en AI Studio pero no en mi código?

AI Studio realiza las llamadas desde el origen propio de Google. Una clave restringida por referente permite ese origen y rechaza tu servidor, que no envía ningún referente.

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.