- Resumen de la configuración de la API de Gemini Pro
- Cómo obtener una clave de API de Google para Gemini
- Cómo llamar al endpoint nativo de la API de Gemini
- Cómo usar Gemini con un cliente compatible con OpenAI
- Cómo elegir y gestionar los IDs de modelo de Gemini
- Cómo construir un backend intercambiable de proveedores
- Cómo encaja Gemini en un backend de agente
- Cuándo un modelo de código abierto es una mejor opción
- Errores comunes de la API de Gemini
- Conclusión
- Preguntas Frecuentes
- Artículos Recomendados
La API de Gemini Pro se accede a través de la API de Gemini con una clave creada en Google AI Studio. Para una solicitud REST directa, llama al endpoint generateContent del modelo; para una integración existente con el SDK de OpenAI, apunta el cliente a la URL base compatible con OpenAI de Google y usa un ID de modelo Gemini actual como gemini-3.1-pro-preview. El detalle importante es que “Gemini Pro” es un término de búsqueda de familia de productos, no un identificador permanente de API, por lo que las aplicaciones en producción deberían leer la lista de modelos actuales de Google antes de fijar un ID.
Resumen de la configuración de la API de Gemini Pro
Necesitas cuatro valores para hacer una solicitud:
| Configuración | Valor |
|---|---|
| Clave de API | Crea una en Google AI Studio |
| Host base nativo | https://generativelanguage.googleapis.com |
| Ruta de API nativa | /v1beta/models/{model}:generateContent |
| URL base compatible con OpenAI | https://generativelanguage.googleapis.com/v1beta/openai/ |
| ID de modelo de ejemplo | gemini-3.1-pro-preview |
El inicio rápido de la API de Gemini de Google documenta la creación de la clave de API y el patrón de solicitud nativa. Su guía de compatibilidad con OpenAI documenta la URL base de compatibilidad para aplicaciones que ya usan el SDK de Python o JavaScript de OpenAI.
Usa el SDK nativo de Gemini o la API REST cuando quieras funciones específicas de Gemini tan pronto como Google las exponga. Usa la capa de compatibilidad cuando ya tengas un cliente de estilo OpenAI y quieras reducir el trabajo de migración. La compatibilidad es útil, pero no garantiza que cada opción específica del proveedor se asigne perfectamente entre las APIs.
Cómo obtener una clave de API de Google para Gemini
Crea la clave en Google AI Studio, luego guárdala en una variable de entorno en lugar de colocarla en el código fuente:
export GEMINI_API_KEY="TU_CLAVE_API_GEMINI"
Trátala como una credencial del lado del servidor. No la confirmes en Git, la imprimas en registros ni la incorpores en JavaScript del navegador o en un paquete de aplicación móvil. Si un frontend necesita la salida de Gemini, envía la solicitud del usuario a tu propio backend y deja que el backend llame a la API de Google.
Para un servicio de producción, también decide quién posee el proyecto de Google Cloud, cómo se rotan las claves, qué entornos reciben credenciales separadas y dónde se monitorean las cuotas de solicitudes. La guía de claves de API de Google explica cómo las claves de API de Gemini están asociadas con proyectos de Google Cloud.
Cómo llamar al endpoint nativo de la API de Gemini
La ruta REST nativa coloca el ID del modelo en la URL. Este ejemplo le pide al modelo de vista previa Pro actual que devuelva una lista de verificación de migración concisa:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Crea una lista de verificación de siete pasos para migrar una API de Python de una región a dos regiones. Incluye comprobaciones de reversión."
}
]
}
]
}'
La respuesta contiene candidatos con contenido generado. Las aplicaciones reales deberían manejar una lista de candidatos vacía, contenido bloqueado, tiempos de espera y respuestas que no sean 2xx en lugar de indexar directamente en el primer objeto de respuesta.
La URL usa v1beta porque esa es la ruta que se muestra en los ejemplos actuales de la API de Gemini de Google. Mantén la versión de la API en la configuración para que puedas probar una nueva versión sin dispersar cadenas de endpoint por todo el código base.
Anatomía del endpoint nativo
La ruta tiene tres partes:
/v1beta/models/{model}:generateContent
v1betaes la versión de la API.{model}es el ID exacto del modelo de la página de modelos de Gemini de Google.generateContentes el método de generación.
Una respuesta 404 a menudo significa que el ID del modelo, la versión de la API o el método no coinciden. Antes de cambiar el código de autenticación, compara la ruta completa con la documentación actual del modelo.
Cómo usar Gemini con un cliente compatible con OpenAI
Si tu aplicación ya usa el paquete de Python de OpenAI, instálalo y cambia la clave de API, la URL base y el ID del modelo:
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[
{
"role": "system",
"content": "Eres un revisor conciso de arquitectura de software.",
},
{
"role": "user",
"content": "Revisa un diseño de trabajador de cola y enumera los cinco principales modos de fallo.",
},
],
)
print(response.choices[0].message.content)
Esta es la ruta más corta para equipos que ya tienen una abstracción de finalizaciones de chat. También facilita la reutilización de un arnés de evaluación: mantén constantes la solicitud y las comprobaciones de respuesta, luego intercambia la configuración del proveedor.
No asumas un comportamiento idéntico solo porque dos proveedores aceptan la misma llamada al SDK. Las instrucciones del sistema, los esquemas de herramientas, las entradas multimodales, el manejo de seguridad, los eventos de transmisión, la contabilidad de tokens y las cargas de error pueden diferir. Ejecuta pruebas específicas del proveedor antes de cambiar el tráfico de producción.
Cómo elegir y gestionar los IDs de modelo de Gemini
Evita colocar un nombre de marketing como gemini-pro directamente en la lógica de la aplicación. Los IDs de modelo disponibles de Google cambian a medida que se introducen, promocionan y retiran modelos de vista previa. En el momento en que se verificó esta guía, la página de modelos oficial de Google enumeraba gemini-3.1-pro-preview como un identificador de modelo de clase Pro.
Usa una capa de configuración en su lugar:
import os
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
Esa pequeña elección convierte las actualizaciones de modelo en un cambio de implementación en lugar de una reescritura de código. Para un servicio más grande, almacena estos campos juntos:
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
Antes de mover un nuevo modelo a producción:
- Confirma que el ID aparece en la documentación actual del modelo de Google o en la API de modelos.
- Comprueba si el modelo es de vista previa, estable o está programado para su retiro.
- Ejecuta tu propio conjunto de evaluación para la calidad de las respuestas y la corrección de las llamadas a herramientas.
- Mide la latencia, el uso de tokens y las tasas de fallo con solicitudes representativas.
- Agrega un modelo de respaldo o una ruta de fallo clara antes de cambiar todo el tráfico.
Los límites de velocidad no son un número único universal. Dependen del modelo y del nivel de uso, así que lee la documentación de límites de velocidad de la API de Gemini de Google y monitorea los límites aplicados a tu proyecto.
Cómo construir un backend intercambiable de proveedores
Una interfaz compatible con OpenAI puede reducir los cambios de código, pero el cambio de proveedor funciona mejor cuando tu propia aplicación define el contrato. Mantén la configuración del proveedor fuera de la lógica de negocio y normaliza la salida que realmente necesitas.
import os
from openai import OpenAI
PROVIDERS = {
"gemini": {
"api_key": os.environ["GEMINI_API_KEY"],
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
},
"novita": {
"api_key": os.environ["NOVITA_API_KEY"],
"base_url": "https://api.novita.ai/openai",
"model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
},
}
def generate(provider_name: str, prompt: str) -> str:
provider = PROVIDERS[provider_name]
client = OpenAI(
api_key=provider["api_key"],
base_url=provider["base_url"],
)
response = client.chat.completions.create(
model=provider["model"],
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content or ""
Este ejemplo expone deliberadamente las diferencias en lugar de ocultarlas. Cada proveedor mantiene su propia credencial, URL base e ID de modelo. La aplicación recibe una cadena normalizada, mientras que las pruebas específicas del proveedor pueden cubrir un comportamiento más enriquecido, como herramientas o entradas multimodales.
La documentación de la API LLM de Novita AI utiliza una forma de API compatible con OpenAI para los modelos compatibles. Esto puede ser útil cuando un equipo quiere comparar Gemini con modelos de código abierto sin reconstruir toda la capa del cliente.
Cómo encaja Gemini en un backend de agente
Un backend de agente tiene al menos dos responsabilidades separadas:
- Inferencia: El modelo decide qué decir o qué herramienta llamar.
- Ejecución: Un tiempo de ejecución controlado realiza acciones de archivo, shell, navegador o aplicación.
La API de Gemini puede manejar el lado de la inferencia. No debe tratarse como el límite de ejecución. Si un modelo propone un comando de shell, tu aplicación aún necesita validar la llamada a la herramienta, autorizarla, ejecutarla en un entorno aislado, capturar el resultado y decidir qué contexto devolver al modelo.
Novita Agent Sandbox está diseñado para flujos de trabajo de ejecución de agentes aislados. Una arquitectura práctica puede usar Gemini para el razonamiento mientras un sandbox maneja las tareas de código o navegador por separado:
Solicitud del usuario
-> Servicio de agente
-> API de Gemini para razonamiento y selección de herramientas
-> Comprobaciones de política para la acción propuesta
-> Agent Sandbox para ejecución aislada
-> Resultado de la herramienta devuelto al servicio de agente
-> API de Gemini para la respuesta final
Esta separación hace que el modelo sea reemplazable y mantiene la ejecución no confiable alejada del servidor de aplicaciones. También le da al backend un lugar para aplicar tiempos de espera, política de red, límites de archivos, registro de auditoría y autorización de usuarios.
Para una primera versión, expón solo unas pocas herramientas estrechas, define esquemas JSON para sus argumentos, rechaza campos desconocidos y coloca límites estrictos en el tiempo de ejecución y el tamaño de salida. Agrega capacidades más amplias de uso de computadora o navegador solo después de que el modelo de permisos esté claro.
Cuándo un modelo de código abierto es una mejor opción
Los modelos Gemini Pro son una opción sólida cuando tu aplicación necesita las capacidades de modelo de Google y la API administrada. Un modelo de código abierto puede ser una mejor opción cuando necesitas un segundo proveedor, deseas evaluar el comportamiento del modelo frente a una versión upstream visible, o prefieres un modelo disponible a través de un endpoint compatible con OpenAI junto con otra infraestructura.
MiMo-V2.5-Pro es una opción actual en Novita AI. La tarjeta de modelo upstream de Xiaomi lo describe como un modelo de código abierto de mezcla de expertos, mientras que Novita AI proporciona el ID de modelo alojado xiaomimimo/mimo-v2.5-pro. Debido a que tanto el endpoint de compatibilidad de Google como Novita AI se pueden llamar con un cliente de estilo OpenAI, el patrón intercambiable de proveedores de la sección anterior puede evaluarlos con las mismas solicitudes y comprobaciones de aceptación.
No elijas solo por la etiqueta. Construye un pequeño conjunto de evaluación a partir de tu carga de trabajo real: comentarios de revisión de código, preguntas de soporte, respuestas basadas en recuperación, llamadas a herramientas o documentos largos. Compara la calidad de salida, la latencia, el comportamiento de errores y el costo utilizando los paneles de control actuales del proveedor antes de tomar una decisión de enrutamiento.
Errores comunes de la API de Gemini
400: Solicitud no válida
Verifica la forma del JSON, los roles de los mensajes, las definiciones de herramientas y los nombres de los parámetros. Una opción aceptada por otro proveedor compatible con OpenAI puede no ser aceptada por la capa de compatibilidad de Google.
401 o 403: Error de autenticación o permiso
Confirma que GEMINI_API_KEY está presente en el entorno del proceso y pertenece al proyecto de Google Cloud previsto. También verifica si el proyecto y el modelo seleccionado están disponibles para la cuenta y la región.
404: Modelo o método no encontrado
Compara el ID exacto del modelo con la lista actual de modelos de Gemini. Para llamadas REST nativas, verifica la versión de la API y el sufijo :generateContent. Para llamadas compatibles con OpenAI, verifica que la URL base termine con /v1beta/openai/.
429: Límite de velocidad excedido
Reintenta con retroceso exponencial y jitter, pero no trates los reintentos como un sustituto de la planificación de capacidad. Pon en cola el trabajo por ráfagas, limita las solicitudes concurrentes e inspecciona el nivel de uso actual del proyecto y los límites específicos del modelo.
El SDK funciona, pero la salida difiere después de cambiar de proveedor
La compatibilidad cubre la interfaz de solicitud, no el comportamiento idéntico del modelo. Vuelve a ejecutar las pruebas de solicitud, salida estructurada y llamada a herramientas para cada proveedor y versión de modelo.
Conclusión
Comienza con la API nativa de Gemini cuando quieras la ruta más clara hacia las funciones específicas de Gemini. Comienza con el endpoint compatible con OpenAI cuando ya tengas un backend de estilo OpenAI o necesites una evaluación rápida de proveedores. En ambos casos, mantén la clave de API en el lado del servidor, coloca el ID del modelo en la configuración, prueba la versión exacta del modelo y separa el razonamiento del modelo de la ejecución del agente.
Para un diseño de producción resistente, mantén al menos un modelo alternativo detrás de la misma interfaz propiedad de la aplicación. Esto le da a tu equipo una forma práctica de probar una opción de código abierto en Novita AI, manejar los cambios en el ciclo de vida del modelo y enrutar la ejecución del agente a un sandbox aislado en lugar de acoplar cada responsabilidad a una sola llamada de API.
Preguntas Frecuentes
¿Existe todavía un ID de modelo llamado gemini-pro?
No asumas que gemini-pro es el ID actual. “Gemini Pro API” se usa comúnmente como una frase de búsqueda para los modelos de Gemini de mayor capacidad de Google, pero las aplicaciones deben usar un ID exacto de la página actual de modelos de Gemini. Esta guía usa gemini-3.1-pro-preview como ejemplo verificado.
¿Dónde obtengo una clave de API de Google para Gemini?
Crea una clave de API de Gemini en Google AI Studio. Guárdala en un secreto del lado del servidor como GEMINI_API_KEY, no en el código fuente ni en JavaScript del frontend.
¿Cuál es el endpoint de la API de Gemini?
El host nativo es https://generativelanguage.googleapis.com. Una solicitud de generación de contenido usa /v1beta/models/{model}:generateContent. La URL base compatible con OpenAI de Google es https://generativelanguage.googleapis.com/v1beta/openai/.
¿La API de Gemini Studio es diferente de la API de Gemini?
Google AI Studio es la interfaz web que los desarrolladores usan para experimentar y crear una clave. Las solicitudes de aplicación van a la API de Gemini. Las búsquedas de “Gemini Studio API” generalmente se refieren a este flujo de trabajo de AI Studio a API.
¿La API de Google Bard es la misma que la API de Gemini?
Gemini es la marca actual de API y modelo. Las búsquedas más antiguas de una API de Google Bard deben usar la documentación, endpoints e IDs de modelo actuales de la API de Gemini en lugar de ejemplos antiguos de Bard.
¿Puedo usar el SDK de OpenAI con Gemini?
Sí. Google documenta un endpoint de compatibilidad con OpenAI. Establece la URL base del cliente en la URL de compatibilidad de Google, proporciona tu clave de API de Gemini y selecciona un ID de modelo de Gemini compatible. Prueba las funciones específicas del proveedor antes de confiar en la paridad completa de comportamiento.
¿Puede Gemini ejecutar código para un agente de IA?
Gemini puede razonar sobre código y proponer llamadas a herramientas, pero la ejecución debe ocurrir en un tiempo de ejecución controlado. Mantén la llamada al modelo separada de un entorno aislado como Agent Sandbox, y valida cada acción solicitada antes de ejecutarla.
