Generación de imágenes con Gemini

La generación de imágenes de Gemini (apodada Banana) usa la API de OpenAI Images y devuelve imágenes en Base64 de forma síncrona; los dos grupos difieren en el endpoint de edición y en la facturación.

Modelos disponibles

Cómo elegir: solo gemini-3-pro-image ofrece 4K; gemini-3.1-flash-image cobra lo mismo en 1K y 2K; no use Lite para componer con varias referencias, porque no está optimizado para ello.

Diferencias entre los dos grupos:

Gemini oficial directo también permite llamar a los modelos de imagen mediante /v1/chat/completions, con la imagen devuelta como data URL incrustada en markdown.

Parámetros de la solicitud

Generar

POST /v1/images/generations con cuerpo JSON. Use la estructura de OpenAI Images; no envíe un payload nativo de Gemini generateContent.

Valores admitidos de aspect_ratio: 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9.

image_config tiene tres formas equivalentes. Si llega más de una, gana la primera en este orden:

• google.image_config
• extra_body.google.image_config (la forma del SDK de OpenAI)
• aspect_ratio / image_size planos en el nivel superior

Un image_size explícito por encima de los niveles del modelo devuelve 400.

Un size con WIDTHxHEIGHT nunca se rechaza por su relación: se asigna a la relación oficial más cercana, y su nivel (según el lado largo) se limita en silencio al nivel máximo del modelo, sin error.

Por ejemplo, 4096x4096 en gemini-3.1-flash-image devuelve una imagen 2K. Una abreviatura de nivel por encima de los niveles del modelo devuelve 400.

n también se limita según el nivel de salida: 4K ≤ 2, 2K ≤ 5, 1K ≤ 10 (límite de tamaño de la respuesta); si lo supera, devuelve 400.

Imágenes de referencia

Ambos grupos reciben referencias en image / images de generations, solo en JSON. Cada elemento es una URL http(s) o un Data URL; la URL debe ser accesible para el servidor y no puede apuntar a una dirección interna.

Gemini (todos los modelos, incl. imagen) comprime las referencias de más de 4 MiB antes de generar. Según el límite oficial, gemini-2.5-flash-image admite como máximo 3 referencias. Ejemplo de Data URL: data:image/png;base64,iVBORw0KGgo…, con un MIME que coincida con la imagen.

Editar (solo Gemini (todos los modelos, incl. imagen))

POST /v1/images/edits recomienda multipart/form-data y también acepta JSON (referencias como URL / Data URL). Requiere al menos una imagen de referencia.

Gemini oficial directo no tiene este endpoint y devuelve 404; para editar ahí, envíe las referencias a generations. Ningún grupo admite mask, que devuelve 400.

Asíncrono

Con la cabecera HTTP Prefer: respond-async, la solicitud devuelve de inmediato 202 Accepted y un task_id. Úsela para imágenes 2K / 4K, así las solicitudes largas no se cortan por los tiempos de espera de la CDN.

Respuesta

Las solicitudes síncronas devuelven JSON de OpenAI Images, con la imagen en data[].b64_json.

{
  "created": 1760000000,
  "model": "gemini-3-pro-image",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1120,
    "total_tokens": 1162
  }
}

Tareas asíncronas

Al enviar, la respuesta llega de inmediato:

{
  "task_id": "imgtask_EXAMPLE",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=imgtask_EXAMPLE"
}

La respuesta cuando la tarea termina:

{
  "task_id": "imgtask_EXAMPLE",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

Ejemplos

Texto a imagen

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "Tetera de cerámica en una mesa soleada, foto de producto",
    "google": {
      "image_config": { "aspect_ratio": "16:9", "image_size": "2K" }
    }
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

El ejemplo de curl necesita jq. Si data[].mime_type es image/jpeg, cambie la extensión a .jpg.

Edición con imágenes de referencia

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Pinta la taza de la imagen 1 con la paleta de la imagen 2",
    "images": [
      "https://example.com/cup.png",
      "https://example.com/palette.png"
    ],
    "size": "1024x1024"
  }'

Notas

• Solo Gemini (todos los modelos, incl. imagen) ofrece /v1/images/edits; con el otro grupo, envíe las referencias a generations.
• El resultado va en Base64 y puede ser JPEG, así que revise data[].mime_type antes de guardarlo.
• mask no se admite; describa la zona a cambiar en el prompt.
• No hay salida transparente, y background: "transparent" devuelve 400.
• stream: true no se admite; mantenga el modo síncrono predeterminado o use tareas asíncronas.
• Para imágenes 2K / 4K, añada Prefer: respond-async o dé a las solicitudes síncronas un tiempo de lectura largo en el cliente.
• Antes de una solicitud de pago, tome el ID completo de GET /v1/models con su clave y no le añada un sufijo de nivel.

Errores comunes

Los parámetros no válidos devuelven 400 antes de generar y no se cobran.

# Gemini (todos los modelos, incl. imagen)
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# Gemini oficial directo
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type

Facturación

Gemini (todos los modelos, incl. imagen) cobra por imagen entregada; Gemini oficial directo cobra por token, según el nivel realmente generado. Los parámetros no válidos y los fallos parciales no se cobran; al terminar una tarea asíncrona, usage.cost en la respuesta de consulta es el importe realmente cobrado.

Los precios están en la ficha de cada modelo y en el catálogo de modelos con la sesión iniciada.

Próximos pasos

• Resumen de generación de imágenes
• GPT Image, Seedream, imágenes de Grok Imagine, imágenes de Kling
• Referencia de API: Generar imágenes, Editar imágenes, Consultar tarea de imagen
• Si algo falla, consulte Solución de problemas