La ruta más corta para integrar la API de Gemini es esta: abrir AI Studio con una cuenta de Google, crear una clave de API, instalar el SDK y enviar la primera solicitud generateContent. Con suerte, todo el proceso lleva menos de veinte minutos. Los verdaderos obstáculos no están en «si la llamada funciona», sino en elegir la entrada equivocada, escribir mal el ID del modelo, confundir la cuota gratuita con el plan de pago y guardar la clave donde no corresponde.

Este artículo sigue el orden real de integración: primero distingue AI Studio de Vertex AI, después crea la clave, instala el SDK y envía solicitudes con curl y Python; luego trata el nombre del modelo, las instrucciones del sistema, el streaming y la configuración de seguridad; por último enumera las causas habituales de los errores 400, 403 y 429 y una lista de seguridad para las claves.

Nota: Google y Gemini son marcas de Google LLC. Los nombres de modelos, las cuotas gratuitas y las reglas de facturación pueden cambiar. Este artículo toma como ejemplo el flujo habitual a octubre de 2026; para los detalles, consulta la documentación oficial de Google y la página de precios de modelos.

1. Distinguir AI Studio de Vertex AI

La API de Gemini tiene dos entradas habituales, con sistemas de cuenta y gestión distintos; elegir mal obliga a rehacer permisos o facturación.

Aspecto Google AI Studio Vertex AI
Entrada Consola web para pruebas rápidas de desarrolladores Consola de Google Cloud para uso por proyectos
Requisitos de cuenta Basta una cuenta de Google para empezar Proyecto de Cloud, cuenta de facturación y permisos IAM
Credenciales Clave de API generada en AI Studio Cuenta de servicio o clave controlada, con IAM
Facturación Conviven plan gratuito y plan de pago Facturación por proyecto de Cloud
Región y datos Según los términos de AI Studio Región seleccionable, sujeta a los términos de Cloud y a la configuración del proyecto
Escenario adecuado Prototipos, aprendizaje y validación a pequeña escala Sistemas en producción y equipos con requisitos de auditoría y permisos

Las personas desarrolladoras y los equipos pequeños suelen empezar con AI Studio para validar el flujo; cuando hay contratos, requisitos de región de datos o auditoría unificada, conviene evaluar Vertex AI. No mezcles claves, cuotas ni facturas de ambos lados, y tampoco uses una clave de AI Studio para llamar a las interfaces de Vertex AI.

2. Crear la primera clave de API

  1. Inicia sesión en Google AI Studio con una cuenta de Google.
  2. Entra en la página de gestión de claves de API y elige crear una clave.
  3. Selecciona un proyecto de Google Cloud; si no tienes uno, créalo siguiendo las indicaciones de la página.
  4. Copia la clave generada y guárdala de inmediato en una variable de entorno del servidor o en un gestor de contraseñas.
  5. Envía un mensaje de prueba desde el Playground para confirmar que la clave y el modelo funcionan.
  6. Dale a la clave un nombre que permita reconocer su uso, para facilitar la rotación y la revocación.

AI Studio ofrece un plan gratuito de prueba; los modelos disponibles, la velocidad de solicitudes y la cuota varían según la cuenta y el momento. Al activar la facturación en el proyecto de Cloud asociado se accede al plan de pago. No tomes las cifras de cuota de artículos antiguos como un compromiso actual: lo que muestre la consola y la documentación oficial es lo que vale.

Después de crear la clave, confirma a qué proyecto de Cloud pertenece. La cuota suele calcularse por proyecto, y mezclar pruebas y producción puede hacer que otras personas agoten la cuota. Si necesitas más capacidad, activa la facturación en el proyecto de Cloud, configura alertas de presupuesto y observa el uso real durante una semana.

3. Instalar el SDK y enviar la primera solicitud

Para Python se recomienda la versión 3.10 o superior, con el SDK oficial instalado en un entorno virtual.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="tu clave"

Primero usa curl para descartar factores del SDK. El ID del modelo se sustituye por un marcador; el nombre real se obtiene de la lista de modelos o de la página de precios.

curl "https://generativelanguage.googleapis.com/v1beta/models/<ID_DEL_MODELO>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explica en una frase qué es una pasarela de API"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

Cuando curl devuelva 200, pasa al SDK de Python:

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<ID_DEL_MODELO>",
    contents="Explica en una frase qué es una pasarela de API",
)
print(resp.text)

model debe llevar el ID completo del modelo, no solo el nombre de la familia. Cada modelo admite tipos de entrada y parámetros distintos; si te equivocas, lo verás en un 400 o un 404.

4. Nombres de modelo, instrucciones del sistema y parámetros de generación

Los ID de los modelos de Gemini suelen combinar familia y versión. Lo más seguro es consultar primero la lista de modelos disponibles para la cuenta actual:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

No adivines modelos que no aparezcan en la lista. Al elegir, reparte por tarea: usa el nivel de baja latencia para tareas ligeras y el nivel superior para razonamiento complejo y documentos largos; los niveles y precios concretos se rigen por la página de precios de modelos.

Los ID cambian con las versiones, y uno antiguo puede quedar marcado como obsoleto o retirarse. Guarda el nombre del modelo en un archivo de configuración en lugar de repartirlo por el código: al actualizar solo cambias un sitio y confirmas con muestras de regresión que la salida no cambió de forma evidente.

Las instrucciones del sistema fijan el rol y las reglas de salida, y son útiles en traducción, extracción y atención al cliente:

resp = client.models.generate_content(
    model="<ID_DEL_MODELO>",
    contents="Traduce esta frase al inglés: integración completada",
    config={"system_instruction": "Eres traductor de documentación técnica; entrega solo la traducción."},
)

Los parámetros de generación habituales son temperature, maxOutputTokens y topP. Si necesitas resultados estructurados, puedes pedir al modelo que devuelva JSON y analizarlo y validarlo en el código; no supongas que siempre respetará el formato, y prepara de antemano los reintentos y la lógica de respaldo.

5. Streaming y configuración de seguridad

El streaming es útil para interfaces de chat y respuestas largas. En la interfaz REST se añade :streamGenerateContent al método y se incluye alt=sse; en el SDK de Python se usa generate_content_stream:

for chunk in client.models.generate_content_stream(
    model="<ID_DEL_MODELO>",
    contents="Explica en tres puntos qué es un límite de velocidad",
):
    print(chunk.text, end="")

La configuración de seguridad permite ajustar el umbral de bloqueo por categorías; las habituales son acoso, odio, contenido sexual y contenido peligroso. Los umbrales predeterminados sirven para la mayoría de los negocios; bajarlos amplía el rango de contenido y exige evaluarlo junto con la política del producto y la normativa local. No desactives toda la seguridad solo para «pasar las pruebas», sobre todo en productos dirigidos al público.

6. Cómo diagnosticar 400, 403 y 429

Código Causa habitual Dirección de la solución
400 JSON mal formado, parámetro no admitido, ID de modelo incompatible con la interfaz Revisa el cuerpo campo por campo y empieza por la solicitud mínima
403 Clave inválida o restringida, API no habilitada, restricción de proyecto o región Prueba otra clave y revisa permisos del proyecto y estado de la cuenta
404 ID de modelo mal escrito, versión o ruta incorrecta Consulta la lista de modelos y confirma v1beta y el nombre del método
429 Cuota gratuita agotada, demasiadas solicitudes por minuto o concurrencia alta Reintenta con retroceso exponencial, baja la concurrencia y evalúa el plan de pago
500/503 Fallo temporal del servidor Reintenta un número limitado de veces; si persiste, degrada o cambia de canal

No reenvíes de inmediato tras un 429. Lo correcto es aplicar retroceso con fluctuación aleatoria, fijar un número máximo de reintentos y registrar las solicitudes fallidas en el log. Los límites del plan gratuito suelen ser más estrictos; las pruebas de carga y los lotes deben planificarse aparte.

7. Lista de seguridad para las claves

  • Guarda la clave solo en variables de entorno del servidor o en un gestor de secretos; nunca en el frontend, el repositorio o el historial de chat.
  • Usa una clave distinta para producción, pruebas y desarrollo, con cuotas y permisos aislados por entorno.
  • Rota con regularidad y revoca de inmediato cuando alguien deje el equipo o termine el proyecto.
  • Limita en la consola de Cloud las API que puede llamar la clave, para reducir el impacto de una filtración.
  • Activa alertas de uso; ante llamadas anómalas, desactiva primero la clave y luego investiga.
  • No muestres la clave completa en capturas de pantalla, grabaciones o tickets.

8. Acceder a Gemini mediante una entrada compatible con OpenAI

Si el equipo ya tiene el SDK de OpenAI y todo el código de llamadas, puede usar la entrada compatible con OpenAI de ZSQH AI Gateway, cuya Base URL es https://ai.zhongshangqihang.com/v1. Solo hay que cambiar base_url, api_key y model:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<nombre del modelo Gemini en la página de precios>",
    messages=[{"role": "user", "content": "Responde solo OK"}],
)
print(resp.choices[0].message.content)

Este enfoque encaja en equipos que necesitan una factura unificada para varios modelos, liquidación en RMB y una ruta de red estable en su región. Los parámetros nativos de Gemini y los campos multimodales no tienen compatibilidad completa; antes de migrar, valida cada elemento con solicitudes reales. El registro está aquí y los modelos y precios se rigen por la página de precios de modelos.

Preguntas frecuentes

¿La API de Gemini tiene cuota gratuita?

AI Studio ofrece un plan gratuito, pero los modelos disponibles, la velocidad y la cuota cambian, y los términos de datos pueden diferir del plan de pago. Puedes usar el plan gratuito para validar prototipos; para un negocio en producción conviene reevaluar la cuota y el costo con el plan de pago.

¿Qué hacer si se filtra una clave de API?

Primero revoca o rota la clave en la consola; después revisa los logs de uso para delimitar las llamadas anómalas y, por último, investiga el canal de la filtración. Borrar la clave del código no basta: una credencial expuesta debe considerarse inválida.

¿Se puede llamar directamente a la API de Gemini desde cualquier red?

La calidad de la conexión varía según la región y el operador, y pueden aparecer tiempos de espera o fallos de conexión. Una práctica habitual es ejecutar las solicitudes en un servidor con acceso estable o usar una pasarela con interfaz compatible con OpenAI; las limitaciones concretas dependen de la red real y de la documentación oficial.

¿Por qué curl funciona y el SDK de Python devuelve error?

Revisa primero si el SDK y las dependencias están actualizados; después confirma que la forma de escribir model, la configuración del proxy y las variables de entorno coinciden. Si el SDK devuelve 404, céntrate en el ID del modelo y la ruta de la interfaz, y no cambies varias variables a la vez.

¿Se puede llamar a la API de Gemini directamente con el SDK de OpenAI?

Google ofrece una entrada compatible con OpenAI y las pasarelas locales también suelen proporcionar una capa de compatibilidad, pero el rango de parámetros admitidos varía. El multimodal, la llamada a herramientas y la salida estructurada deben validarse con solicitudes reales; no supongas equivalencia completa.

Siguiente paso

Sigue el flujo de este artículo para hacer funcionar la solicitud mínima y después integra logs de negocio, reintentos y monitoreo de uso. Si quieres gestionar en un solo panel el consumo de Gemini y otros modelos, la facturación en RMB y los permisos de las claves, puedes registrarte en ZSQH AI Gateway; los precios están en precios de modelos.

Lecturas relacionadas: