Gemini API — Setup, Billing y Gestion de Claves

Proyecto: CreaRack Pro Fecha: 08-03-2026 Uso: Auto-Plan AI + CreaRack Network Sentinel (CNS) Explain

1. Resumen

CreaRack Pro usa la Generative Language API de Google (modelo gemini-3-flash-preview) para dos funcionalidades:

Funcionalidad	Descripcion
Auto-Plan AI	Analisis automatico de planos de datacenter
CNS Explain	Respuestas contextuales sobre insights de Network Sentinel

Ambas usan la misma API key (GEMINI_API_KEY) y el SDK Python google-genai.

2. Free Tier vs Paid Tier

Aspecto	Free Tier	Paid Tier (Pay-as-you-go)
Limite requests	20/dia por modelo	1,500/minuto (~2.1M/dia)
Coste	$0	~$0.10 / millon tokens input
Requiere tarjeta	No	Si
Apto para produccion	No	Si

Coste real estimado: ~$0.0001 por peticion. Ver seccion 9.3 para estimaciones detalladas por escenario SaaS.

IMPORTANTE: El free tier de 20 peticiones/dia es insuficiente para produccion. Siempre usar paid tier.

3. Crear el Proyecto en Google Cloud

3.1 Acceder a Google Cloud Console

URL: https://console.cloud.google.com
Iniciar sesion con la cuenta de Google del proyecto

3.2 Crear o seleccionar un proyecto

Click en el selector de proyectos (barra superior)
Nuevo Proyecto (o seleccionar uno existente)
Nombre: CreaRack-Pro (o el que prefieras)
Click Crear

4. Activar la API

Ir a: https://console.cloud.google.com/apis/library
Buscar: Generative Language API
Click en el resultado → Habilitar

Sin este paso, la API key no funcionara aunque exista.

5. Activar Facturacion (Billing)

5.1 Crear cuenta de facturacion

Ir a: https://console.cloud.google.com/billing
Si no hay cuenta de facturacion: Crear cuenta
Vincular tarjeta de credito/debito
Completar datos fiscales

5.2 Vincular billing al proyecto

En la misma pagina de billing, pestaña Mis proyectos
Buscar tu proyecto (CreaRack-Pro)
Click en Acciones (tres puntos) → Cambiar facturacion
Seleccionar la cuenta de facturacion creada
Guardar

Verificacion: Ir a https://console.cloud.google.com/billing y confirmar que el proyecto aparece con estado “Cuenta de facturacion activa”.

6. Crear la API Key

Ir a: https://console.cloud.google.com/apis/credentials
Click Crear credenciales → Clave de API
Copiar la clave generada (formato: AIzaSy...)

6.1 Restringir la clave (recomendado)

Google muestra un aviso si la clave no esta restringida. Para restringirla:

En la lista de credenciales, click en la clave (icono de lapiz)
Seccion Restricciones de API → seleccionar Restringir clave
En el desplegable, marcar solo: Generative Language API
Click Guardar

Esto asegura que la clave solo puede usarse para Gemini, no para otros servicios de Google.

Nota: Tanto Auto-Plan como CNS Explain usan la misma Generative Language API. Una sola restriccion cubre ambos.

7. Configurar la Key en CreaRack

7.1 Entorno local (desarrollo)

Editar el archivo .env en la raiz del proyecto:

GEMINI_API_KEY=AIzaSy...tu_clave_aqui...

Reiniciar:

docker compose restart web

7.2 Produccion (Dokploy)

Abrir Dokploy → seleccionar aplicacion CreaRack
Pestaña Environment (Variables de entorno)
Buscar GEMINI_API_KEY y reemplazar el valor
Guardar
Si no hace deploy automatico: click Deploy manualmente

IMPORTANTE: Cambiar variables de entorno en Dokploy no siempre dispara autodeploy. Solo los push a GitHub lo hacen. Si no se redespliega, pulsar Deploy manualmente.

8. Verificar que Funciona

8.1 Verificar desde la app

Ir a Observatory → pestaña CNS
Abrir un insight (boton Details)
Escribir una pregunta y pulsar Explain
Debe responder sin error de quota

8.2 Verificar cuotas

URL: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
La fila “Request limit per model per day for a project in the free tier” puede seguir en 20 — es normal
Lo que importa es que existan filas de paid tier (tier 1, tier 2, etc.) con limites mayores

9. Monitoring de Uso y Costes

9.1 Ver uso de la API

URL: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/metrics
Muestra: requests/dia, errores, latencia

9.2 Ver costes

URL: https://console.cloud.google.com/billing
Seccion Informes para ver desglose por servicio
Configurar alertas de presupuesto para evitar sorpresas:
1. Billing → Presupuestos y alertas
2. Crear presupuesto
3. Ejemplo: $10/mes con alerta al 80%

9.3 Estimacion de costes SaaS

Gemini 3 Flash Preview tiene un coste aproximado de ~$0.10 por millon de tokens de input y ~$0.40 por millon de tokens de output (paid tier).

Coste por peticion

Tipo de peticion	Tokens input (aprox)	Tokens output (aprox)	Coste estimado
`create_insight` (anomaly → diagnostico)	~800	~400	~$0.00025
`explain_insight` (pregunta usuario)	~500	~300	~$0.00015
`auto_plan` (analisis de plano)	~1,200	~600	~$0.00040

Conclusion: El coste por peticion es despreciable (~$0.0001–$0.0004).

Escenarios SaaS mensuales

Suponiendo un SaaS con varias cuentas y diferentes niveles de actividad:

Escenario	Cuentas	Devices/cuenta	Anomalias/dia/device	Insights/mes	Coste/mes
Startup	3	20	0.5	~900	~$0.23
Crecimiento	10	50	0.5	~7,500	~$1.88
Enterprise	10	300	0.3	~27,000	~$6.75
Pico (incidente)	10	300	2.0	~180,000	~$45.00

Nota: El escenario “Pico” asume un evento de red grave (ej: fallo de switch core) donde muchos devices generan anomalias simultaneamente. Es temporal y no sostenido.

Explains adicionales (preguntas de usuarios)

Los Explains son peticiones manuales del usuario (boton “Explain” en el modal de insight). Estimacion:

Escenario	Explains/dia	Coste adicional/mes
Bajo (1-2 admins)	5	~$0.02
Medio (equipo NOC)	50	~$0.23
Alto (multiples turnos)	200	~$0.90

Auto-Plan (analisis de planos)

Cada uso de Auto-Plan analiza un plano de datacenter. Estimacion:

Uso	Frecuencia	Coste/mes
Diseño inicial	5-10 planos/mes	~$0.004
Iteraciones	20-50/mes	~$0.02
Produccion SaaS	100-500/mes	~$0.20

Resumen de coste total estimado

Escenario SaaS	Insights	Explains	Auto-Plan	Total/mes
Startup (3 cuentas)	$0.23	$0.02	$0.004	~$0.25
Crecimiento (10 cuentas)	$1.88	$0.23	$0.02	~$2.13
Enterprise (10×300 devices)	$6.75	$0.90	$0.20	~$7.85

Conclusion: Incluso en el escenario Enterprise con 3,000 dispositivos, el coste mensual de la API de Gemini es inferior a $10/mes. Los picos por incidentes graves son temporales y no superan $50/mes.

Alertas de presupuesto recomendadas

Tier SaaS	Alerta 80%	Presupuesto mensual
Startup	$2	$3
Crecimiento	$5	$10
Enterprise	$20	$30

Configurar en: Cloud Console → Billing → Presupuestos y alertas (ver seccion 9.2)

10. Diferencia entre Google AI Studio y Google Cloud Console

Existen dos formas de obtener una API key de Gemini. Es importante no confundirlas:

Aspecto	Google AI Studio	Google Cloud Console
URL	https://aistudio.google.com	https://console.cloud.google.com
Tipo	Herramienta rapida para prototipos	Plataforma completa de infraestructura
Billing	Limitado, no siempre disponible	Completo, con tarjeta vinculada
Keys	Se crean desde la interfaz de AI Studio	Se crean desde Credenciales
Recomendado para produccion	No	Si

Leccion aprendida (08-03-2026): Si la key se creo en AI Studio y el billing se activo en Cloud Console (proyecto diferente), los limites no cambian. Hay que crear la key desde el mismo proyecto de Cloud Console que tiene billing.

11. Proteccion contra Rate Limits

CreaRack implementa un sistema de proteccion en 4 capas para evitar perdida de datos y errores por limites de la API de Gemini.

11.1 Rate limiting propio (pre-API)

Antes de llamar a Gemini, el sistema limita las peticiones para no saturar la API:

Limite	Valor	Ambito
Insights por dispositivo	5/hora	Por cada MonitoringTarget
Insights por tenant	100/hora	Por organizacion (SaaS)

Configurado en: monitoring/services/insight_service.py → RATE_LIMIT_PER_DEVICE, RATE_LIMIT_PER_TENANT

Por que estos valores:

5/hora/device: Si un dispositivo genera mas de 5 anomalias/hora, los primeros 5 insights ya cubren el diagnostico. Mas seria redundante.
100/hora/tenant: Dimensionado para redes grandes (hasta 300 devices). Cubre eventos de red donde muchos dispositivos reportan anomalias simultaneamente (ej: switch core caido que afecta a 50+ devices).

11.2 Exponential Backoff (reintentos automaticos)

Si Gemini devuelve un error 429 (Too Many Requests) o RESOURCE_EXHAUSTED, el sistema reintenta automaticamente con delays crecientes:

Intento	Delay antes de reintentar
1	0s (primer intento inmediato)
2	2s
3	4s

Max reintentos: 3
Delay inicial: 2 segundos
Multiplicador: 2x (exponencial)
Delay maximo: 30 segundos

Configurado en: monitoring/services/ai_providers/gemini.py → MAX_RETRIES, INITIAL_DELAY, BACKOFF_MULTIPLIER

Esto cubre tanto la generacion de insights (Agent) como las preguntas Explain (browser).

11.3 Fallback a Static Rules

Si Gemini falla tras los 3 reintentos durante la creacion de insights (llamada desde el Agent), el sistema cae automaticamente a un proveedor de reglas estaticas que genera un diagnostico basico sin IA:

Gemini falla → 3 reintentos con backoff → sigue fallando → StaticRulesProvider

Esto garantiza que nunca se pierde un insight por un error transitorio de la API.

Nota: El fallback a Static Rules solo aplica a create_insight. El Explain (pregunta del usuario) no tiene fallback a Static Rules porque no tendria sentido — necesita IA real para responder.

11.4 Mensaje amigable al usuario

Si el Explain falla tras los reintentos, el usuario ve un mensaje legible en la interfaz en lugar de un error tecnico crudo:

“Gemini API quota exceeded. Try again in a few minutes.”

Resumen visual del flujo

Peticion a Gemini
    ├── OK → Respuesta normal
    └── Error 429/RESOURCE_EXHAUSTED
        ├── Reintento 1 (espera 2s)
        │   ├── OK → Respuesta normal
        │   └── Error 429
        │       ├── Reintento 2 (espera 4s)
        │       │   ├── OK → Respuesta normal
        │       │   └── Error 429
        │       │       ├── create_insight → Fallback a StaticRules
        │       │       └── Explain → Mensaje "quota exceeded" al usuario
        └── Otro error (no 429) → Error inmediato, sin reintentos

12. Troubleshooting

Error: “RESOURCE_EXHAUSTED” / “quota exceeded”

Causa: Free tier agotado (20 req/dia) o billing no vinculado
Solucion: Verificar billing activo en el proyecto de la key (seccion 5)

Error: “API key not valid”

Causa: Key incorrecta o API no habilitada
Solucion: Verificar que Generative Language API esta habilitada (seccion 4)

Explain responde vacio

Causa: Timeout o error silencioso del provider
Solucion: Verificar logs con docker compose logs -f web

Cambio de key no surte efecto en produccion

Causa: Dokploy no redesplego
Solucion: Deploy manual desde panel de Dokploy (seccion 7.2)

13. URLs de Referencia Rapida

Que	URL
Cloud Console	https://console.cloud.google.com
APIs habilitadas	https://console.cloud.google.com/apis/dashboard
Credenciales (keys)	https://console.cloud.google.com/apis/credentials
Billing	https://console.cloud.google.com/billing
Cuotas Gemini	https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
Metricas uso	https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/metrics
AI Studio (prototipos)	https://aistudio.google.com
Rate limits documentacion	https://ai.google.dev/gemini-api/docs/rate-limits

Ultima actualizacion: 08-03-2026 Mantenido por: Equipo CreaRack

Véase también

[[decision—20260401—gemini-3-flash-preview]] — ADR modelo Gemini fijo
[[crearack-tech—backend—auto-plan-technical-reference]] — referencia técnica de Auto-Plan AI
[[crearack-tech—agents—dev-map-editor]] — perfil de subagente dev-map-editor
[[crearack-tech—guides—ollama-self-hosted-ai]] — evaluación de Ollama self-hosted
[[crearack-tech—guides—secret-rotation-playbook]] — playbook de rotación de secretos
[[crearack—blueprints—auto-plan-ai]] — generador AI de planos