Conectar Google Gemini a JMAX: cómo conseguir una clave que funcione

Guía hecha sobre el caso real del 11 de septiembre de 2026, con las capturas de cada pantalla. Sirve para un cliente que quiera usar Gemini como cerebro de nube en JMAX y se encuentre con los mismos errores.

Lo que hay que saber antes de empezar (2026)

1. AI Studio ya solo emite claves AQ. (claves de autorización enlazadas a una cuenta de servicio). Las AIza de antes dejaron de emitirse y serán rechazadas desde septiembre de 2026.
2. Una clave AQ. creada en un proyecto sin cuenta de servicio válida devuelve 401 ACCESS_TOKEN_TYPE_UNSUPPORTED en todas las rutas. No es un fallo de JMAX ni del endpoint: es la clave.
3. La clave se crea en Google Cloud Console (APIs y servicios → Credenciales), enlazada a una cuenta de servicio del proyecto, con la restricción Gemini API. Así salió la que funciona.
4. Los 300 USD de prueba de Google Cloud NO pagan la Gemini API desde marzo de 2026. Un proyecto en prueba gratuita queda en «Prepay required» y contesta 429 Your prepayment credits are depleted. Hay que usar un proyecto en Free tier (o cargar prepago).
5. Vertex AI por clave de API está bloqueado en organizaciones de Google Cloud: en el desplegable de restricciones «Agent Platform API» aparece deshabilitada. No sirve para gastar los 300 USD desde JMAX.
6. Los modelos gemini-2.5-* ya no existen para cuentas nuevas (404 no longer available to new users). Usa gemini-3.5-flash, gemini-flash-latest o los que devuelva «Descubrir modelos».

Pasos

1. Elegir el proyecto correcto

Entra en https://aistudio.google.com/projects. Verás tus proyectos con su Billing Tier. Elige uno en Free tier. Si el único que tienes está en «Free trial · Prepay required», crea otro o usa el que AI Studio crea por defecto («Default Gemini Project»). En el caso real se usó jmax-506114.

2. Habilitar la Gemini API en ese proyecto

Cloud Console → APIs y servicios → Biblioteca → Gemini API (generativelanguage.googleapis.com) → Enable. La ficha debe decir «Status: Enabled».

3. Crear una cuenta de servicio

IAM y administración → Cuentas de servicio → Crear. Nombre jmax-gemini; no hace falta darle roles. Queda como jmax-gemini@<proyecto>.iam.gserviceaccount.com.

4. Crear la clave

APIs y servicios → Credenciales → Crear credenciales → Clave de API:

• Nombre: JMAX-free (o el que quieras).
• Select API restrictions → marcar Gemini API → OK.
• Service account → Select a service account → elegir jmax-gemini → Select.
• Application restrictions: None.
• Create.

(El intento de añadir «Agent Platform API» a una clave, en el proyecto de prueba, terminó con la opción deshabilitada; no se conservó captura porque el panel se cerró antes.)

La clave sale una sola vez en pantalla: cópiala. Empieza por AQ. y tiene 53 caracteres.

5. Pegarla en JMAX

Proveedores → Google Gemini → API key → Guardar clave. Desde la 0.2.4, al guardar la clave JMAX pregunta al proveedor los modelos del momento y los guarda; en la 0.2.3 la lista quedaba vacía («—») y «Probar conexión» probaba el modelo ? con un 404. Después Probar conexión.

Con prepago activo en la cuenta de facturación (AI Studio → Billing → Buy credits) desaparece el techo de 20 peticiones al día y responden también los modelos pro.

Cuotas: lo que da el nivel gratuito

• 20 peticiones al día por modelo y proyecto (GenerateRequestsPerDayPerProjectPerModel-FreeTier). Un turno con herramientas gasta 2 o 3. Repartir los roles en modelos distintos multiplica el margen: rápido en gemini-3.1-flash-lite (razonamiento «low»), grande en gemini-3.5-flash-lite, respaldo en gemini-flash-lite-latest. Así se grabó el tutorial 25.
• Un proyecto enlazado a una cuenta de facturación deja de ser Free tier: pasa a «Tier 1 · Prepay» y, con saldo cero, Google contesta 429 Your prepayment credits are depleted aunque no se haya gastado nada. Pasó con jmax-506114 el 11-sep-2026. Para volver al gratuito hay que desenlazar la facturación del proyecto (Facturación → Administrar cuenta → Proyectos → Inhabilitar facturación), o comprar créditos, que además sube los límites.
• Una clave borrada por error se recupera 30 días desde Credenciales → «Restore deleted credentials».

Errores y qué significan

Mensaje	Causa	Qué hacer
401 ACCESS_TOKEN_TYPE_UNSUPPORTED	Clave AQ. de AI Studio sin cuenta de servicio válida	Crear la clave en Cloud Console enlazada a una cuenta de servicio (pasos 3 y 4)
404 This model … is no longer available to new users	Modelo gemini-2.5-* retirado	Usar gemini-3.5-flash o «Descubrir modelos»
429 Your prepayment credits are depleted	Proyecto enlazado a una cuenta de facturación sin saldo (prueba de Cloud o prepago vacío)	Comprar créditos en AI Studio → Billing, o desenlazar la facturación para volver a Free tier
429 You exceeded your current quota	Modelo fuera del nivel gratuito (los pro)	Usar un modelo flash
503 high demand	Google saturado	Reintentar en un rato; JMAX lo dice sin culparte
403 API_KEY_SERVICE_BLOCKED en aiplatform	La clave no admite Vertex	No hay vía por clave; Vertex requiere OAuth

Capturas del recorrido completo

Archivo	Qué muestra
01-api-habilitada.png	Gemini API habilitada en el proyecto de prueba (My First Project)
02-crear-clave.png	Panel «Create API key» en Cloud Console
03-gemini-api-cuenta-servicio.png	Al marcar Gemini API aparece «Service account *» obligatorio
04-clave-creada.png	Clave creada en My First Project (autentica, pero el proyecto pide prepago)
05-vertex-habilitada.png	Agent Platform (Vertex) API habilitada
09-jmax506-api-habilitada.png	Gemini API habilitada en el proyecto Free tier jmax-506114
10-jmax506-cuenta-servicio.png	Cuenta de servicio jmax-gemini
11-jmax506-crear-clave.png	Clave JMAX-free con Gemini API y cuenta enlazada, lista para crear
12-jmax-responde-telemundo47.png	JMAX responde las noticias de Telemundo 47 con 6 fuentes, en 15 s, con Gemini 3.5 Flash Lite
tomas/	Las 14 tomas de la grabación de evidencia; el tutorial 25 se monta con ellas (docs/generador/tutorial_gemini.py)

Las capturas del monitor se tomaron con docs/generador/_captura_firefox.ps1 (captura el monitor donde está Firefox, con corrección de escalado DPI).

Seguridad

• La clave nunca debe verse en pantalla ni en registros. Hasta la 0.2.3 JMAX la mandaba en la URL (?key=) y el texto del error la mostraba entera; desde el commit 4e6d252 viaja en la cabecera x-goog-api-key y los errores se explican sin repetirla.
• Si una clave apareció en una captura o en un chat, bórrala en Cloud Console (Credenciales → la clave → Delete) y crea otra.