Gemini es la familia de modelos multimodales de Google, que admite entradas de texto, imagen, audio y vídeo. Muchos desarrolladores se atascan en tres puntos la primera vez que usan la API de Gemini: dónde crear una clave, cómo funcionan las cuotas gratuitas y cómo llamar a la API de forma fiable desde China.
Este artículo de ZSQH AI Gateway explica cómo obtener y configurar una API Key de Gemini, hacer llamadas y gestionar los errores habituales.
Este artículo usa las versiones habituales a octubre de 2026. La interfaz y las cuotas de Google AI Studio pueden cambiar; consulta la consola oficial para los detalles.
1. Qué puede hacer la API de Gemini
Usos habituales:
- Resumen, traducción y reescritura de documentos largos.
- Comprensión de imágenes y vídeo y moderación de contenido.
- Preguntas y respuestas multimodales, OCR y extracción de tablas.
- Generación y explicación de código.
- Nodos de razonamiento en flujos de agentes.
Los modelos Gemini habituales se dividen en niveles Pro, Flash y otros. Pro es más capaz; Flash es más rápido y más económico. Para nombres de modelo, longitudes de contexto y precios concretos, consulta la página de precios de modelos.
2. Dos formas de obtener una API Key de Gemini
Ruta A: clave oficial de Google AI Studio
- Abre Google AI Studio.
- Inicia sesión con una cuenta de Google.
- Ve a la página de API Key y crea una clave.
- Copia la clave y guárdala en un gestor de contraseñas.
- Vincula una cuenta de facturación en el proyecto si necesitas cuotas más altas.
Una clave oficial encaja en escenarios en los que puedes acceder a Google de forma fiable, necesitas una conexión directa oficial y tu uso es moderado.
Ruta B: obtener una clave a través de ZSQH Gateway
- Abre ZSQH AI Gateway, regístrate e inicia sesión.
- Ve a la página "API Keys" y crea una clave nueva.
- Fija un límite de gasto y una fecha de caducidad.
- Recarga tu monedero.
- Copia la clave.
El gateway encaja en equipos con acceso inestable desde China, equipos que necesitan facturación unificada y equipos que usan varios proveedores de modelos a la vez.
3. Qué poner en la Base URL
API oficial de Gemini
La Base URL nativa de la API de Gemini es:
https://generativelanguage.googleapis.com
Google también ofrece un endpoint compatible con OpenAI:
https://generativelanguage.googleapis.com/v1beta/openai/
ZSQH Gateway
Cuando uses la interfaz compatible con OpenAI, configura la Base URL así:
https://ai.zhongshangqihang.com/v1
No las mezcles: usa la clave oficial con el endpoint oficial y la clave del gateway con el endpoint del gateway. Mezclarlas suele devolver 401 o 404.
4. Prueba con curl
export GEMINI_API_KEY="sk-your-key"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-flash",
"messages": [
{"role": "user", "content": "Explain what a multimodal model is in three sentences"}
]
}'
Los nombres de modelo están sujetos a lo que muestre actualmente la página de precios de modelos. Si recibes model not found, comprueba primero el nombre del modelo en lugar de sospechar de la clave.
5. Llamadas desde Python
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://ai.zhongshangqihang.com/v1",
)
response = client.chat.completions.create(
model="gemini-2.5-flash",
messages=[
{"role": "user", "content": "Summarize the key points of this text: " + "..."}
],
)
print(response.choices[0].message.content)
Si usas el SDK oficial de Google, instala google-genai según la documentación oficial y usa el endpoint oficial. No mezcles los dos enfoques.
6. Cuotas y límites de peticiones
Las cuotas de Gemini suelen calcularse por modelo, proyecto, región y ventana temporal. Los límites habituales incluyen:
- Peticiones por minuto (RPM).
- Tokens por minuto (TPM).
- Peticiones por día (RPD).
- Límites distintos para niveles gratuitos y de pago.
Las cuotas reales están sujetas a la consola oficial de Google o a la consola del gateway. Para producción, recomendamos:
- Fijar un límite de gasto en cada clave.
- Usar retroceso exponencial para las respuestas 429.
- Mantener un modelo de respaldo para cargas críticas.
- Monitorizar la tasa de error y el tiempo hasta el primer token.
7. Problemas de acceso habituales en China
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Tiempo de conexión agotado | La red no llega a Google | Usa un gateway o proxy disponible |
| 401 | Clave incorrecta o Base URL mezclada | Comprueba que la clave y el endpoint coinciden |
| 404 | /v1 sobra o falta en la ruta |
Revisa por separado el endpoint oficial y el del gateway |
| 429 | Cuota o límite de peticiones superado | Reduce la concurrencia, reintenta o amplía la cuota |
| Modelo no disponible | Región o cuenta no habilitada | Cambia de modelo o de canal |
| Salida truncada | Límite de salida o de contexto | Ajusta los parámetros o divide la entrada |
8. Cómo estimar el coste
El coste de Gemini suele depender de los tokens de entrada, los tokens de salida y las entradas multimodales como imágenes y vídeo. Pasos para estimarlo:
- Mide los tokens medios de entrada y salida por petición.
- Consulta el precio unitario del modelo actual (sujeto a precios de modelos).
- Multiplica por el volumen diario de peticiones para obtener el coste diario.
- Añade el consumo extra de reintentos, caché y entrada multimodal.
No mires solo el precio "por millón de tokens". El contexto largo y la entrada multimodal suelen ser los mayores generadores de coste.
9. Recomendaciones de seguridad
- No pongas claves en el código del front-end.
- Una clave por persona; dentro de un equipo, separa las claves por proyecto.
- Fija límites de gasto y fechas de caducidad.
- Rota las claves con regularidad.
- Usa variables de entorno o un gestor de secretos en producción.
Preguntas frecuentes
¿La API Key de Gemini es gratuita?
Suele haber un nivel gratuito, pero tiene restricciones de cuota y regionales. Para uso a largo plazo o comercial, usa el nivel de pago; consulta la política oficial para los detalles.
¿Puede una clave llamar a Claude?
A través de un gateway, una clave puede llamar a varios modelos habilitados y tú especificas el modelo en los parámetros de la petición. Una clave oficial de Gemini solo puede llamar a modelos de Google.
¿Por qué el mismo modelo a veces va lento?
Puede verse afectado por la carga upstream, las condiciones de red regionales, la longitud del contexto y la concurrencia. Para producción, añade tiempos de espera, reintentos y un canal de respaldo.
Próximos pasos
Si necesitas acceso estable desde China o un único punto de entrada para varios modelos, regístrate en ZSQH AI Gateway, crea una clave de prueba, verifícala con curl y después conecta tu aplicación. Los modelos y precios están sujetos a precios de modelos.
Lecturas relacionadas:
