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:

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

2. Free Tier vs Paid Tier

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

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

4. Activar la API

1. Ir a: https://console.cloud.google.com/apis/library
2. Buscar: Generative Language API
3. 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

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

5.2 Vincular billing al proyecto

1. En la misma pagina de billing, pestaña Mis proyectos
2. Buscar tu proyecto (CreaRack-Pro)
3. Click en Acciones (tres puntos) → Cambiar facturacion
4. Seleccionar la cuenta de facturacion creada
5. 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

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

6.1 Restringir la clave (recomendado)

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

1. En la lista de credenciales, click en la clave (icono de lapiz)
2. Seccion Restricciones de API → seleccionar Restringir clave
3. En el desplegable, marcar solo: Generative Language API
4. 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)

1. Abrir Dokploy → seleccionar aplicacion CreaRack
2. Pestaña Environment (Variables de entorno)
3. Buscar GEMINI_API_KEY y reemplazar el valor
4. Guardar
5. 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

1. Ir a Observatory → pestaña CNS
2. Abrir un insight (boton Details)
3. Escribir una pregunta y pulsar Explain
4. 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

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:

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:

Auto-Plan (analisis de planos)

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

Resumen de coste total estimado

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

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:

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:

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:

• 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

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