API de imágenes de Gemini: modelos, código y coste desde 0,0336 $

La API de imágenes de Gemini es la Gemini API de Google (también llamada Gemini Developer API) usada con los modelos Nano Banana, que crean y editan imágenes a partir de texto y de otras imágenes. A 5 de octubre de 2026 hay tres modelos activos: gemini-3.1-flash-lite-image (Nano Banana 2 Lite), gemini-3.1-flash-image (Nano Banana 2) y gemini-3-pro-image (Nano Banana Pro). Ninguno genera imágenes en el nivel gratuito: necesitas una clave de Google AI Studio en un proyecto con facturación y un prepago mínimo de 5 $. Cada imagen cuesta entre 0,0336 $ (1K con Lite) y 0,24 $ (4K con Pro), y la mitad si la pides por Batch, según la página de precios de la Gemini API a 4 de octubre de 2026.

Si buscabas Imagen, ya no está: los modelos Imagen 4 se cerraron en la Gemini API el 17 de agosto de 2026 y Google remite a Nano Banana para cualquier generación o edición. Y si lo que necesitas es que Gemini describa o analice una foto, con respuesta en texto, eso es comprensión de imágenes, otra parte de la documentación; aquí se trata de obtener imágenes nuevas o editadas.

Modelos de imagen en la Gemini API: tres IDs vigentes y los ya cerrados

Estos son los únicos IDs que debes poner en código nuevo. La descripción de cada uno resume la de la guía de generación de imágenes de Google:

Los IDs que aparecen en tutoriales antiguos ya fallan, según la tabla de retiradas de la Gemini API:

Para elegir, empieza con Nano Banana 2 a 1K: es el que Google sitúa como opción por defecto y sale a 0,067 $ por imagen. Baja a Lite si 1K te basta y vas a generar mucho volumen con una sola instrucción por imagen, como miniaturas o variaciones. Sube a Pro cuando el encargo exige mucho razonamiento (infografías, instrucciones largas, varios personajes o referencias de estilo, que solo admite Pro) y aceptas pagar el doble o más. La fundamentación con la Búsqueda de Google (grounding) funciona con Nano Banana 2 y Pro, no con Lite.

Clave de API y facturación: sin nivel de pago no hay imágenes

En la tabla de precios de Google, la salida de imagen figura como "No disponible" en el nivel gratuito para todos los modelos de imagen. Antes de la primera llamada necesitas lo siguiente:

1. Una cuenta mayor de 18 años en un país admitido. España está en la lista de regiones disponibles de la Gemini API y de AI Studio.
2. Una clave creada en Google AI Studio. Cada clave pertenece a un proyecto de Google Cloud, y los límites se aplican por proyecto, no por clave.
3. Facturación vinculada y un prepago de al menos 5 $. Desde el 23 de marzo de 2026 las cuentas nuevas entran en prepago. Cuando el saldo llega a 0 $, todas las claves de los proyectos vinculados a esa cuenta de facturación dejan de funcionar a la vez y las peticiones devuelven HTTP 402 hasta que recargas (facturación de la Gemini API).

Hay dos atajos que no funcionan. El crédito de prueba de 300 $ de Google Cloud no cubre la Gemini API ni AI Studio: Google lo excluye expresamente desde marzo de 2026. Y el área de pruebas de AI Studio tampoco regala imágenes: a 5 de octubre de 2026, al elegir Nano Banana 2 o Nano Banana 2 Lite sin clave de pago ni plan de Google AI, AI Studio pide "Upgrade to unlock". Lo que mandas por el nivel de pago, por otro lado, no se usa para mejorar los productos de Google, según la misma página de precios.

Guarda la clave como variable de entorno para que el SDK la lea sin escribirla en el código:

export GEMINI_API_KEY="tu_clave"
pip install -U google-genai

Generar una imagen con Python: google-genai e Interactions

La guía de imágenes de Google, actualizada el 23 de septiembre de 2026, escribe sus ejemplos con la API Interactions (client.interactions.create) del SDK google-genai. Los fragmentos de este apartado y de los siguientes reproducen la forma de la documentación de Google a 5 de octubre de 2026 y no se han ejecutado contra la API: prueba con una sola imagen antes de meterlos en un bucle.

import base64
from google import genai

client = genai.Client()  # lee GEMINI_API_KEY del entorno

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Foto de producto: taza de cerámica azul sobre una mesa de roble, luz natural de mañana",
    response_format={
        "type": "image",
        "aspect_ratio": "4:3",
        "image_size": "1K",
    },
)

imagen = interaction.output_image
if imagen:
    with open("taza.png", "wb") as f:
        f.write(base64.b64decode(imagen.data))
else:
    print("La respuesta no trae imagen:", interaction)

output_image devuelve el último bloque de imagen en base64. Al poner "type": "image" en response_format pides solo la imagen; sin ese campo, el modelo devuelve texto e imagen. Para pedir ambas cosas de forma explícita, response_format admite una lista: [{"type": "text"}, {"type": "image"}].

Para seguir retocando el mismo resultado, pasa previous_interaction_id=interaction.id en la siguiente llamada con la nueva instrucción ("cambia el fondo a blanco, no toques la taza"). Google recomienda esa conversación en varios turnos para iterar sobre una imagen.

Editar una foto: texto e imagen de referencia en la misma llamada

Para editar, mandas la instrucción y la imagen en base64 dentro de input. Por defecto la salida respeta la proporción de la imagen de entrada.

import base64
from google import genai

client = genai.Client()

with open("salon.jpg", "rb") as f:
    foto = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input=[
        {
            "type": "text",
            "text": "Usando la imagen proporcionada, cambia solo el sofá por uno de terciopelo verde. "
                    "Mantén todo lo demás exactamente igual: estilo, iluminación y encuadre.",
        },
        {"type": "image", "data": foto, "mime_type": "image/jpeg"},
    ],
)

with open("salon_editado.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

La fórmula "cambia solo X; mantén todo lo demás igual" es la que propone Google para ediciones localizadas. Describe lo que quieres ver ("una calle vacía") en lugar de lo que no quieres ("sin coches"). Google también recuerda que debes tener derechos sobre las imágenes que subes y que no puedes crear contenido que engañe, acose o haga daño; con fotos de personas, usa las tuyas o las que tengas permiso para editar.

Límite de imágenes de referencia por modelo

Los tres modelos admiten hasta 14 imágenes de referencia por petición, repartidas así según la guía de Google:

Cada referencia se factura como tokens de entrada. En Pro, una imagen de entrada son 560 tokens a 2 $ por millón, unos 0,0011 $; en la práctica, el coste lo marca la imagen que generas.

La misma petición con generateContent e imageConfig

El método clásico, generateContent, sigue documentado y te hace falta en tres casos: la Batch API solo funciona con él, los ajustes de seguridad personalizados (safetySettings) no están disponibles en Interactions, y el diagnóstico por finishReason y promptFeedback de la referencia de la API se lee en su respuesta. Aquí el tamaño y la proporción van en imageConfig:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image",
    contents="Cartel minimalista para un festival de jazz, título «Jazz en Triana» en tipografía serif",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="3:4", image_size="2K"),
    ),
)

if not response.candidates:
    print("Prompt bloqueado:", response.prompt_feedback)
else:
    candidato = response.candidates[0]
    partes = candidato.content.parts if candidato.content else []
    imagenes = [p for p in partes if p.inline_data]
    if imagenes:
        imagenes[0].as_image().save("cartel.png")
    else:
        print("Sin imagen. finish_reason:", candidato.finish_reason)

En REST, con curl, el cuerpo es el mismo y la imagen llega en base64 dentro de candidates[0].content.parts[].inlineData.data:

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Cartel minimalista para un festival de jazz, título en tipografía serif"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "3:4", "imageSize": "2K"}
    }
  }' > respuesta.json

jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' respuesta.json \
  | base64 --decode > cartel.png

Tamaños y proporciones: de 512 px a 4K, siempre con K mayúscula

Si no indicas nada, sale una imagen 1K con la proporción de la imagen de entrada o, sin entrada, cuadrada. En Interactions lo cambias con image_size y aspect_ratio dentro de response_format; en generateContent, con imageSize y aspectRatio dentro de imageConfig. El tamaño se escribe con K mayúscula (1K, 2K, 4K): Google rechaza 1k. Para 512 px, la referencia de imageConfig acepta el valor 512.

Algunas medidas exactas de la tabla de Google: en Pro, 16:9 sale a 1376x768 en 1K, 2752x1536 en 2K y 5504x3072 en 4K; 1:1 en 4K son 4096x4096, pero 9:16 en 4K son 3072x5504, así que no todas las proporciones llegan a 4096 px por lado. En Nano Banana 2, una tira 1:8 en 4K mide 1536x12288.

Un detalle que cambia la factura: en Pro, una imagen 1K y una 2K consumen los mismos 1.120 tokens de salida y cuestan lo mismo. Si usas Pro, pedir 2K no te sale más caro. En Nano Banana 2 no pasa: 2K consume 1.680 tokens frente a 1.120 en 1K.

Cuánto cuesta la API de imágenes de Gemini: de 0,0336 $ a 0,24 $ por imagen

Google cobra la imagen generada como tokens de salida de imagen, más el texto de entrada, las imágenes de referencia y, en Pro, el razonamiento. Precio por imagen a 4 de octubre de 2026:

Cada cifra sale de multiplicar los tokens de la imagen por la tarifa de salida de imagen. En Pro, 1.120 tokens × 120 $ por millón = 0,1344 $; en Nano Banana 2, 1.120 tokens × 60 $ por millón = 0,0672 $. Batch cobra la mitad a cambio de entregar en un plazo objetivo de 24 horas, aunque suele tardar mucho menos. La fundamentación con la Búsqueda de Google se cobra aparte: 5.000 búsquedas gratis al mes compartidas entre los modelos Gemini 3.x y después 14 $ por cada 1.000.

Con el prepago mínimo de 5 $, y sin contar texto, razonamiento ni referencias, salen unas 148 imágenes con Lite (5 / 0,0336), 74 con Nano Banana 2 a 1K (5 / 0,067), 37 con Pro a 1K o 2K (5 / 0,134) o 20 con Pro a 4K (5 / 0,24).

Si generas sobre todo en 4K con Pro, una pasarela de pago por llamada puede salir más barata. LaoZhang API publica gemini-3-pro-image a 0,09 $ por llamada en 1K, 2K o 4K y gemini-3.1-flash-image a 0,055 $ (precios públicos a 24 de septiembre de 2026, según su documentación). Frente a los 0,24 $ de Pro 4K estándar son 0,15 $ menos por imagen; en Pro a 1K o 2K, Batch a 0,067 $ sigue saliendo más barato. Ten en cuenta sus condiciones: una respuesta HTTP 200 sin imagen se cobra como una llamada, el tamaño y la proporción solo se eligen por la ruta nativa de Gemini (la compatible con OpenAI devuelve 1:1 a 1K), y como reenvía al modelo de Google, los filtros de seguridad son los mismos.

Aviso: laozhang.ai es un servicio propio. Sus precios son nuestra tarifa, no una comparación independiente.

Para hacer números con más detalle tienes el desglose de precios de Nano Banana 2 por resolución y el cálculo de Nano Banana Pro con Batch API y su punto de equilibrio.

Límites de uso de la API: por proyecto, con imágenes por minuto y niveles

Los límites de la Gemini API se aplican al proyecto, no a la clave: crear más claves en el mismo proyecto no te da más cuota. Según la página de límites de Google, funcionan así:

• Imágenes por minuto (IPM). Los modelos de imagen tienen este límite además de las peticiones por minuto (RPM) y por día (RPD). Las RPD se reinician a medianoche, hora del Pacífico, que en España cae por la mañana.
• Niveles de uso. Al activar la facturación pasas del nivel gratuito al Tier 1, normalmente al instante; los siguientes ascensos dependen del gasto acumulado y se aplican en menos de 10 minutos.
• Límite de gasto cada 10 minutos. Según tu historial de facturación, Google puede aplicar un tope de 10 $ en Tier 1, 50 $ en Tier 2 y 200 $ en Tier 3 por ventana móvil de 10 minutos. Con Pro a 4K, 10 $ dan para 41 imágenes (10 / 0,24 ≈ 41,7).

Las cifras concretas de RPM e IPM de cada modelo de imagen no aparecen en esa página para los IDs actuales; las ves en la sección de límites de tu proyecto en AI Studio, que refleja tu nivel real. Si necesitas volumen sin prisa, Batch tiene límites aparte y más altos.

Errores 402, 429 y respuestas sin imagen: qué revisar en cada caso

Las peticiones que fallan con error 400 o 500 no se cobran, pero cuentan para la cuota. Sobre los filtros: en los modelos Gemini actuales, los ajustes de seguridad configurables ya están desactivados por defecto, y las protecciones básicas, como las relativas a menores, no se pueden cambiar (ajustes de seguridad). De ahí se deduce que poner BLOCK_NONE no resuelve un IMAGE_SAFETY ni un OTHER. Intentar esquivar los filtros va contra la política de uso prohibido de Google y puede acabar en límites o en la suspensión del acceso. Si el OTHER te aparece con instrucciones normales, tienes una guía paso a paso sobre qué significa blockReason OTHER en Nano Banana 2 y qué revisar.

Si vienes de Imagen, del SDK antiguo o de Vertex AI

Desde Imagen. El endpoint :predict y parámetros como personGeneration eran de Imagen y desaparecieron con él. Los modelos Gemini de imagen no tienen un interruptor equivalente para generar personas: las peticiones con personas pasan por los mismos filtros y políticas que cualquier otra.

Desde el SDK antiguo. El paquete google-generativeai, con genai.configure() y genai.GenerativeModel(), ya no aparece en la documentación actual. El cambio mínimo es instalar google-genai, importar con from google import genai, crear client = genai.Client() y sustituir los IDs -preview por los vigentes. Si tenías código con generate_content, puedes mantener esa forma con client.models.generate_content, como en el ejemplo de arriba.

Desde Vertex AI. Los mismos modelos están en Google Cloud (Vertex AI) con las mismas tarifas por token en la región Global, pero con la autenticación y la facturación de Google Cloud en lugar de una clave de AI Studio. Los detalles están en Nano Banana en Vertex AI: modelos vigentes, costes y errores. Si buscas plantillas JSON más largas para Pro, consulta la API de Nano Banana Pro con plantillas JSON y YAML.

Preguntas frecuentes sobre la API de imágenes de Gemini

¿Cómo se llama la API de Gemini?

Gemini API, también llamada Gemini Developer API cuando se distingue de Vertex AI. Se usa con una clave de Google AI Studio y el SDK google-genai. La generación de imágenes no tiene una API aparte: son los modelos Nano Banana (gemini-3.1-flash-lite-image, gemini-3.1-flash-image y gemini-3-pro-image) dentro de la misma Gemini API.

¿Cómo puedo crear una imagen con la IA de Gemini sin programar?

En la app de Gemini: escribes lo que quieres o subes una foto para editarla, y genera con Nano Banana 2. Tiene límites de uso que dependen de tu plan de Google AI y no necesita clave ni prepago. La guía de cómo generar imágenes con Gemini en la app, Flow y la API explica cada vía.

¿Cuánto cuesta la API de Gemini Developer para imágenes?

Entre 0,0336 $ (Nano Banana 2 Lite a 1K) y 0,24 $ (Nano Banana Pro a 4K) por imagen en modo estándar, y la mitad con Batch, a 4 de octubre de 2026. No hay salida de imagen gratuita y el prepago mínimo es de 5 $.

¿Las imágenes de la API de Gemini llevan marca de agua?

Todas llevan SynthID, una marca invisible que no se puede desactivar. La marca visible (el destello de Gemini) es cosa de la app de Gemini, donde se gestiona en los ajustes; según el anuncio de Nano Banana Pro, Google no la añade en AI Studio.