La Gemini API key se crea desde la pantalla de API Keys de Google AI Studio. Ese paso solo confirma que tienes una credencial; no confirma que la primera petición a Gemini API vaya a funcionar. La ejecución real depende del Google Cloud project asociado, la región de uso, el estado de billing o Free Tier, el modelo elegido, los active limits del proyecto y la seguridad de la key.
Antes de cambiar código o crear varias keys nuevas, revisa estas 6 condiciones.
| Qué comprobar primero | Por qué afecta a la llamada | Qué hacer si falla |
|---|---|---|
| Proyecto | La API key está asociada a un Google Cloud project; permisos, billing, uso y límites siguen al proyecto. | Confirma que la key pertenece al proyecto que vas a usar. |
| Región | Google AI Studio / Gemini API solo está disponible en países y territorios listados por Google. | Consulta available regions. Al 27 de abril de 2026, Taiwan aparece; Mainland China, Hong Kong y Macao no aparecen en la lista de AI Studio/Gemini API. |
| Billing / Free Tier | Free Tier cubre solo ciertos modelos y condiciones; Paid Tier requiere billing account activo y puede requerir prepay. | Revisa el estado de billing antes de asumir que el modelo será gratuito. |
| Modelo | Una key válida no habilita todos los modelos; los preview pueden cambiar o cerrarse. | Elige el model ID desde la documentación actual de modelos. |
| Active limits | RPM, TPM y RPD se evalúan por proyecto y modelo; más keys en el mismo proyecto no suman capacidad. | Abre active limits en AI Studio y reduce tráfico si estás cerca del límite. |
| Seguridad | Una key expuesta en frontend, repositorios, logs o capturas puede bloquearse o generar coste no autorizado. | Genera una key nueva, rota secretos y elimina la exposición. |
Dónde crear una Google AI Studio API key
La ruta oficial es abrir Google AI Studio API Keys, iniciar sesión con una cuenta de Google, elegir o crear un Google Cloud project y generar una Gemini API key. La documentación de Gemini API keys explica que para usar Gemini API necesitas una API key y que esa key se administra dentro del contexto de un proyecto.
El proyecto no es un detalle administrativo. La key no es una contraseña aislada; arrastra ownership, permisos, billing, usage, limits y recuperación. Una key creada por defecto puede vivir en un proyecto automático. Una key enviada por otra persona puede pertenecer al proyecto de esa persona. Si miras billing o quota en un proyecto distinto, el diagnóstico empieza mal.
Copia la key una sola vez y guárdala en un lugar seguro. Google permite hardcode temporal para una prueba inicial, pero eso no debe llegar a código público, browser bundle, app móvil, repositorios, capturas, issues ni chats. En desarrollo usa GEMINI_API_KEY o GOOGLE_API_KEY como variables de entorno; en producción usa variables privadas del servidor o un secret manager.
Si no ves una key restringida dentro de AI Studio, no concluyas que desapareció. Google indica que AI Studio muestra keys sin restricciones o restringidas a Generative Language API; restricciones más finas se gestionan en Google Cloud Console. El error común no es solo no encontrar el botón, sino mezclar proyectos, copiar una key equivocada o tratar una variable pública de frontend como si fuera un secreto de servidor.
Las 6 condiciones que deben cuadrar después de crear la key
Cuando la key ya existe, la siguiente pregunta no es “qué snippet copio”, sino “qué condiciones hacen que este proyecto pueda ejecutar la petición”.
| Condición | Estado esperado | Lectura equivocada frecuente |
|---|---|---|
| Proyecto actual | La key pertenece al proyecto donde verás billing, usage y limits. | Copiar una key de otro proyecto y revisar cuota en el proyecto actual. |
| Región soportada | Tu uso encaja con la lista de Google AI Studio / Gemini API. | Asumir que Gemini web disponible equivale a Gemini API disponible. |
| Billing | Free Tier o Paid Tier encaja con el modelo y el volumen. | Pensar que crear key concede todos los modelos gratis. |
| Modelo | El modelo aparece en la documentación actual y es compatible con el proyecto. | Reutilizar un preview ID de un tutorial antiguo. |
| Active limits | RPM, TPM, RPD u otros límites no están agotados. | Crear otra key del mismo proyecto para intentar ampliar cuota. |
| Seguridad | La key no está expuesta ni marcada como leaked. | Seguir usando una key filtrada porque aún parece responder. |
El orden ayuda. Primero confirma el proyecto porque billing y limits solo tienen sentido dentro del mismo owner. Luego revisa región. Si la región no encaja, cambiar SDK, prompt o endpoint al azar no resuelve el bloqueo. Después separa billing / Free Tier y modelo. Al final mira active limits y seguridad, dos causas frecuentes cuando algo funcionaba ayer y hoy devuelve errores.
Para un análisis más profundo de límites gratuitos, conviene leer Límites de la capa gratuita de Gemini API: qué sigue siendo gratis y dónde ver tu cuota real. Aquí el foco es que la key llegue a una primera llamada real sin mezclar credencial, región, billing y capacidad.
Cómo poner la key en variables de entorno y probar una petición pequeña
La primera prueba no debería ser una demo grande. Debería confirmar tres cosas: la aplicación lee la key, el proyecto puede llamar al modelo y los límites actuales no bloquean una petición mínima.
En local puedes empezar con variables de entorno simples.
hljs bashexport GEMINI_API_KEY="tu key real solo en local o servidor"
export MODEL_ID="modelo elegido desde la documentación actual"
La petición de salud debe ser corta y repetible. La forma siguiente mantiene tres límites sanos: la key se lee desde entorno, el model ID no queda congelado en un valor viejo y el payload es pequeño.
hljs bashcurl "https://generativelanguage.googleapis.com/v1beta/models/${MODEL_ID}:generateContent?key=${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{ "text": "Reply with one short sentence." }
]
}
]
}'
Con SDK oficial el criterio es el mismo: key desde variable privada, modelo desde docs actuales, petición corta, y solo después más contexto, tools, files, batch, retry o concurrencia. Si cargas tráfico real, documentos largos, frontend público y cola de reintentos sobre una key recién creada, perderás la capacidad de saber qué condición falló.
Los proyectos frontend necesitan una parada adicional. Una Gemini API key es una credencial que puede generar coste y abuso. No debe aparecer en NEXT_PUBLIC_, bundles de navegador, apps móviles, archivos estáticos ni JavaScript descargable. La estructura más segura es que el browser llame a tu backend, y el backend lea la key desde una variable privada antes de llamar a Gemini API.
Crear una key gratis no significa uso gratis
Crear una API key y consumir Gemini API son cosas distintas. La key es una credencial, no una bolsa de cuota. La documentación de rate limits trata los límites por proyecto, modelo y tier; los active limits reales se consultan en AI Studio. Varias keys dentro del mismo proyecto suelen compartir los mismos límites.
La documentación de billing separa Free Tier y Paid Tier. Un usuario nuevo puede empezar en Free Tier, pero solo ciertos modelos y condiciones quedan dentro de esa capa. Paid Tier requiere un billing account activo y prepay. La página actual de billing también puede mostrar un mínimo de 10 USD para setup nuevo; ese tipo de umbral cambia y debe confirmarse en la pantalla oficial antes de desplegar.
| Duda | Dónde mirarla | Qué no asumir |
|---|---|---|
| Si un modelo es gratuito | Pricing, billing y model docs de Google | No uses capturas antiguas como fuente final. |
| Cuánto puede usar tu proyecto | Active limits en AI Studio | No calcules capacidad por key individual. |
| Qué significa 429 | Rate limits y troubleshooting | No resuelvas creando otra key del mismo proyecto. |
| Cuándo activar pago | Billing, presupuesto y riesgo del workload | No trates Free Tier como promesa de producción. |
Free Tier sirve para aprendizaje, prototipos pequeños y pruebas de bajo riesgo. Si hay usuarios externos, datos sensibles, volumen estable, demos con clientes, servicios persistentes o 429 repetidos, prepara paid project, budget alerts, límites de datos y recuperación. Lo gratuito valida una idea; no reemplaza capacity planning.
Región y 403 se diagnostican por ruta
La región debe evaluarse por producto. Gemini web, mobile app, Google AI Studio, Gemini API y Vertex AI no comparten una sola tabla. Para una API key creada en AI Studio, la referencia es Google AI Studio / Gemini API available regions.
Al 27 de abril de 2026, Taiwan aparece en la lista oficial de Gemini API available regions. Mainland China, Hong Kong y Macao no aparecen en la lista de AI Studio/Gemini API. Ese dato se limita a la ruta Google AI Studio / Gemini API; no prueba ni niega por sí solo disponibilidad de Gemini web, mobile app, Workspace o Vertex AI.
Un 403 PERMISSION_DENIED debe tratarse primero como problema de owner y condiciones de ruta. La documentación de troubleshooting apunta a causas como wrong key, insufficient permission, unsupported free-tier region o authentication mismatch. La secuencia práctica es: proyecto correcto, región y Free Tier, billing, modelo disponible para el proyecto, y método de autenticación adecuado para la API.
| Error o síntoma | Causa más probable | Primero revisa | Siguiente paso |
|---|---|---|---|
| 403 / permission denied | Key, proyecto, permisos, región o Free Tier no encajan | API key docs, available regions, permisos del proyecto | Vuelve al proyecto o ruta correcta y detén reintentos inútiles. |
| Falla solo un modelo | Modelo retirado, preview cambiado, billing o región insuficiente | Model docs actuales | Cambia a un modelo disponible o habilita el billing necesario. |
| AI Studio abre pero la API falla | La UI y la API no son el mismo contrato | Project, region, billing, model | No uses acceso a la web como prueba de API. |
| Colab o runtime cloud falla | El runtime puede estar en otra región o proyecto | Region del runtime y error completo | Usa runtime soportado o cambia de ruta oficial. |
Si el problema es una disponibilidad de Gemini más amplia, revisa ¿Gemini no está disponible en tu región? Divide primero web, app y API. Ese tema separa entradas de consumidor, API, Vertex y gateway. Aquí se mantiene el límite de AI Studio API key y la primera llamada a Gemini API.
Cómo recuperar 429, modelo no disponible o key filtrada
429 RESOURCE_EXHAUSTED suele indicar límite o cuota agotada. No mires solo número de peticiones; también cuentan tokens, concurrencia, modelo, project tier, límite diario y tormentas de retry. La documentación de rate limits usa dimensiones como RPM, TPM y RPD, y RPD puede resetearse a medianoche Pacific Time. La capacidad real depende del proyecto y del modelo.
La recuperación debe ir de menor a mayor coste.
- Confirma en AI Studio qué proyecto está detrás de la key.
- Revisa si active limits muestra RPM, TPM, RPD u otra dimensión agotada.
- Baja concurrencia, añade exponential backoff y detén reintentos sin límite.
- Reduce prompts, cachea respuestas repetidas y divide batch jobs.
- Comprueba si el modelo necesita Paid Tier o más capacidad.
- Si el tráfico normal sigue chocando, solicita quota increase o migra a un proyecto con billing.
Cuando el problema es modelo no disponible, no cambies a otro ID copiado de un tutorial. La página de models es la referencia actual. Un ejemplo claro es Gemini 3 Pro Preview: se cerró el 9 de marzo de 2026 y Google indicó migración a Gemini 3.1 Pro Preview. La configuración resistente no memoriza un ID histórico; guarda el model ID como variable y lo actualiza contra docs actuales.
Una key filtrada se rota, no se “vigila”. Google indica que puede bloquear API keys reportadas como leaked. El orden sano es crear una key nueva, actualizar environment variables o secret manager, eliminar la key antigua de lugares públicos, revisar uso y billing anómalos, y después desactivar o borrar la key anterior.
La seguridad forma parte del setup. Si la key apareció en GitHub público, bundle frontend, screenshot, issue, log o herramienta online de terceros, trátala como filtrada. Una configuración madura puede responder tres preguntas: quién puede leer la key, dónde se audita el uso y quién ejecuta la rotación cuando se expone.
AI Studio, Vertex AI, Android Studio y gateway no son lo mismo
Muchos tutoriales mezclan Google AI Studio, Gemini API, Vertex AI, Android Studio y gateways de terceros. Son contratos distintos.
| Ruta | Qué resuelve | Para quién encaja | Límite principal |
|---|---|---|---|
| Google AI Studio / Gemini API key | Crear rápido una credencial para llamar a Gemini API | Desarrolladores individuales, prototipos, backends pequeños | Región, Free Tier, billing y active limits se revisan por proyecto. |
| Vertex AI | Ruta enterprise dentro de Google Cloud | Equipos con GCP, IAM, endpoints regionales y governance | IAM, endpoint, billing y data boundary son distintos. |
| Android Studio Gemini API key | Configuración dentro del IDE o entorno Android | Desarrolladores Android | No reemplaza gestión de key para backend de producción. |
| Gateway de terceros | Un proveedor empaqueta modelos, billing, logs y soporte | Necesidades multi-modelo o API compatible | Hay que verificar precio, cobertura, logs, soporte y salida. |
Para crear y probar una Gemini API key, la ruta base es AI Studio. Si necesitas IAM de Google Cloud, endpoint regional, organización, compliance o governance, evalúa Vertex AI por separado. Un gateway puede ser útil como contrato de proveedor independiente, pero no es prueba de que desaparezcan las reglas de región, billing o soporte de Google.
Checklist final de preparación
La configuración no termina cuando ves una cadena de caracteres. Deberías poder responder cada punto.
| Pregunta | Criterio de listo |
|---|---|
| ¿De dónde viene la key? | Fue creada en Google AI Studio API Keys y conoces el Google Cloud project asociado. |
| ¿Dónde se guarda? | Solo local, servidor o secret manager; no frontend ni repositorio público. |
| ¿Cómo eliges modelo? | Desde model docs actuales, sin preview ID retirado. |
| ¿Cómo separas gratis y pago? | Free Tier / Paid Tier se confirma en billing, pricing y AI Studio. |
| ¿Dónde ves límites? | Active limits del proyecto en AI Studio, incluyendo RPM, TPM y RPD. |
| ¿Cómo tratas 403? | Proyecto, región, permisos, billing y modelo antes de reescribir código. |
| ¿Cómo tratas 429? | Backoff, concurrencia, prompt size y cache antes de quota increase o billing. |
| ¿Cómo tratas filtración? | Key nueva, secretos actualizados, key antigua retirada y uso revisado. |
Si una respuesta queda abierta, la key está creada pero no preparada para uso real. Cierra esas preguntas antes de conectar tráfico o automatizaciones.
Preguntas frecuentes
¿Google AI Studio API key es gratis?
Crear la key normalmente no tiene coste. Usar Gemini API depende del modelo, proyecto, región, Free Tier, billing y active limits. La key no es una promesa de uso gratuito para todos los modelos.
¿Debo usar GEMINI_API_KEY o GOOGLE_API_KEY?
La documentación de API keys indica que las Gemini API libraries pueden usar GEMINI_API_KEY o GOOGLE_API_KEY. En equipo conviene estandarizar un nombre y documentar origen, scope y rotación.
¿Varias API keys aumentan la cuota de Gemini API?
No lo trates como expansión. La cuota pertenece al proyecto, modelo y tier, no a cada string de key. Varias keys sirven para separar entornos, rotar secretos y gestionar permisos.
¿Por qué una key recién creada devuelve 403?
Puede pertenecer a otro proyecto, faltar permiso, fallar la región, no cumplir Free Tier, requerir billing o usar una autenticación que no corresponde a Gemini API. Empieza por proyecto, región, billing y modelo.
¿Por qué ayer funcionaba y hoy aparece 429?
Puede haberse agotado RPM, TPM, RPD, subir tráfico, crecer el tamaño del prompt, dispararse retry o cambiar el modelo. Revisa active limits en AI Studio y reduce carga antes de escalar.
¿Mainland China, Hong Kong o Macao pueden usar Google AI Studio / Gemini API directamente?
Al 27 de abril de 2026, esos territorios no aparecen en la lista oficial de Google AI Studio / Gemini API available regions; Taiwan sí aparece. La disponibilidad puede cambiar y debe confirmarse antes de desplegar.
¿Si Gemini web funciona, también funciona Gemini API key?
No necesariamente. Gemini web, mobile app, AI Studio, Gemini API y Vertex AI tienen regiones, cuentas, billing y límites distintos. La configuración de API key debe evaluarse con documentación de Google AI Studio / Gemini API.
¿Puedo seguir usando una key filtrada?
No es recomendable. Google puede bloquear keys expuestas. Genera una nueva, actualiza secretos del servidor, elimina la key antigua de lugares públicos, revisa uso y desactiva la anterior.
¿Cuándo elegir Vertex AI en lugar de AI Studio?
AI Studio / Gemini API key encaja para desarrollo individual, prototipos y backends pequeños. Vertex AI encaja cuando ya necesitas GCP IAM, endpoints regionales, governance empresarial y controles de datos.
¿Qué model ID debo dejar en el ejemplo de código?
No fijes un preview ID antiguo. Elige un model ID disponible en los model docs actuales y guárdalo como configuración. Si el estado del modelo cambia, deberías poder actualizarlo sin reescribir todo el código.
