Si tu equipo ya usa CC Switch o un plano de control estilo NewAPI, la forma más rápida de activar Gemini no es añadir otra credencial de proveedor en todas partes. Es definir una única ruta upstream, una regla de nomenclatura de modelos, una comprobación de uso y un punto de revisión de producción antes del despliegue.
Google ahora documenta el acceso a Gemini a través de las bibliotecas de OpenAI cambiando la clave API, la URL base y el nombre del modelo. Para acceso directo a Gemini, la URL base compatible con OpenAI es https://generativelanguage.googleapis.com/v1beta/openai/. Para los equipos que quieren una capa operativa única para Gemini y otros proveedores, Flatkey expone una única ruta compatible con OpenAI en https://router.flatkey.ai/v1, y el lenguaje actual de la página principal enfatiza una sola clave, una sola URL base y seguir usando tu SDK existente.
Esta guía es para aplicaciones de producción, no para demostraciones de aficionado. El objetivo es ayudarte a conectar Gemini de una manera que pueda ser revisada por ingeniería, operaciones y seguridad antes de que cambie el tráfico.
Respuesta rápida: ¿qué debería cambiar en producción?
Para un despliegue de la API de Gemini en producción, bloquea cinco cosas antes de guardar el upstream:
| Elemento | Configuración directa de Gemini | Configuración de una sola puerta de enlace para clientes CC Switch o estilo NewAPI |
|---|---|---|
| Origen de autenticación | Clave de API de Gemini de Google AI Studio o proyecto importado de Google Cloud | Una clave de la puerta de enlace administrada en un solo lugar |
| URL base | https://generativelanguage.googleapis.com/v1beta/openai/ | https://router.flatkey.ai/v1 |
| Modo de protocolo | Compatible con OpenAI | Compatible con OpenAI |
| Política de modelos | Lista aprobada de modelos Gemini | Lista aprobada de modelos Gemini más política de respaldo entre proveedores |
| Verificación | Comprobaciones de uso y facturación del lado de Google | Registro de solicitudes de la puerta de enlace, cuota, asignación de modelos y revisión aguas abajo |
Si tu aplicación ya admite upstreams compatibles con OpenAI, Gemini suele ser una tarea de enrutamiento y políticas, no una reescritura completa del SDK.
Por qué esta lista de verificación importa el viernes, 17 de julio de 2026
Tres hechos actuales hacen que una lista de verificación de producción sea más importante que un inicio rápido:
- La documentación de Gemini de Google ahora admite explícitamente el acceso mediante bibliotecas de OpenAI, lo que facilita que los equipos cambien endpoints sin reforzar la disciplina de revisión.
- Google también indica que las nuevas claves de AI Studio se crean como claves de autenticación de forma predeterminada y que las claves estándar serán rechazadas en septiembre de 2026, por lo que el tipo de clave y la propiedad del proyecto forman parte de la decisión de lanzamiento.
- El lenguaje público de configuración en vivo de Flatkey se centra en una sola clave, una sola URL base y en mantener el SDK existente, lo cual solo es útil si el equipo también estandariza el mapeo de campos, el registro y la reversión.
Antes de empezar
No abras CC Switch o NewAPI primero. Empieza con el contrato que quieres que cumpla el upstream.
Usa esta lista mínima de preflight:
| Verificación | Qué confirmar | Por qué importa |
|---|---|---|
| Responsable | El equipo sabe quién es responsable de la creación, rotación y cuota de la clave de Gemini | Evita desvíos por cuentas compartidas |
| Tipo de ruta | Está utilizando un upstream compatible con OpenAI, no un adaptador personalizado mixto | Mantiene simple el mapeo de campos |
| Lista de modelos | Tiene una lista aprobada de IDs de modelos de Gemini para esta app | Evita desvíos silenciosos de alias |
| Registro | Sabe dónde se realizarán la revisión de logs de solicitudes, uso y facturación | Necesario para la evidencia del corte |
| Reversión | Puede cambiar rápidamente la política de upstream o de modelo | Requerido para un despliegue por fases |
Si no tiene estas respuestas, no está listo para tratar la configuración como lista para producción.
Asignación de campos para upstreams de estilo CC Switch o NewAPI
Distintos clientes etiquetan los campos de forma diferente, pero la asignación para producción debe mantenerse coherente.
| Campo upstream | Valor para este despliegue | Nota de revisión |
|---|---|---|
| Tipo de proveedor | OpenAI-compatible | Utilice el modo genérico compatible con OpenAI, a menos que el cliente tenga un modo Gemini nativo validado que pretenda usar |
| Clave de API | Clave Flatkey o clave upstream aprobada | Manténgala en una única fuente secreta, no en copias locales por usuario |
| URL base | https://router.flatkey.ai/v1 | Utilice una sola ruta para el control centralizado |
| Origen del modelo | Allowlist manual o recuperación después de guardar la ruta | Revise los IDs de modelo devueltos antes de exponerlos a la app |
| Modelo predeterminado | Modelo de producción de Gemini aprobado | No apunte producción a un modelo de vista previa por accidente |
| Modelo de respaldo | Opcional y deliberado | Actívelo solo después de que pasen la nomenclatura del modelo y las comprobaciones de logs |
| Encabezados | Autenticación estándar Bearer, a menos que su cliente documente campos adicionales | Evite trucos puntuales con encabezados que rompan la portabilidad |
| Revisión de uso | Log de solicitudes más panel de cuota o facturación | Debe formar parte de la aprobación final |
Esta es la diferencia operativa clave entre una configuración directa de Gemini y una configuración con gateway: la ruta con gateway reduce la dispersión de credenciales, pero aumenta la necesidad de una puerta de revisión clara porque más apps pueden heredar el mismo upstream.
Paso 1: decida si esta app necesita Gemini directo o un único gateway
Use Gemini directo si la app está aislada, el responsable está claro y no necesita en este momento enrutamiento entre proveedores.
Use un único gateway si se cumple cualquiera de estas condiciones:
- El mismo cliente ya interactúa con varios proveedores.
- Más de un ingeniero o equipo gestionará la integración.
- Quiere un único lugar para verificar el uso, las cuotas o los logs de solicitudes.
- Prevé sustitución de modelos, fallback o ampliación de proveedores más adelante.
Para los equipos de CC Switch y de estilo NewAPI, la segunda ruta suele ser más fácil de mantener con el tiempo porque el cliente conserva una única forma compatible con OpenAI mientras la política de enrutamiento permanece en upstream.
Paso 2: fija los IDs exactos de los modelos Gemini que permitirás
No uses "Gemini" como un requisito vago. Aprueba IDs exactos de modelos para esta aplicación y este entorno.
Ese análisis debería responder:
- ¿Qué modelo de Gemini es el predeterminado en producción?
- ¿Qué modelos están permitidos solo para pruebas?
- ¿Se permiten modelos de vista previa en producción en absoluto?
- ¿La aplicación mostrará un selector de modelo o un único modelo fijo?
- Si se habilita el fallback, ¿qué modelos que no son Gemini están permitidos y bajo qué condición?
Aquí es donde muchos equipos crean incidentes evitables. Guardan correctamente el upstream y luego dejan la nomenclatura de modelos lo bastante flexible como para que las pruebas y producción se comporten de forma diferente.
Si necesitas ayuda para alinear los nombres de los modelos después de que la ruta esté activa, revisa la guía existente Migración de API compatible con OpenAI antes de exponer la integración a los usuarios.
Paso 3: guarda un único upstream y ejecuta una prueba rápida antes de obtener los modelos
Después de introducir la clave de API y la URL base, haz una prueba rápida antes de importar o exponer la lista completa de modelos.
Tu prueba rápida debería confirmar:
| Prueba | Resultado esperado |
|---|---|
| Autenticación | El upstream acepta la clave sin errores locales de credenciales |
| Ruta | Una solicitud simple de finalización de chat se devuelve desde la URL base configurada |
| Modelo | El ID exacto del modelo Gemini se resuelve correctamente |
| Registro | Puedes encontrar la solicitud en la superficie de revisión que elegiste |
| Facturación o cuota | La solicitud es visible donde el equipo espera evidencias de uso |
Para los equipos que estandarizan en una sola pasarela, esto importa más que obtener la lista de modelos. Obtener una lista de modelos demuestra que el cliente puede ver nombres. No demuestra que la ruta de solicitud en producción sea revisable.
Paso 4: revisa el tipo de clave y la propiedad del proyecto
Este paso es fácil de omitir porque la solicitud puede funcionar ya.
La guía actual de Google sobre claves es la razón para no omitirlo. Google AI Studio ahora crea claves de autenticación de forma predeterminada, las claves estándar sin restricciones ya están más fuertemente restringidas, y Google indica que la API de Gemini rechazará las claves estándar en septiembre de 2026. Eso significa que los equipos de producción deberían tratar el tipo de clave como parte de la preparación para el despliegue, no como una tarea de limpieza posterior.
Usa esta breve revisión:
| Pregunta | Respuesta aceptable |
|---|---|
| ¿Quién es el propietario del proyecto Gemini? | Propietario o equipo identificado |
| ¿Qué tipo de clave está en uso? | Se prefiere la clave de autenticación para nuevas configuraciones de producción |
| ¿Dónde se almacena la clave? | Gestor de secretos central o secreto controlado de la plataforma |
| ¿Cómo se rotará? | Propietario y proceso documentados |
| ¿Qué sucede si el uso aumenta de forma repentina? | Existe una alerta de facturación o una ruta de revisión de cuota |
Si centraliza a través de una sola pasarela, haga la misma revisión para la clave de la pasarela y la cuenta del proveedor downstream.
Paso 5: decida si la aplicación debe exponer Gemini directamente a los usuarios
No dé por sentado que la respuesta es sí.
En muchas aplicaciones de producción, el mejor patrón es:
- Enrutar Gemini upstream primero.
- Validar los logs, la latencia y la revisión del uso.
- Mantener el modelo detrás de una bandera de función o una lista de अनुमति interna.
- Exponerlo a los usuarios finales solo después de que pase el control de revisión.
Esto es especialmente útil en entornos de estilo CC Switch y NewAPI, donde un solo cambio de configuración puede afectar a varios operadores o rutas de la aplicación.
Paso 6: añada un control de revisión para producción
Esta es la parte que la mayoría de las guías de configuración omiten. Antes de mover el tráfico, exija un breve control de revisión que alguien pueda aprobar de una sola vez.
Use esta lista de verificación exacta:
| Elemento del control de revisión | Condición para aprobar |
|---|---|
| Asignación de campos | La fuente de la clave de API, la URL base, el modo del proveedor y el modelo predeterminado están documentados |
| Evidencia de prueba rápida | Se registra una solicitud exitosa con la ruta final |
| Lista de अनुमति de modelos | Solo los IDs de modelos Gemini aprobados están disponibles para la aplicación |
| Visibilidad del uso | Se confirma la ruta de revisión del registro de solicitudes o de facturación |
| Propiedad del secreto | Se nombran el propietario de la clave y la ruta de rotación |
| Rollback | Se puede restaurar rápidamente la política anterior de upstream o del modelo |
| Alcance | El equipo sabe si este cambio afecta a una aplicación, a un espacio de trabajo o a muchos clientes |
Este es el documento de configuración más breve que aun así protege el despliegue.
Paso 7: decida cómo debe funcionar el fallback antes de habilitarlo
Si está usando una sola pasarela, la tentación es activar el fallback de inmediato. No lo haga a menos que pueda responder dos preguntas:
- ¿Qué condición de fallo debe activar el fallback?
- ¿Es aceptable el comportamiento del modelo de fallback para la misma tarea orientada al usuario?
Para los despliegues de producción de Gemini, el fallback suele ser más seguro después del primer cambio, no durante él. Primero pruebe la ruta principal y luego añada el fallback con su propia evidencia de prueba.
Paso 8: valide la ruta desde la aplicación, no solo desde un script local
Una prueba local con curl es necesaria. No es suficiente.
Ejecute una validación desde la ruta real de la aplicación y confirme:
- La aplicación usa el upstream previsto.
- El modelo devuelto es el modelo Gemini esperado.
- La observabilidad muestra la misma solicitud.
- Cualquier comportamiento de tiempo de espera, reintento o cuota a nivel de la aplicación sigue funcionando.
Aquí es donde aparecen los problemas de producción cuando la aplicación tiene variables de entorno antiguas, nombres de modelo almacenados en caché o una fuente de secretos diferente a la del ingeniero que ejecutó la primera prueba.
Despliegue recomendado para equipos de estilo CC Switch y NewAPI
Use un despliegue por fases que mantenga simple el plano de control:
- Añada un upstream compatible con OpenAI y apto para Gemini.
- Pruebe un modelo de Gemini aprobado.
- Confirme la revisión de logs y uso.
- Exponga el modelo solo a usuarios internos.
- Añada fallback solo después de que la ruta principal sea estable.
- Amplíe a más aplicaciones solo después de que la primera aplicación pase el punto de control de revisión.
El mensaje de enrutamiento en vivo de Flatkey es útil aquí porque la misma URL base puede mantenerse mientras su política de modelos se vuelve más estricta con el tiempo. Si está comparando el costo o el impacto de adquisiciones antes del despliegue, la página de precios en vivo es la siguiente comprobación adecuada.
Documento breve de configuración que puede aprobar internamente
Si quiere un traspaso que pueda revisarse, copie esta estructura en su nota de configuración interna:
| Field | Value |
|---|---|
| App name | |
| Upstream owner | |
| Provider mode | OpenAI-compatible |
| Base URL | https://router.flatkey.ai/v1 |
| API key source | |
| Approved Gemini model IDs | |
| Fallback enabled | Yes or No |
| Usage review surface | |
| Billing or quota review surface | |
| Rollback action | |
| Reviewer | |
| Approval date |
Esa es suficiente estructura para aprobar un despliegue de Gemini sin convertir la configuración en un largo memorando de arquitectura.
Si su equipo también usa Claude Code en el mismo plano de control, el artículo en vivo CC Switch Claude Code setup with Flatkey and NewAPI es un compañero útil porque muestra el mismo patrón operativo desde el lado del cliente.
FAQ
¿Cuál es el patrón de URL base más seguro para un despliegue de Gemini en producción en un cliente compatible con OpenAI?
El patrón más seguro es una URL base revisada por entorno. Para acceso directo a Gemini, Google documenta https://generativelanguage.googleapis.com/v1beta/openai/. Para un despliegue mediante una pasarela centralizada, use una única ruta de gateway aprobada y mantenga ese valor bajo control de configuración.
¿Debería usar una credencial de Gemini separada para cada cliente de CC Switch o NewAPI?
Normalmente no. Para equipos de producción, una única fuente de secreto controlada es más segura que credenciales locales dispersas. La desventaja es que debe añadir un punto de control de revisión porque más clientes pueden heredar la misma ruta.
¿Necesito reemplazar mi SDK para usar Gemini en una aplicación compatible con OpenAI?
Normalmente no. La documentación actual de Gemini de Google admite explícitamente las bibliotecas de OpenAI cambiando la clave, la URL base y el nombre del modelo. El trabajo real es validar la política de la ruta, el nombre del modelo, el registro y la propiedad.
¿Qué cambió sobre las claves API de Gemini en 2026?
A partir del viernes 17 de julio de 2026, Google AI Studio crea nuevas claves como claves de autenticación de forma predeterminada, advierte que las claves estándar sin restricciones no son aceptables para un uso a largo plazo y afirma que la API de Gemini rechazará las claves estándar en septiembre de 2026. Los equipos deben revisar el tipo de clave antes del cambio a producción.
¿Cuándo debería activar el fallback para Gemini?
Después de que la ruta principal de Gemini sea estable. Primero verifique un modelo de Gemini aprobado a través de la ruta final de la aplicación. Luego agregue fallback solo si la condición de activación y el comportamiento del modelo de respaldo son aceptables para el mismo flujo de trabajo.
¿Qué debo inspeccionar antes de aprobar el documento de configuración?
Inspeccione la URL base exacta, el origen de la clave, los IDs de modelo de Gemini aprobados, un registro de solicitud exitosa, la superficie de revisión de uso y la acción de reversión. Si falta alguno de esos elementos, la configuración no está lista para la aprobación en producción.
