La API de Gemini admite entradas multimodales de texto, imagen, audio, vídeo y otros tipos, y su precio es relativamente favorable. Pero el acceso a los servicios de Google desde China continental, los límites de cuota y los métodos de pago siguen siendo barreras habituales.
Un API relay de Gemini concentra este acceso y la facturación en una puerta de enlace. Este artículo explica cómo elegirlo, cómo conectarse y cómo probar.
Nota: Gemini y Google son marcas registradas de sus respectivos propietarios. Este artículo es solo para discusión técnica; los precios y las interfaces están sujetos al proveedor oficial o al sitio.
1. Qué es un API relay de Gemini
tu aplicación → puerta de enlace relay → Google Gemini
Sigues llamando a los modelos Gemini; solo cambias la URL base y la clave por las de la puerta de enlace. La puerta de enlace se encarga de la autenticación, la facturación, los registros y el cambio de canal.
2. Para quién es adecuado
- Equipos cuyo acceso a Google desde China continental es inestable.
- Aplicaciones que necesitan entrada multimodal, como imágenes, vídeo o audio.
- Equipos que necesitan facturación, miembros y cuotas unificados.
- Equipos que usan Gemini, Claude, GPT y DeepSeek al mismo tiempo.
- Equipos que necesitan cambiar de modelo rápidamente para pruebas A/B.
3. Criterios de selección
| Criterio | Qué confirmar |
|---|---|
| Cobertura de modelos | Si están disponibles Pro, Flash y otras versiones |
| Multimodalidad | Si se admite entrada de imagen, vídeo y audio |
| Protocolo | Si la compatibilidad con OpenAI es completa y funcionan streaming y llamada a herramientas |
| Fiabilidad | Tasa de error, P95, límites de peticiones |
| Facturación | Cómo se facturan entrada, salida y entrada multimodal |
| Cuotas | Límites por clave, miembro y proyecto |
| Cumplimiento | Conservación de datos, contratos, facturas |
La compatibilidad multimodal merece especial atención. Una puerta de enlace puede gestionar el texto a la perfección y, al mismo tiempo, admitir solo un subconjunto de formatos de imagen o vídeo, o imponer límites de tamaño más estrictos que la API oficial.
Comprueba también cómo se contabilizan los tokens de las entradas de imagen y vídeo. Una puerta de enlace que acepta un archivo pero lo factura de forma distinta a la API oficial puede cambiar tu economía unitaria, sobre todo en aplicaciones con muchos documentos o contenido multimedia.
4. Configuración
URL base:
https://ai.zhongshangqihang.com/v1
curl:
export GEMINI_API_KEY="sk-tu-clave"
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": "Responde solo OK"}]
}'
Los nombres de modelo están sujetos al precio de los modelos.
5. Cómo usar la entrada multimodal
Cada puerta de enlace admite la entrada multimodal de forma distinta. Dos enfoques habituales:
- Entrada por URL: pasa la URL de una imagen o un vídeo en el array de mensajes.
- Entrada en Base64: codifica el archivo y inclúyelo en la petición.
Antes de usarla, confirma qué campos admite la puerta de enlace y qué límites de tamaño se aplican. No copies el formato del SDK oficial sin más. Prueba primero con una imagen pequeña y después pasa a producción.
6. Lista de pruebas
- Peticiones de texto.
- Salida en streaming.
- Entrada de imagen.
- Contexto largo.
- 5 y 10 peticiones concurrentes.
- Gestión de 429/5xx.
- Conciliación de la factura.
Prueba varios tamaños de archivo, no solo una miniatura. Una puerta de enlace puede aceptar una imagen pequeña y rechazar un escaneo mayor o un vídeo corto, y esos límites se descubren mejor antes del lanzamiento que en producción.
7. Errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
| Tiempo de conexión agotado | No se puede llegar a Google | Usa una puerta de enlace accesible desde China continental |
| 401 | La clave y la URL no coinciden | Revisa la clave y la URL base |
| 404 | Ruta incorrecta | Usa solo hasta /v1 |
| 429 | Cuota o límite de peticiones | Reduce la concurrencia, reintenta o amplía la cuota |
| Error multimodal | Campo o tamaño no admitido | Consulta la documentación de la puerta de enlace y prueba con un archivo pequeño |
8. Acceso directo oficial frente a relay
| Dimensión | Acceso directo oficial | Puerta de enlace relay |
|---|---|---|
| Acceso | Afectado por las condiciones de red | Accesible desde China continental |
| Pago | Métodos oficiales | Recarga en el sitio |
| Modelos | Solo Gemini | Varios modelos |
| Facturación | Consola oficial | Consola unificada |
| Multimodalidad | Todas las capacidades oficiales | Depende del soporte de la puerta de enlace |
Si solo necesitas Gemini y el acceso oficial funciona bien, el acceso directo es una opción razonable. Si el acceso desde China continental es inestable o necesitas varios modelos, un relay encaja mejor.
Un patrón habitual es el enrutamiento híbrido: enviar las llamadas de texto sensibles a la latencia por un canal y los trabajos multimodales grandes por otro, manteniendo la misma interfaz de aplicación. La puerta de enlace debería convertir ese cambio en una modificación de configuración, no de código.
Siguientes pasos
Si necesitas acceso desde el país o un único punto de entrada para varios modelos, regístrate en ZSQH AI Gateway y prueba tanto peticiones de texto como multimodales con una clave pequeña. Los modelos y los precios están sujetos al precio de los modelos.
Lecturas relacionadas:
