Clave API de Google AI Studio: crear, proteger y probar la primera llamada

Una clave de Google AI Studio autentica las llamadas a Gemini Developer API. No es una suscripción de consumo de Gemini, no compra un modelo y no crea una cuota separada por cada cadena. La clave pertenece a un proyecto de Google Cloud; ese proyecto concentra permisos, miembros, uso y relación de facturación.

Por eso el objetivo no es simplemente copiar la clave. La configuración termina cuando la credencial pertenece a un proyecto que controlas, se guarda fuera del código cliente y una petición mínima produce una respuesta identificable.

Confirma que la ruta directa se aplica a tu cuenta

Consulta la lista actual de regiones de Google AI Studio y Gemini API. España aparecía en la lista revisada el 29 de agosto de 2026. Google también indica un requisito de 18 años y puede exigir verificación de edad.

La presencia del país no garantiza por sí sola que una cuenta, una política de organización o un método de pago concretos sean válidos. Si AI Studio muestra una restricción de cuenta, edad o región, resuélvela por la vía oficial; no uses identidades, direcciones o proyectos ajenos para esquivarla.

Elige el propietario antes de crear la clave

Abre Google AI Studio API Keys con la cuenta que deba administrar la integración. Para una prueba personal puede ser tu proyecto. Para un servicio de empresa conviene que la organización conserve IAM, billing, rotación y revocación aunque cambien las personas del equipo.

La documentación actual de claves de Gemini API describe dos situaciones:

• una cuenta nueva puede recibir un proyecto Cloud y una clave por defecto tras aceptar las condiciones;
• una cuenta que ya usa Google Cloud puede tener que abrir Dashboard → Projects, importar el proyecto elegido y crear la clave desde API Keys.

Anota el project ID, no solo el nombre visible. Después podrás compararlo con Usage, Billing, límites y configuración desplegada sin confundir proyectos parecidos.

Si Create API key no está disponible, conserva el mensaje exacto. El administrador debe revisar los permisos de lectura del proyecto, creación de claves, activación del servicio, creación de service account y binding que enumera Google. Pedir una clave a otra persona no corrige IAM y deja el consumo fuera de tu control.

Comprueba que sea el tipo de clave actual

Las claves nuevas creadas en AI Studio son authorization keys o auth keys, vinculadas a una service account y restringidas a Gemini API de forma predeterminada. Google está retirando las standard keys y su documento actual anuncia que serán rechazadas en septiembre de 2026.

La fecha y la interfaz pueden cambiar. Revisa la columna Key Type y vuelve a leer la fuente oficial antes de una migración. No diseñes producción alrededor de una unrestricted standard key tomada de un tutorial anterior.

Guarda el secreto fuera del cliente

Quien obtiene la clave puede consumir cuota del proyecto y, si hay billing, generar cargos. No la incluyas en Git, issues, capturas, dumps de entorno, JavaScript de producción, una app móvil o una URL que termine en logs.

Los SDK actuales detectan GEMINI_API_KEY o GOOGLE_API_KEY. Si ambas existen, GOOGLE_API_KEY tiene prioridad. Una variable antigua puede explicar por qué cambiar GEMINI_API_KEY no modifica el resultado.

bash
export GEMINI_API_KEY="YOUR_API_KEY"

El valor del ejemplo es un marcador. En producción usa un gestor de secretos del servidor y haz que el navegador o la aplicación móvil llame a tu backend. Comprueba la presencia sin imprimir la clave:

bash
if [ -n "${GEMINI_API_KEY:-}" ]; then
  echo "GEMINI_API_KEY configurada"
else
  echo "Falta GEMINI_API_KEY"
fi

Envía un canary pequeño y actual

La guía get-started actual de Google muestra el endpoint Interactions y el modelo gemini-3.7-flash. La clave viaja en una cabecera, no en la URL:

bash
curl -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.7-flash",
    "input": "Confirma en una frase breve que la conexión API funciona."
  }'

No evalúes una frase exacta. La señal válida es una respuesta estructurada del hostname esperado, autenticada con la credencial del proyecto previsto, con estado completado y salida del modelo.

Los model IDs y las superficies API cambian. Si el quickstart vigente usa otro ejemplo, actualiza el canary desde esa página en lugar de probar nombres antiguos al azar.

Conserva el error que ayuda a decidir

Antes de rotar nada, guarda HTTP status, cuerpo saneado, project ID, endpoint, modelo, hora UTC y request ID. Nunca guardes la clave completa. Cambia una sola variable y repite el mismo canary.

Una llamada correcta prueba la autenticación de ese camino, no su capacidad de producción. Una clave válida puede chocar con la cuota; un proyecto de pago puede usar una variable equivocada.

Separa creación, cuota y facturación

Crear la clave no tiene una tarifa independiente. Free solo cubre ciertos modelos y modos; los límites activos son los que AI Studio muestra para el proyecto y modelo seleccionados. Varias claves del mismo proyecto no equivalen a varias bolsas de cuota.

Decide Free, Paid o Prepay después de medir la primera llamada y la carga real. Para la decisión económica usa la guía de precios de Gemini API y la tabla oficial vigente.

Antes de producción deja registrados project ID, propietario de la credencial, Key Type, ubicación del secreto, responsable de rotación, backend permitido, modelo, live limits y estado de billing. Esa ficha permite revocar con precisión y evita que una integración dependa de una cadena sin dueño.