Cómo obtener una clave de API de Google Gemini (2026): créala, pruébala y protégela para producción
Para obtener una clave de API de Google Gemini, inicia sesión en Google AI Studio con una cuenta de Google, acepta las condiciones, abre la página Claves de API y haz clic en Crear clave de API; los usuarios nuevos reciben automáticamente un proyecto de Google Cloud y una clave predeterminados. Crear una clave es gratis, y varios modelos de Gemini, incluidos Gemini 3.8 Flash y Gemini 3.5 Flash-Lite, tienen un nivel gratuito. Desde el 28 de mayo de 2026, todas las claves nuevas creadas en AI Studio son «claves de autorización» vinculadas a una cuenta de servicio, y la Gemini API rechaza las claves antiguas sin restricciones, por lo que quizá tengas que sustituir una clave que funcionaba el año pasado (documentación de Google sobre claves de API, consultada el 27 de octubre de 2026).
Esta guía está dirigida a desarrolladores independientes y equipos pequeños que quieren poner en marcha una clave de Gemini en minutos y usarla de forma segura en producción. Explica los pasos, los nuevos tipos de claves, el nivel gratuito, una primera solicitud con curl, Python y Node.js, los errores más habituales y una lista de comprobación para producción. Si estás comparando costes, nuestra guía de precios de la Gemini API incluye todas las tarifas.
Cómo obtener una clave de API de Gemini paso a paso
- Abre Google AI Studio. Ve a aistudio.google.com/apikey e inicia sesión con la cuenta de Google que quieras usar para la facturación o como propietaria del proyecto.
- Acepta las condiciones. Si eres un usuario nuevo, AI Studio crea un proyecto de Google Cloud y una clave de API predeterminados después de que aceptes las Condiciones del Servicio. Puedes cambiar el nombre del proyecto más adelante en la vista Proyectos.
- Elige o importa un proyecto. Si ya usas Google Cloud, AI Studio no crea un proyecto predeterminado. Abre Panel → Proyectos → Importar proyectos y selecciona el proyecto de Cloud que quieras.
- Crea la clave. En la página Claves de API, haz clic en Crear clave de API y elige el proyecto. Las claves nuevas son claves de autorización de forma predeterminada.
- Cópiala una vez y guárdala. Guárdala de inmediato en una variable de entorno o en un gestor de secretos, no en un archivo de tu repositorio.
- Aplica restricciones. Si la clave solo va a llamar a Gemini, mantenla restringida a la Gemini API (Generative Language API). Si se va a usar desde servidores fijos, añade restricciones por IP en la consola de Google Cloud.
- Pruébala con una de las solicitudes siguientes.
Pasos basados en Uso de claves de la Gemini API, de Google AI for Developers, cuya última actualización es del 27 de octubre de 2026.
¿Dónde puedo encontrar mi clave de API de Google más adelante?
En Google AI Studio, abre Panel → Claves de API. AI Studio muestra hasta 100 claves y 50 proyectos, y solo enumera las claves sin restricciones o restringidas a la Gemini API. Las claves restringidas a otras API de Google solo aparecen en la página de credenciales de la consola de Google Cloud. Si falta un proyecto, impórtalo primero.
Claves estándar frente a claves de autorización: qué cambió en 2026
Google está migrando la Gemini API de las claves de API estándar a las claves de autorización (auth). Según la documentación oficial (27 de octubre de 2026):
| Clave de API estándar | Clave de autorización | |
|---|---|---|
| A qué está vinculada | A un proyecto de Google Cloud, para la facturación y la cuota | A una cuenta de servicio de Google Cloud |
| Identifica a quien hace la llamada | No | Sí, las solicitudes se ejecutan con la identidad de la cuenta de servicio vinculada |
| Alcance predeterminado | Depende de las restricciones que añadas | Restringida a la Gemini API de forma predeterminada |
| Gestión de claves filtradas | Manual | Medidas rápidas que impiden el uso de las claves filtradas que detecta Google |
| Creada por AI Studio | Antes del 28 de mayo de 2026 | A partir del 28 de mayo de 2026 |
| ¿Sigue funcionando? | Solo si tiene restricciones explícitas | Sí |
Qué implica esto en la práctica:
- Las claves estándar sin restricciones se rechazan. Si una clave antigua no tiene restricciones de API, las solicitudes a Gemini fallan. Corrígelo en AI Studio: pasa el cursor sobre la etiqueta de advertencia de la clave y elige Restringir solo a la Gemini API. Necesitas el permiso
apikeys.keys.update. - Las claves sin restricciones que llevan mucho tiempo inactivas se bloquean. Desde el 7 de mayo de 2026, las claves sin restricciones que no se han usado durante un periodo prolongado muestran la etiqueta Bloqueada. Crea una clave nueva y configura tu aplicación para usarla.
- Nuevo prefijo de clave. Algunos desarrolladores señalan que las nuevas claves de autorización ya no empiezan por el conocido prefijo
AIza(artículo de ejemplo). Si una herramienta de terceros valida las claves por su prefijo, puede rechazar una clave nueva válida. Actualiza la herramienta en lugar de volver a una clave estándar. - Permisos para crear claves. Si el botón Crear indica que no tienes permisos, tu administrador de Cloud debe asignarte un rol con
apikeys.keys.create,serviceusage.services.enable,iam.serviceAccounts.createyiam.serviceAccountApiKeyBindings.create, entre otros. Si no tienes acceso de administrador, puedes crear un proyecto nuevo que no pertenezca a una organización.
Configura la clave como variable de entorno
Las bibliotecas cliente de Google leen GEMINI_API_KEY o GOOGLE_API_KEY automáticamente. Si ambas están definidas, GOOGLE_API_KEY tiene prioridad, una causa habitual de que «no se esté usando mi clave nueva».
# macOS / Linux (add to ~/.zshrc or ~/.bashrc, then open a new terminal)
export GEMINI_API_KEY="paste-your-key-here"
# Make sure an old key is not overriding it
unset GOOGLE_API_KEY
En Windows, añade GEMINI_API_KEY en Propiedades del sistema → Variables de entorno y abre una terminal nueva.
Prueba tu clave de API de Gemini
curl (Interactions API)
La guía de inicio rápido actual de Google usa el endpoint de Interactions con la clave en la cabecera x-goog-api-key:
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"input": "Reply with the single word: ok"
}'
Una respuesta JSON con texto de salida significa que la clave, el proyecto y el acceso al modelo funcionan correctamente. Un 403 suele indicar que la clave está restringida a otras API o bloqueada; un 429 significa que has alcanzado un límite de solicitudes (consulta más abajo).
Python (google-genai SDK)
# pip install google-genai
from google import genai
client = genai.Client() # reads GEMINI_API_KEY from the environment
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Explain what an API key is in one sentence.",
)
print(interaction.output_text)
Node.js (@google/genai)
// npm install @google/genai
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const interaction = await ai.interactions.create({
model: "gemini-3.8-flash",
input: "Explain what an API key is in one sentence.",
});
console.log(interaction.output_text);
Usa la misma clave con el OpenAI SDK
Gemini también ofrece un endpoint compatible con OpenAI. Resulta útil para herramientas que solo aceptan una URL base de OpenAI, como muchos agentes de programación y aplicaciones de chat:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
resp = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[{"role": "user", "content": "Say ok"}],
)
print(resp.choices[0].message.content)
Para configurar cada herramienta a través de una única pasarela, consulta Gemini API a través de un enrutador compatible con OpenAI.
¿La clave de API de Gemini es gratis?
La clave es gratis, y también hay un nivel gratuito con límites. La página de precios de Google (consultada el 27 de octubre de 2026) describe tres planes: Gratuito, De pago y Empresarial. El nivel gratuito ofrece tokens de entrada y salida gratis en determinados modelos, pero el contenido enviado en el nivel gratuito se utiliza para mejorar los productos de Google. En el nivel de pago, no. No envíes datos de clientes con una clave del nivel gratuito.
| Modelo | Nivel gratuito | Entrada / salida de pago por 1M de tokens (Estándar) |
|---|---|---|
| Gemini 4 Argon | No disponible | $2.00 / $10.00 hasta el 30 de noviembre de 2026; $4.00 / $20.00 a partir del 1 de diciembre de 2026 |
| Gemini 3.8 Flash | Sí | $0.75 / $3.75 hasta el 31 de diciembre de 2026; $1.50 / $7.50 a partir del 1 de enero de 2027 |
| Gemini 3.5 Flash-Lite | Sí | $0.30 / $2.50 |
| Gemini 3.1 Flash-Lite | Sí | $0.25 / $1.50 (texto, imagen, vídeo) |
Fuente: Precios de Gemini Developer API, 27 de octubre de 2026. Ten en cuenta las subidas de precios previstas: presupuesta las tarifas más altas si tu aplicación va a seguir funcionando después de esas fechas.
Cómo usar la Gemini API gratis
- Crea una clave en AI Studio sin vincular la facturación. El proyecto se mantiene en el nivel Gratuito.
- Usa un modelo que tenga nivel gratuito, como
gemini-3.8-flashogemini-3.5-flash-lite. Gemini 4 Argon solo está disponible de pago. - Respeta los límites de solicitudes del nivel gratuito que se muestran en AI Studio. Los límites se aplican por proyecto, no por clave, así que crear más claves en un proyecto no aumenta la cuota.
- Usa solo datos de prueba o públicos, porque el contenido del nivel gratuito puede utilizarse para mejorar los productos de Google.
Límites de solicitudes y niveles
Los límites de Gemini se miden en solicitudes por minuto (RPM), tokens de entrada por minuto (TPM) y solicitudes por día (RPD). Superar cualquiera de ellos devuelve un error, y el contador de RPD se reinicia a medianoche, hora del Pacífico (límites de solicitudes, 27 de octubre de 2026). Google también aplica límites basados en el gasto durante una ventana móvil de 10 minutos, que devuelven 429 RESOURCE_EXHAUSTED.
| Nivel | Requisitos de acceso | Límite de facturación del nivel |
|---|---|---|
| Gratuito | Proyecto activo o prueba gratuita | No aplicable |
| Nivel 1 | Vincular una cuenta de facturación activa | $250 |
| Nivel 2 | Haber pagado $100 + 3 días desde el primer pago completado correctamente | $2,000 |
| Nivel 3 | Haber pagado $1,000 + 30 días desde el primer pago completado correctamente | $20,000 a $100,000+ |
Fuente: Límites de solicitudes de la Gemini API, 27 de octubre de 2026. Consulta los límites exactos de cada modelo en AI Studio; Google indica que los límites publicados no están garantizados.
¿Qué puede hacer alguien con tu clave de API?
Cualquiera que tenga tu clave de Gemini puede enviar solicitudes que se facturen a tu proyecto y agotar tu cuota. La documentación de Google advierte de que una clave filtrada puede provocar «cargos de facturación inesperados» y dar acceso a datos privados del proyecto. Con una clave de autorización, el atacante actúa con la identidad de la cuenta de servicio vinculada y puede acceder a todo lo que esa cuenta tenga permitido (prácticas recomendadas para claves de API de Google Cloud). Por eso debes limitar al mínimo los permisos de la cuenta de servicio.
Si crees que se ha filtrado una clave:
- Crea una clave de sustitución en AI Studio.
- Despliega la clave nueva en tu aplicación y confirma que funciona.
- Desactiva la clave antigua en la consola de Cloud. No la elimines antes de que la nueva esté en uso, o provocarás una interrupción del servicio.
- Revisa la facturación y el uso de la API en la consola de Cloud para detectar tráfico desconocido. La página Uso de AI Studio agrupa el tráfico que no puede asociar a una clave con nombre como «(claves desconocidas)».
Solución de problemas: por qué no funciona tu clave de API de Gemini
| Síntoma | Causa probable | Solución |
|---|---|---|
403 o «Clave de API no válida» con una clave antigua |
Clave estándar sin restricciones, que ahora se rechaza | Restringirla solo a la Gemini API o crear una clave de autorización nueva |
| La clave aparece como Bloqueada en AI Studio | Clave sin restricciones que llevaba mucho tiempo inactiva, bloqueada desde el 7 de mayo de 2026 | Crear una clave nueva y actualizar tu aplicación |
| Tu código ignora la clave nueva | GOOGLE_API_KEY también está definida y tiene prioridad |
Eliminar esa variable o asignarle la clave nueva |
| Una herramienta de terceros indica que el formato de la clave es incorrecto | La herramienta espera el prefijo antiguo | Actualizar la herramienta o enrutar las solicitudes a través de una pasarela compatible con OpenAI |
| «No tienes permiso para crear una clave» | Faltan permisos de IAM en el proyecto de Cloud | Pedir ayuda a un administrador o usar un proyecto fuera de la organización |
429 RESOURCE_EXHAUSTED |
Límite de RPM, TPM, RPD o basado en el gasto | Reintentar con esperas progresivas, reducir el tamaño de las solicitudes o subir de nivel |
| Modelo no encontrado o no disponible | El modelo no está incluido en el nivel gratuito (p. ej., Gemini 4 Argon) | Vincular la facturación o elegir un modelo del nivel gratuito |
Para conocer patrones de gestión de errores entre proveedores, consulta nuestra taxonomía de errores de pasarelas de LLM.
Lista de comprobación para usar una clave de API de Gemini en producción
Que una clave funcione en un notebook no significa que esté lista para atender a usuarios. Antes del lanzamiento:
- Mantén la clave en el servidor. Nunca la incluyas en una aplicación web o móvil; Google indica que las claves del código cliente se pueden extraer. Coloca un pequeño proxy de backend entre tu cliente y Gemini.
- Usa una clave por entorno y por aplicación. Separa las claves de desarrollo, preproducción y producción para poder revocar una sin afectar a las demás. Asígnales nombres claros.
- Guárdala en un gestor de secretos. Google recomienda Secret Manager para producción. Carga la clave en tiempo de ejecución.
- Restringe por API y, cuando sea posible, por IP. Una clave de autorización está restringida a Gemini de forma predeterminada; añade restricciones por IP para los backends fijos.
- Limita los permisos de la cuenta de servicio. No concedas a la cuenta de servicio vinculada roles amplios que no necesite.
- Activa las alertas de facturación en la consola de Google Cloud para enterarte de un pico de gasto antes de recibir la factura.
- Fija los ID de los modelos. Usa ID exactos como
gemini-3.8-flashen la configuración y ten en cuenta los cambios de precios del 1 de diciembre de 2026 y del 1 de enero de 2027. - Usa el nivel de pago para los datos de usuarios. El contenido del nivel gratuito puede utilizarse para mejorar los productos de Google.
- Planifica la gestión de los límites de solicitudes. Añade esperas exponenciales entre reintentos para
429y decide qué hacer al alcanzar un límite: poner las solicitudes en cola, pasar a un modelo más pequeño o recurrir a una alternativa. - Analiza los repositorios en busca de claves filtradas. Activa la detección de secretos de GitHub y la protección de inserción.
- Rota las claves periódicamente. Crea la clave nueva, despliégala, verifica que funciona y después desactiva la antigua.
Para una revisión más exhaustiva, usa nuestra lista de comprobación de la Gemini API para producción y nuestra guía de gestión segura de claves de API.
Cuándo una clave de Flatkey simplifica el uso de una clave de Gemini
Si tu aplicación también llama a Claude, GPT, DeepSeek o Qwen, gestionar una clave, una cuenta de facturación y un nivel de límites de solicitudes por separado para cada proveedor supone más trabajo. Flatkey ofrece una única clave compatible con OpenAI y una URL base (https://router.flatkey.ai/v1) para Gemini y otros modelos, con registros de uso por clave (documentación de Flatkey). Valora con honestidad las diferencias de precio, que varían según el modelo. El 27 de octubre de 2026, las páginas de modelos de Flatkey mostraban:
| Modelo | Tarifa de Google (Estándar) | Flatkey |
|---|---|---|
| Gemini 4 Argon | $2.00 / $10.00 | $1.60 / $8.00 |
| Gemini 3.5 Flash-Lite | $0.30 / $2.50 | $0.24 / $2.00 |
| Gemini 3.8 Flash | $0.75 / $3.75 (promoción hasta el 31 de diciembre de 2026) | $1.20 / $6.00 |
Para Gemini 3.8 Flash, el precio promocional de Google es inferior al de Flatkey hasta el 31 de diciembre de 2026, así que una aplicación que solo use Flash tendrá menos costes si llama directamente a Google hasta entonces. Flatkey tiene más sentido para Argon, Flash-Lite o aplicaciones que combinan proveedores.
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["FLATKEY_API_KEY"], base_url="https://router.flatkey.ai/v1")
resp = client.chat.completions.create(
model="gemini-4-argon",
messages=[{"role": "user", "content": "Summarize this stack trace in one line."}],
)
print(resp.choices[0].message.content)
Preguntas frecuentes
¿Cómo obtengo una clave de API de Google Gemini?
Inicia sesión en aistudio.google.com/apikey, acepta las condiciones, elige o importa un proyecto de Google Cloud y haz clic en Crear clave de API. Los usuarios nuevos reciben automáticamente un proyecto y una clave predeterminados. La clave se muestra en la página Claves de API de AI Studio.
¿La clave de API de Gemini es gratis?
Sí. Crear una clave no cuesta nada, y modelos como Gemini 3.8 Flash y Gemini 3.5 Flash-Lite tienen un nivel gratuito con límites de solicitudes. El contenido del nivel gratuito puede utilizarse para mejorar los productos de Google, y Gemini 4 Argon no está disponible gratis.
¿Cómo uso la Gemini API gratis?
Crea una clave sin vincular la facturación, llama a un modelo del nivel gratuito como gemini-3.8-flash y respeta los límites que se muestran en AI Studio. Los límites se aplican por proyecto, así que añadir claves al mismo proyecto no aumenta la cuota.
¿Dónde puedo encontrar mi clave de API de Google?
En Google AI Studio, en Panel → Claves de API. Las claves restringidas a API de Google distintas de Gemini solo aparecen en la página de credenciales de la consola de Google Cloud.
¿Qué puede hacer alguien con mi clave de API?
Puede hacer solicitudes que se facturen a tu proyecto, agotar tu cuota y, con una clave de autorización, actuar con la identidad de la cuenta de servicio vinculada. Si sospechas que se ha filtrado, sustituye la clave, despliega la nueva, desactiva la antigua y revisa el uso.
¿Por qué dejó de funcionar mi antigua clave de API de Gemini?
Desde 2026, la Gemini API rechaza las claves estándar sin restricciones, y desde el 7 de mayo de 2026 bloquea las claves sin restricciones que llevaban mucho tiempo inactivas. Restringe la clave a la Gemini API o crea una clave de autorización nueva.
¿Puedo usar una clave de API de Gemini con el OpenAI SDK?
Sí. Configura la URL base como https://generativelanguage.googleapis.com/v1beta/openai/ y proporciona tu clave de Gemini como clave de API.
Conclusión
Obtener una clave de Gemini lleva dos minutos en AI Studio; mantenerla segura requiere algo más. Usa una clave de autorización, guárdala en el servidor en un gestor de secretos, aplica restricciones, configura alertas de facturación, usa el nivel de pago para datos de usuarios reales y vigila los cambios de precios previstos. Si trabajas con varios proveedores, una sola clave de pasarela puede sustituir a un conjunto de claves individuales. Compara modelos en el catálogo de modelos de Flatkey y consulta la guía de enrutamiento entre Gemini y Claude para saber cuándo enviar tráfico a cada uno.
