Conectar la API de imágenes Gemini con un proxy
Elige el formato de API, genera una imagen y recupera la tarea si se agota el tiempo de espera.
Un proxy de API de imágenes Gemini actúa como intermediario entre tu aplicación y un modelo de imágenes Gemini. Para conectarlo necesitas un ID de modelo que genere imágenes, el formato de solicitud del servicio y una forma de obtener el archivo. Cambiar la URL base de un cliente de texto no demuestra que admita generación de imágenes.
En OmniaKey, el flujo documentado es crear una tarea → consultar su estado → descargar el recurso, empezando por POST /v1/media/tasks. Esta guía recorre el proceso y explica qué cambia frente a la API nativa de Google o una interfaz compatible con OpenAI.
Documentación comprobada el 14 de octubre de 2026. Guía de integración de OmniaKey basada en documentación pública de Google y OmniaKey. No hemos ejecutado generación de pago ni medido la velocidad o calidad de los proveedores. La presencia de un modelo en el catálogo no garantiza permisos para tu clave ni un canal disponible.
Qué tipo de proxy necesitas
Aquí hablamos de un servicio de API que gestiona solicitudes, autenticación y respuestas. Un proxy de red reenvía tráfico, pero no convierte por sí solo un formato de API de imágenes en otro. Elige según la especificación publicada por el servicio.
| Interfaz | Formato de solicitud | Dónde llega la imagen |
|---|---|---|
| Gemini GenerateContent | /v1beta/models/MODEL:generateContent, con contents y los campos admitidos de generationConfig | Partes de imagen como candidates[].content.parts[].inlineData |
| Proxy compatible con OpenAI | Endpoint y esquema de imágenes documentados por el proveedor | Datos de imagen o URL según su formato de respuesta |
| Tareas de imágenes de OmniaKey | /v1/media/tasks, con model, type, operation, input, parameters | Primero un ID; después assets[] cuando el estado sea succeeded |
La guía actual de imágenes de Google utiliza ejemplos de Interactions API. La referencia de GenerateContent define otro contrato. No mezcles sus campos ni sus analizadores de respuestas, ni supongas que un proxy ofrece ambos.
También hay que distinguir comprensión y generación de imágenes. Un modelo puede describir una foto y devolver solo texto. Una llamada de texto correcta no verifica la generación ni la edición. La etiqueta «compatible con OpenAI» tampoco demuestra que una ruta admita todos los métodos del SDK.
Elige un modelo de imágenes concreto
La documentación de Google distingue estos ID:
- Nano Banana 2.1:
gemini-nano-banana-2.1, punto de partida recomendado por Google para nuevos flujos generales de imágenes. - Nano Banana Pro:
gemini-3-pro-image, una opción independiente para tareas visuales más exigentes. - Nano Banana 2:
gemini-3.1-flash-image, la generación anterior, no un alias de 2.1.
Copia el ID del servicio que vas a utilizar. Comprueba permisos, generación o edición, tamaños y unidad de facturación. Para 2.1, OmniaKey documenta parameters.aspect_ratio y parameters.image_size, con niveles 1K, 2K y 4K. No equivalen directamente a imageConfig de Google ni a size y quality de GPT Image.
Consulta la página de Nano Banana 2.1 para ver la oferta actual y la comparación entre 2.1 y Pro para profundizar en la selección.
Genera una imagen con OmniaKey
Necesitas Bash, cURL, jq y una clave de OmniaKey guardada en la variable local OMNIAKEY_API_KEY. Ejecuta los comandos en tu servidor o equipo de desarrollo; no expongas la clave en código del navegador. El prompt de ejemplo se mantiene en inglés y es sencillo para verificar primero el flujo de API.
1. Crea y guarda la tarea
Elige un Idempotency-Key único para esta solicitud lógica. El valor del ejemplo es de demostración: cámbialo una vez para una tarea nueva y conserva tanto la clave como el cuerpo al reintentar esa misma tarea. Guarda ambos antes del envío.
curl --fail-with-body --silent --show-error \
https://api.omniakey.com/v1/media/tasks \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gemini-image-demo-20261014-001" \
-d '{
"model": "gemini-nano-banana-2.1",
"type": "image",
"operation": "generate",
"input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
"parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
}' -o task.json
Continúa solo si cURL termina correctamente y task.json contiene un id. Una tarea nueva devuelve 202 Accepted; repetir la misma clave y el mismo cuerpo recupera la tarea original con 200. Que esté aceptada no significa que la imagen esté lista. Consulta el ciclo de vida de las tareas.
2. Consulta el ID guardado
Este ejemplo de Bash limita el número de consultas. Al llegar al límite conserva el ID para continuar después: no cancela la tarea ni crea otra.
TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
curl --fail-with-body --silent --show-error \
"https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-o result.json || exit 1
STATUS="$(jq -er '.status' result.json)" || exit 1
case "$STATUS" in
succeeded) break ;;
failed|canceled) jq '.error' result.json; exit 1 ;;
queued|processing) sleep 3 ;;
*) exit 1 ;;
esac
done
Si la creación agota el tiempo de espera antes de recibir un ID, repite el mismo cuerpo y la misma clave de idempotencia. Si ya tienes ID, consulta esa tarea. Una clave nueva puede crear otra tarea facturable. La recuperación está limitada por la retención: los registros se conservan 24 horas desde la creación.
3. Descarga solo un resultado correcto
jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
"$ASSET_URL" -o generated-image
Lee mime_type para asignar la extensión correcta y comprueba que el archivo se abre y tiene las dimensiones esperadas. Las URL firmadas caducan; vuelve a consultar mientras la tarea y el recurso sigan disponibles para obtener una URL nueva. Descarga los resultados que quieras conservar: el enlace no es almacenamiento permanente.
Edita con una imagen de referencia
Usa operation: "edit" y envía Base64 integrado en input.image, o input.images para varias referencias cuando se admita. La instrucción de edición sigue en input.prompt. La documentación de imágenes muestra el formato completo.
El límite del cuerpo completo es 1 MiB, incluido Base64. Comprime o reduce la referencia si hace falta. Los límites de subida de la API directa de Google no sustituyen los del proxy. Empieza con una imagen pequeña y una modificación clara; revisa también las partes que debían mantenerse.
Cambiar el prompt, la referencia, el modelo o un parámetro constituye otra solicitud y requiere otra clave. Reutilizar la clave con un cuerpo distinto devuelve 409 idempotency_key_reused.
Localiza la capa que falla
| Síntoma | Qué comprobar | Acción |
|---|---|---|
401 / 403 | Clave, host, autenticación y permisos del modelo | Corrige credenciales o permisos antes de reintentar |
400 / 404 | Endpoint, ID, campos y propietario de la tarea | Revisa el contrato; no inventes alias |
413 | Tamaño total, incluido Base64 | Reduce la imagen de entrada |
409 idempotency_key_reused | Misma clave con otro cuerpo | Recupera con el cuerpo original o usa otra clave para una tarea nueva |
429 | Cuota, frecuencia y concurrencia | Lee el error, reduce carga y aplica espera progresiva limitada cuando proceda |
503 | Configuración o capacidad temporal | worker_disabled y no_available_channel exigen revisar configuración o disponibilidad |
| Solo texto o salida vacía | Compatibilidad, filtros de seguridad y análisis de respuesta | En GenerateContent revisa promptFeedback, finishReason y todas las partes |
| Tiempo de consulta agotado | Si la tarea sigue ejecutándose | Continúa con el mismo ID; no vuelvas a crearla por el límite local |
La guía de errores de Google describe su propio servicio. El proxy añade otra capa: registra el estado HTTP, código de error, ID y duración sin datos sensibles. No registres claves ni referencias privadas. Un JSON con 200 no demuestra que tengas una imagen utilizable.
Compara costes y valida la integración
Las tarifas directas de Google y las de un proxy son ofertas distintas. Consulta los precios actuales de OmniaKey y la unidad del modelo antes de calcular un lote. No uses precios de tokens de texto para imágenes ni supongas que una suscripción de consumo de Gemini paga las llamadas al proxy.
Una medida útil es importe total cobrado ÷ imágenes aceptadas. Incluye los reintentos cobrados y las imágenes descartadas en la revisión. Es una fórmula de planificación, no un resultado experimental ni una promesa de menor precio.
Antes de aumentar el volumen, comprueba cinco casos pequeños:
- Un prompt devuelve una imagen que se abre, con formato y dimensiones correctos.
- La edición de una referencia realiza el cambio y conserva los detalles necesarios.
- Repetir clave y cuerpo devuelve el mismo ID de tarea.
- Tras agotar la espera local puedes continuar por ID sin crear otra tarea.
- Un parámetro inválido o modelo no disponible produce un error útil, no un falso éxito.
Registra ID de modelo, parámetros, duración, estado final, cargo y resultado de la revisión. Antes de enviar material de producción, comprueba cómo trata el servicio los prompts y las referencias.
Preguntas frecuentes
¿Basta con cambiar la URL base del SDK?
Solo si el proxy documenta el endpoint, los campos y la respuesta de imagen que espera tu SDK. Prueba la operación de imagen; una llamada de chat no basta.
¿El proxy elimina los límites de Gemini?
No. Pueden aplicarse límites del proveedor, del modelo, del proxy y de la cuenta. Una pasarela no garantiza generación ilimitada ni disponibilidad regional.
¿Con qué modelo conviene empezar?
Revisa el catálogo actual y evalúa un modelo de imágenes compatible con una tarea pequeña. La guía de Nano Banana 2.1 explica sus novedades; este artículo se centra en conectar y validar la API.
Fuentes y siguiente paso
Referencias principales: generación de imágenes, GenerateContent y resolución de errores de Google, además de los documentos de OmniaKey enlazados. Las referencias de Google están en inglés. Especificaciones comprobadas el 14 de octubre de 2026; confirma el acceso al modelo antes de ejecutar el ejemplo.