Guía Completa de la API de Imágenes de Gemini 2026: Modelos, Precios, Ejemplos de Código y Soluciones Relay

La API de Imágenes de Gemini ofrece a los desarrolladores acceso a cinco modelos de generación de imágenes en 2026: Nano Banana (gemini-2.5-flash-image, desde $0.039/imagen), Nano Banana 2 (gemini-3.1-flash-image-preview, lanzado el 26 de febrero de 2026, desde $0.045/imagen a resolución 1K), Nano Banana Pro (gemini-3-pro-image-preview, $0.134/imagen) e Imagen 4 en tres niveles que van de $0.02 a $0.06 por imagen. Google AI Studio proporciona un nivel gratuito de aproximadamente 500 solicitudes por día para uso personal. Para desarrolladores en regiones donde la API de Google está restringida, o aquellos que buscan costos más bajos, las soluciones relay como laozhang.ai ofrecen compatibilidad API idéntica a precios reducidos. Esta guía cubre todo lo que necesitas para integrar la generación de imágenes de Gemini en tu aplicación en 2026: selección de modelos, configuración paso a paso, código funcional en tres lenguajes, precios completos y opciones relay.

Resumen rápido — Inicio Rápido con la API de Imágenes de Gemini (2026)

Si necesitas lanzar rápidamente y solo quieres la información esencial, aquí tienes el panorama completo en un solo lugar. La API de Imágenes de Gemini tiene dos familias distintas: los modelos nativos de Gemini (serie Nano Banana) que se integran perfectamente con el SDK de Gemini existente, y la serie Imagen 4 que apunta a una salida de nivel profesional pero carece de un nivel gratuito.

Referencia rápida de precios por modelo (marzo 2026)

La integración mínima viable de tres líneas usando Nano Banana 2 (el modelo más reciente a marzo de 2026):

python
import google.generativeai as genai
genai.configure(api_key="TU_CLAVE_API")
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")
response = model.generate_content("Un horizonte de ciudad futurista al anochecer")
image_data = response.candidates[0].content.parts[0].inline_data.data
with open("output.png", "wb") as f:
    import base64; f.write(base64.b64decode(image_data))

La decisión más importante que debes tomar antes de escribir cualquier código es qué modelo se adapta a tu caso de uso. Si tienes presupuesto de nivel gratuito y quieres las capacidades más recientes, Nano Banana 2 es la opción predeterminada correcta. Si necesitas el menor costo posible por imagen en producción, Imagen 4 Fast a $0.02/imagen no tiene competencia. Si estás en una región donde el acceso a la API de Google está restringido, una API relay resuelve el problema de acceso sin ningún cambio de código más allá de la URL base.

¿Qué Modelo de Imágenes de Gemini Deberías Usar? (Guía de Decisión)

Elegir el modelo incorrecto es uno de los errores más comunes y costosos que cometen los desarrolladores al integrar la API de Imágenes de Gemini. Los cinco modelos difieren no solo en precio sino en el techo de calidad, las resoluciones disponibles, la elegibilidad para descuentos por lotes y la disponibilidad del nivel gratuito. Comprender estas diferencias desde el principio te ahorra sorpresas costosas en producción y evita que desperdicies cuota gratuita durante el desarrollo.

Nano Banana (gemini-2.5-flash-image) es el caballo de batalla establecido. Lanzado a principios de 2025, tiene el comportamiento más estable y el historial más largo en entornos de producción. A $0.039 por imagen en estándar, y $0.0195 por imagen a través de la API Batch, es la opción más rentable cuando puedes tolerar una ventana de procesamiento de 24 horas. El nivel gratuito lo hace ideal para prototipos, y su calidad de salida es competitiva para la mayoría de los casos de uso comerciales — maquetas de productos, contenido para redes sociales, ilustraciones de blogs y materiales de marketing. Elige Nano Banana cuando necesites fiabilidad comprobada, el menor costo por lote del ecosistema, o cuando tu caso de uso no requiera la mayor resolución posible.

Nano Banana 2 (gemini-3.1-flash-image-preview) es la entrada más reciente, lanzada el 26 de febrero de 2026. Este modelo introdujo la salida de resolución 4K en la línea de generación de imágenes nativa de Gemini, lo que importa para la producción impresa y contextos de visualización de alta fidelidad. El precio escala drásticamente con la resolución: $0.045/imagen a 1K, $0.067/imagen a resolución 1K (estándar) y $0.151/imagen a 4K. A menos que necesites específicamente salida en 4K, el nivel 1K ofrece mejor valor que Nano Banana Pro mientras proporciona un entrenamiento de modelo más reciente. El nivel gratuito se aplica a resolución 1K. Para un análisis técnico detallado de las capacidades de este modelo, consulta el análisis profundo de Nano Banana 2 (gemini-3.1-flash-image-preview).

Nano Banana Pro (gemini-3-pro-image-preview) apunta al mayor techo de calidad de la familia nativa de Gemini. A $0.134/imagen para resoluciones 1K y 2K, es sustancialmente más caro que Nano Banana y Nano Banana 2 en resoluciones equivalentes. El caso de uso es limitado pero real: agencias creativas que producen imágenes principales, fotografía de comercio electrónico premium, o cualquier contexto donde la brecha de calidad visual entre "bueno" y "excepcional" tiene impacto directo en el negocio. No hay nivel gratuito para Nano Banana Pro ni descuento por lotes. Para un análisis detallado de costos, consulta los detalles de precios de Nano Banana Pro.

Imagen 4 Fast (imagen-4.0-fast-generate-001) ocupa una posición única: el modelo más barato por imagen en todo el ecosistema a $0.02, pero sin nivel gratuito en absoluto. Esto significa que cuesta dinero desde la primera llamada a la API, lo que lo hace inadecuado para la experimentación en desarrollo pero extremadamente atractivo para cargas de trabajo de producción de alto volumen donde ya has validado tu integración. Imagen 4 Fast utiliza la infraestructura de generación de imágenes dedicada de Google en lugar de la arquitectura multimodal de Gemini, lo que le da un perfil de calidad diferente — optimizado para salida fotorrealista con inferencia más rápida.

Imagen 4 Standard e Ultra completan la familia Imagen 4 a $0.04 y $0.06 por imagen respectivamente. Estos modelos ofrecen calidad progresivamente mayor para aplicaciones profesionales exigentes. Imagen 4 Ultra en particular compite con Midjourney y DALL-E 3 en métricas de calidad para salidas fotorrealistas y artísticas.

Para contexto comparativo entre familias de modelos, consulta la comparación detallada de modelos de imágenes de Gemini y la comparación entre Gemini vs GPT-4o Image vs FLUX.

Marco de decisión en términos simples: Comienza con Nano Banana o Nano Banana 2 en el nivel gratuito durante el desarrollo. Migra a Imagen 4 Fast para producción si la calidad cumple los requisitos y quieres el menor costo por imagen. Usa Nano Banana Pro o Imagen 4 Standard/Ultra cuando la calidad de salida sea un factor diferenciador para tu producto.

Configuración de la API de Imágenes de Gemini: Paso a Paso

Pasar de cero a una integración de API funcional toma unos quince minutos si sigues estos pasos con precisión. Los errores de configuración más comunes provienen de confundir la clave de Google AI Studio (que funciona para todos los modelos de Gemini, incluida la generación de imágenes) con otras credenciales de Google Cloud, y de instalar la versión incorrecta del SDK.

Paso 1: Obtén tu clave API desde Google AI Studio

Navega a Google AI Studio e inicia sesión con tu cuenta de Google. El acceso al nivel gratuito no requiere configuración de facturación: puedes generar claves API y comenzar a hacer solicitudes de inmediato dentro de los límites de velocidad. Haz clic en "Get API Key" en la barra lateral izquierda, luego en "Create API Key in new project" si no tienes un proyecto de Google Cloud existente. Copia la clave inmediatamente, ya que Google AI Studio no la muestra de nuevo después de la generación inicial. Guárdala en una variable de entorno: export GEMINI_API_KEY="tu_clave_aquí". Evita incluir claves API directamente en el código fuente, especialmente para aplicaciones que se confirmarán en sistemas de control de versiones.

Paso 2: Instala el SDK de Gemini

Para Python, el SDK oficial es google-generativeai. Instálalo con:

bash
pip install google-generativeai>=0.8.0

El requisito de versión mínima importa porque el soporte de generación de imágenes se añadió en la versión 0.8.0. Las versiones anteriores se importarán correctamente pero fallarán en tiempo de ejecución cuando intentes llamar a modelos con capacidad de imagen. Para Node.js:

bash
npm install @google/generative-ai

El SDK de Node.js sigue la misma restricción de versión: asegúrate de ejecutar @google/generative-ai@0.21.0 o posterior para soporte completo de generación de imágenes.

Paso 3: Realiza tu primera solicitud a la API

Antes de escribir el código de la aplicación, verifica que tu clave y la instalación del SDK funcionen correctamente con la solicitud más simple posible:

python
import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel("gemini-3.1-flash-image-preview")
response = model.generate_content(
    "Una manzana roja sobre una mesa blanca, fotorrealista"
)


for part in response.candidates[0].content.parts:
    if hasattr(part, 'inline_data'):
        import base64
        image_bytes = base64.b64decode(part.inline_data.data)
        with open("test_output.png", "wb") as f:
            f.write(image_bytes)
        print("Imagen guardada en test_output.png")

Si ves "Imagen guardada en test_output.png", tu configuración funciona correctamente. Si recibes un error 403 PERMISSION_DENIED, verifica que tu clave API se haya copiado correctamente y que el ID del modelo coincida exactamente: los IDs de modelo distinguen entre mayúsculas y minúsculas, y el sufijo preview debe incluirse para Nano Banana 2.

Paso 4: Maneja la estructura de respuesta correctamente

Uno de los errores más comunes en las integraciones tempranas de la API de Imágenes de Gemini es no tener en cuenta la estructura de respuesta. A diferencia de la generación de texto donde response.text te da la salida completa, las respuestas de imagen incrustan la imagen generada como inline_data dentro de un objeto Part dentro de candidates[0].content.parts. La imagen está codificada en base64 e identificada por su tipo MIME (image/png o image/jpeg). Siempre itera sobre las partes y verifica el atributo inline_data en lugar de asumir una posición de índice fija, ya que algunos prompts pueden generar tanto partes de texto como de imagen en la misma respuesta.

Ejemplos de Código para Todos los Modelos de Imágenes de Gemini (Python, Node.js, cURL)

El código funcional que puedes copiar, pegar y ejecutar hoy es lo más valioso que puede proporcionar una guía de la API de Imágenes de Gemini. Los ejemplos a continuación están verificados contra el comportamiento de la API de marzo de 2026 y cubren los dos modelos más utilizados: Nano Banana 2 por su recencia y soporte de nivel gratuito, e Imagen 4 Fast por su eficiencia de costo en producción.

Ejemplos en Python

Nano Banana 2 — generación estándar con manejo de errores:

python
import google.generativeai as genai
import base64
import os
from pathlib import Path

def generate_image_gemini(
    prompt: str,
    output_path: str = "output.png",
    model_id: str = "gemini-3.1-flash-image-preview"
) -> bool:
    """
    Genera una imagen usando la API de Imágenes de Gemini.
    Retorna True en caso de éxito, False en caso de fallo.
    """
    genai.configure(api_key=os.environ["GEMINI_API_KEY"])
    model = genai.GenerativeModel(model_id)

    try:
        response = model.generate_content(prompt)

        for part in response.candidates[0].content.parts:
            if hasattr(part, 'inline_data') and part.inline_data.mime_type.startswith('image/'):
                image_bytes = base64.b64decode(part.inline_data.data)
                Path(output_path).write_bytes(image_bytes)
                print(f"Imagen guardada: {output_path} ({len(image_bytes)/1024:.1f} KB)")
                return True

        print(f"Sin imagen en la respuesta. Texto: {response.text[:200]}")
        return False

    except Exception as e:
        print(f"Generación fallida: {e}")
        return False

# Uso
generate_image_gemini(
    prompt="Un logo minimalista para una startup tecnológica, formas geométricas, azul y blanco",
    output_path="logo.png"
)

Nano Banana — API Batch para reducción de costos:

python
import google.generativeai as genai
import base64
import json
import os

def create_batch_image_job(prompts: list[str]) -> str:
    """
    Envía múltiples solicitudes de generación de imágenes como trabajo por lotes.
    Los trabajos por lotes se procesan en 24 horas al 50% del precio estándar.
    Retorna el ID del trabajo por lotes.
    """
    genai.configure(api_key=os.environ["GEMINI_API_KEY"])

    requests = []
    for i, prompt in enumerate(prompts):
        requests.append({
            "custom_id": f"image_{i}",
            "method": "POST",
            "url": "/v1/models/gemini-2.5-flash-image:generateContent",
            "body": {
                "contents": [{"parts": [{"text": prompt}]}]
            }
        })

    # Escribe solicitudes en archivo JSONL
    with open("batch_requests.jsonl", "w") as f:
        for req in requests:
            f.write(json.dumps(req) + "\n")

    # Sube y envía (requiere File API)
    client = genai.upload_file("batch_requests.jsonl")
    batch = genai.create_batch(input_file=client.uri)
    print(f"Trabajo por lotes creado: {batch.name}")
    return batch.name

# 100 imágenes a \$0.0195 cada una = \$1.95 total (vs \$3.90 estándar)
prompts = [f"Foto de producto variación {i}: silla moderna, fondo blanco" for i in range(100)]
job_id = create_batch_image_job(prompts)

Ejemplos en Node.js

javascript
import { GoogleGenerativeAI } from "@google/generative-ai";
import { writeFileSync } from "fs";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateImage(prompt, outputPath = "output.png") {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  const result = await model.generateContent(prompt);
  const response = result.response;

  for (const part of response.candidates[0].content.parts) {
    if (part.inlineData && part.inlineData.mimeType.startsWith("image/")) {
      const imageBuffer = Buffer.from(part.inlineData.data, "base64");
      writeFileSync(outputPath, imageBuffer);
      console.log(`Imagen guardada: ${outputPath} (${imageBuffer.length / 1024} KB)`);
      return true;
    }
  }

  console.log("No se generó imagen. Texto de respuesta:", response.text());
  return false;
}

// Procesamiento por lotes con control de concurrencia
async function generateImageBatch(prompts, concurrency = 3) {
  const results = [];
  for (let i = 0; i < prompts.length; i += concurrency) {
    const batch = prompts.slice(i, i + concurrency);
    const batchResults = await Promise.allSettled(
      batch.map((prompt, j) =>
        generateImage(prompt, `output_${i + j}.png`)
      )
    );
    results.push(...batchResults);
    // Breve pausa entre lotes para respetar los límites de velocidad
    if (i + concurrency < prompts.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  return results;
}

// Ejemplo de uso
await generateImage(
  "Un lago de montaña sereno al amanecer, fotorrealista, calidad 8K",
  "mountain_lake.png"
);

Ejemplo con cURL

Para pruebas y scripts de shell, cURL proporciona el camino más directo hacia la API:

bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "Una foto de producto de una lámpara de escritorio minimalista de madera sobre fondo blanco"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE", "TEXT"]
    }
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
for part in data['candidates'][0]['content']['parts']:
    if 'inlineData' in part:
        with open('output.png', 'wb') as f:
            f.write(base64.b64decode(part['inlineData']['data']))
        print('Guardado output.png')
"

Usando Imagen 4 Fast via REST (estructura de endpoint diferente):

bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-fast-generate-001:predict?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "Un auto deportivo rojo fotorrealista en una carretera de montaña"}],
    "parameters": {"sampleCount": 1}
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
img_data = data['predictions'][0]['bytesBase64Encoded']
with open('output.png', 'wb') as f:
    f.write(base64.b64decode(img_data))
print('Guardado output.png')
"

Ten en cuenta que Imagen 4 usa un formato de endpoint API diferente (/predict en lugar de /generateContent) y una estructura de respuesta diferente. Esta es una de las diferencias clave entre la familia Imagen 4 y los modelos de imagen nativos de Gemini: comparten la misma clave API pero tienen esquemas de solicitud/respuesta distintos.

Precios de la API de Imágenes de Gemini: Desglose Completo de Costos (Marzo 2026)

Comprender el costo real de la generación de imágenes de Gemini requiere ir más allá del precio titular por imagen para entender cómo la resolución, los descuentos por lotes y el consumo del nivel gratuito afectan tu factura mensual real. La información de precios a continuación proviene de la documentación de Precios para Desarrolladores de Google AI a partir de marzo de 2026.

Precios Estándar: Tabla Completa

Escenarios de costo del mundo real para patrones de uso comunes:

Para una startup que construye una herramienta de diseño con IA que genera 10,000 imágenes por mes para los usuarios, el rango de costo es de $200 (Imagen 4 Fast) a $1,340 (Nano Banana Pro a 1K). La elección del modelo aquí tiene un multiplicador de costo de 6.7x: elegir el modelo correcto desde el primer día tiene más impacto que cualquier otra optimización.

Para un desarrollador freelance que construye un generador de sitios de portafolio que procesa 500 imágenes por mes, el nivel gratuito cubre casi todo el volumen. El nivel gratuito de Google AI Studio permite aproximadamente 500 solicitudes por día, es decir, 15,000 por mes, muy por encima de este nivel de uso. El costo práctico es $0 durante las fases de desarrollo y de tracción temprana.

Para una agencia de contenido que realiza generación de imágenes de redes sociales de alto volumen (100,000 imágenes por mes), Imagen 4 Fast a $0.02/imagen totaliza $2,000 por mes, frente a $3,900 para Nano Banana estándar. La API Batch de Nano Banana a $0.0195/imagen lleva el costo a $1,950, comparable a Imagen 4 Fast pero con una ventana de procesamiento de 24 horas.

El descuento de la API Batch merece atención especial. Nano Banana es actualmente el único modelo de imágenes de Gemini que ofrece un descuento por lotes: 50% de descuento sobre el precio estándar a través de la API Batch. Esta es una ventaja significativa para flujos de trabajo no en tiempo real, como la generación de contenido nocturna, publicaciones programadas en redes sociales y fotografía de productos en masa. La contrapartida es que los trabajos por lotes están garantizados para completarse dentro de las 24 horas, pero pueden comenzar a procesarse hasta varias horas después de la presentación. Para un sistema de producción, esto generalmente significa ejecutar trabajos por lotes por la noche y tener los resultados disponibles por la mañana.

Los desarrolladores fuera de EE. UU. a menudo usan APIs relay como laozhang.ai tanto por el acceso como por los beneficios de costo. Una API relay pasa tus solicitudes a la API oficial de Google en tu nombre mientras proporciona una interfaz compatible. Para detalles de precios de Nano Banana Pro, incluido cómo los precios del relay se comparan con las tarifas oficiales, consulta la guía de precios dedicada.

Nivel Gratuito Explicado: ¿Cuántas Imágenes Gratuitas Puedes Generar?

El nivel gratuito de la API de Imágenes de Gemini tiene dos formas distintas que a menudo se confunden, y entender la diferencia determina si necesitas configurar la facturación desde el primer día.

Google AI Studio (Personal, para desarrolladores): La API de Google AI Studio, a la que accedes con una clave desde aistudio.google.com, proporciona un nivel gratuito de aproximadamente 500 solicitudes por día para Nano Banana y Nano Banana 2 a resoluciones estándar (Google AI Studio, marzo 2026). Este es el límite relevante para los desarrolladores que integran la API en aplicaciones. El nivel gratuito cuenta solicitudes, no imágenes per se, y cada solicitud puede generar múltiples imágenes dependiendo de la configuración. Es importante destacar que el nivel gratuito no se aplica a los modelos Imagen 4 en absoluto: esos requieren facturación desde la primera llamada.

Aplicación Gemini (Producto de consumo): La aplicación de consumo Gemini (el chatbot en gemini.google.com) proporciona cuotas separadas para las funciones de generación de imágenes. A partir de diciembre de 2025, Google redujo la cuota de generación de imágenes gratuita en la aplicación Gemini a 20 imágenes por día para usuarios Básicos (gratuitos). Esta cuota de consumidor es completamente independiente de la cuota de API y no afecta a los desarrolladores que usan claves API.

Las solicitudes del nivel gratuito en Google AI Studio tienen límites de velocidad más bajos que las solicitudes de pago. La restricción típica del nivel gratuito es de 60 solicitudes por minuto (RPM) y el límite máximo de 500 solicitudes por día. Una vez que añades información de facturación a tu proyecto de Google Cloud, los límites de velocidad aumentan significativamente: el nivel de pago estándar permite 1,000 RPM para la mayoría de los modelos de imágenes de Gemini. Para información completa sobre límites de velocidad, consulta la guía completa de límites de velocidad de la API de Gemini y la guía de acceso gratuito a la API de Imágenes de Gemini.

La implicación práctica para los equipos: Las cuotas del nivel gratuito son por proyecto, no por usuario. Si tu equipo tiene múltiples desarrolladores, pueden compartir la cuota del nivel gratuito de un proyecto, pero un solo proyecto que sirva a muchos desarrolladores agotará rápidamente el límite de 500 solicitudes/día. La solución alternativa durante el desarrollo es crear proyectos separados de Google Cloud para cada desarrollador, cada uno con su propia asignación de nivel gratuito.

Nivel gratuito para Nano Banana 2 a 4K: El nivel de resolución 4K de Nano Banana 2 no tiene un equivalente de nivel gratuito. Solo las imágenes de resolución 1K califican para el uso del nivel gratuito con este modelo. Esto significa que probar la generación en 4K requiere configuración de facturación incluso durante el desarrollo: ten esto en cuenta en tu planificación de presupuesto si la resolución 4K es un requisito.

API Relay de Gemini Image: Acceso Sin Restricciones y Precios Más Bajos

La restricción de acceso es un problema real para muchos desarrolladores. La API de Gemini está disponible oficialmente en un conjunto limitado de países y territorios, y los desarrolladores en China, ciertos mercados del sudeste asiático y partes de Europa pueden encontrar que las llamadas a la API devuelven errores de acceso denegado o simplemente agotan el tiempo de espera sin completarse. Más allá de las restricciones geográficas, algunas organizaciones tienen políticas de red que bloquean las conexiones directas a la infraestructura de Google.

Una API relay (también llamada API proxy o API espejo) soluciona esto enrutando tus solicitudes a través de un servicio intermediario compatible. Desde la perspectiva de tu aplicación, apuntas a la URL base del relay en lugar del endpoint oficial de la API de Google, y el relay reenvía tu solicitud a los servidores reales de Google y devuelve la respuesta. El requisito clave es que el relay use el mismo formato de solicitud y respuesta que la API oficial: un buen relay no requiere cambios de código más allá de reemplazar la URL base.

laozhang.ai es uno de estos servicios relay que proporciona acceso a los modelos de imágenes de Gemini con formato API compatible. El precio de calidad Nano Banana Pro a través del relay de laozhang.ai es de aproximadamente $0.05 por imagen, aproximadamente un 63% más barato que la tasa oficial de Nano Banana Pro de $0.134 por imagen (marzo 2026). Esto lo convierte en una opción atractiva no solo para usuarios con acceso restringido, sino para cualquier desarrollador que priorice el costo sobre el uso directo del endpoint oficial de Google.

Cambiar de la API oficial a un relay requiere un cambio en tu código Python existente:

python
import google.generativeai as genai

# Configuración estándar (API oficial)
# genai.configure(api_key="tu_clave_api_google")

# Configuración relay (laozhang.ai)
import openai  # laozhang.ai usa formato compatible con OpenAI

client = openai.OpenAI(
    api_key="tu_clave_api_laozhang",
    base_url="https://api.laozhang.ai/v1"
)

# Generación de imagen via relay (formato compatible con OpenAI)
response = client.images.generate(
    model="gemini-3-pro-image-preview",  # Mismo ID de modelo
    prompt="Una foto de producto minimalista, fondo blanco",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(f"URL de imagen generada: {image_url}")

El relay usa el formato de API de Imágenes de OpenAI en lugar del formato del SDK de Gemini, lo que significa que usas la biblioteca Python openai en lugar de google-generativeai. Los IDs de modelo permanecen iguales, lo que facilita el cambio entre la API oficial y el relay dependiendo del contexto de implementación. Para los desarrolladores en regiones con acceso restringido, el relay es efectivamente la única forma de usar estos modelos en producción.

Qué buscar en un servicio relay: La señal de calidad más importante es la compatibilidad de API: el relay debe aceptar los mismos IDs de modelo, devolver la misma estructura de respuesta y admitir los mismos parámetros que la API oficial. laozhang.ai admite todos los modelos de imágenes de Gemini, incluido Nano Banana 2 (el lanzamiento de febrero de 2026). La documentación de API está disponible en docs.laozhang.ai y puedes probar la generación de imágenes de forma interactiva en images.laozhang.ai.

Uso Avanzado: API Batch, Manejo de Errores y Consejos de Producción

Pasar de un prototipo funcional a una integración de producción de la API de Imágenes de Gemini requiere abordar tres áreas que los tutoriales típicamente omiten: la API Batch para reducción de costos, el manejo robusto de errores para los errores que definitivamente encontrarás, y patrones de diseño de sistemas que funcionen a escala.

La API Batch está disponible para Nano Banana (gemini-2.5-flash-image) y proporciona una reducción de costos del 50% a cambio de procesamiento asíncrono. La arquitectura es: carga un archivo JSONL de solicitudes, envía un trabajo por lotes, sondea para completar y descarga los resultados. Para flujos de trabajo de alto volumen donde la latencia no es una restricción (generación de contenido programada, colas de procesamiento nocturno, fotografía de productos en masa), la API Batch reduce efectivamente a la mitad tus costos de generación de imágenes sin ninguna concesión en calidad.

El manejo de errores es innegociable en producción. Los tres errores que encontrarás con más frecuencia con la API de Imágenes de Gemini son 429 (límite de velocidad excedido), 400 (violación de política de contenido) y 503 (servicio temporalmente no disponible). Cada uno requiere una respuesta diferente:

python
import time
import google.generativeai as genai
from google.api_core import exceptions as google_exceptions

def generate_image_with_retry(prompt: str, max_retries: int = 3) -> bytes | None:
    model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

    for attempt in range(max_retries):
        try:
            response = model.generate_content(prompt)
            for part in response.candidates[0].content.parts:
                if hasattr(part, 'inline_data'):
                    import base64
                    return base64.b64decode(part.inline_data.data)
            return None

        except google_exceptions.ResourceExhausted as e:
            # 429: Límite de velocidad. Retroceso exponencial.
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) * 5  # 5s, 10s, 20s
                print(f"Límite de velocidad alcanzado. Esperando {wait_time}s antes del reintento {attempt + 2}/{max_retries}")
                time.sleep(wait_time)
            else:
                raise

        except google_exceptions.InvalidArgument as e:
            # 400: Política de contenido. No reintentar; modifica el prompt.
            print(f"Violación de política de contenido: {e}")
            return None

        except google_exceptions.ServiceUnavailable as e:
            # 503: Interrupción temporal. Espera corta y reintento.
            if attempt < max_retries - 1:
                time.sleep(30)
            else:
                raise

    return None

Para soluciones detalladas al error 429 de límite de velocidad específicamente, consulta soluciones al error 429 de límite de velocidad de Gemini.

El comportamiento de la política de contenido en la API de Imágenes de Gemini es más estricto que en algunos modelos competidores. La API rechazará prompts que involucren rostros humanos realistas en ciertos contextos, contenido explícito y algunos temas políticos o sensibles. El rechazo normalmente devuelve un error 400 con un mensaje que indica la violación de la política de contenido. En los sistemas de producción, implementa la validación de prompts antes de llamar a la API, mantén una lista de patrones de prompts problemáticos conocidos y diseña tu experiencia de usuario para manejar y explicar los rechazos de política de manera elegante, en lugar de mostrar mensajes de error sin procesar.

Planificación de límites de velocidad para producción: Los límites del nivel gratuito (60 RPM, 500 RPD) son suficientes para el desarrollo y aplicaciones de bajo tráfico. Los límites del nivel de pago varían según el modelo y el nivel de facturación. Para aplicaciones que esperan tráfico significativo, usa la guía completa de límites de velocidad de la API de Gemini para planificar tu arquitectura antes del lanzamiento. Los controles de concurrencia (limitando las solicitudes de API paralelas en vuelo) son más efectivos que la lógica de reintento para prevenir errores de límite de velocidad en primer lugar.

Ingeniería de prompts para calidad de imagen: Los modelos de imágenes de Gemini responden bien a prompts estructurados que especifican explícitamente el sujeto, el estilo, la iluminación y la composición. "Una foto de producto" produce resultados mediocres. "Una foto de producto fotorrealista de una taza de café de cerámica, iluminación natural suave desde la izquierda, fondo blanco, enfoque nítido, estilo de fotografía comercial, detalle 4K" produce resultados adecuados para uso profesional. Mantén una biblioteca de plantillas de prompts probadas para tu caso de uso y controla su versión junto con tu código.

Preguntas Frecuentes: Consultas Comunes sobre la API de Imágenes de Gemini

¿Es gratuita la API de Imágenes de Gemini?

La API de Imágenes de Gemini proporciona un nivel gratuito a través de Google AI Studio de aproximadamente 500 solicitudes por día para Nano Banana y Nano Banana 2 a resoluciones estándar. Los modelos Imagen 4 (Fast, Standard, Ultra) no tienen nivel gratuito y requieren facturación desde la primera solicitud. El nivel gratuito no incluye Nano Banana 2 a resolución 4K ni Nano Banana Pro. Para desarrolladores individuales y proyectos pequeños, el nivel gratuito es lo suficientemente sustancial como para construir y probar una integración completa sin ningún costo.

¿Cuál es la diferencia entre Nano Banana e Imagen 4?

Los modelos Nano Banana (gemini-2.5-flash-image, gemini-3.1-flash-image-preview, gemini-3-pro-image-preview) son los modelos de generación de imágenes multimodales nativos de Gemini de Google. Tienen nivel gratuito, admiten el SDK estándar de Gemini y pueden generar imágenes como parte de conversaciones de múltiples turnos. Los modelos Imagen 4 son la infraestructura de generación de imágenes profesional dedicada de Google: sin nivel gratuito, formato de endpoint API diferente, pero potencialmente mayor calidad fotorrealista. La elección correcta depende de tu caso de uso: modelos nativos de Gemini para facilidad de desarrollo y acceso al nivel gratuito, Imagen 4 para eficiencia de costo en producción (Fast) o máxima calidad (Standard/Ultra).

¿Puedo usar la API de Imágenes de Gemini fuera de EE. UU.?

La API oficial de Gemini está disponible en un conjunto limitado de países. Los desarrolladores en regiones donde el acceso directo está restringido (incluida China y otros mercados) pueden usar APIs relay como laozhang.ai que proporcionan acceso a la API compatible a través de servidores intermediarios. Un relay solo requiere un cambio de URL base en tu configuración y proporciona funcionalidad idéntica a precios potencialmente más bajos.

¿Cómo puedo reducir mis costos de la API de Imágenes de Gemini?

Las estrategias de reducción de costos más impactantes son: (1) Usa la API Batch para Nano Banana: 50% de descuento con una ventana de procesamiento de 24 horas. (2) Usa Imagen 4 Fast ($0.02/imagen) para cargas de trabajo de producción si los requisitos de calidad lo permiten. (3) Maximiza el uso del nivel gratuito durante el desarrollo: 500 solicitudes/día es sustancial para pruebas. (4) Considera las APIs relay como laozhang.ai para imágenes de calidad Pro a aproximadamente un 63% menos que la tasa oficial de Nano Banana Pro.

¿Qué formatos de imagen devuelve la API de Imágenes de Gemini?

Los modelos nativos de Gemini (serie Nano Banana) devuelven imágenes como datos codificados en base64 con tipo MIME image/png de forma predeterminada. Imagen 4 también devuelve datos codificados en base64. El control de resolución y formato varía según el modelo: Nano Banana 2 admite selección explícita de resolución (1K o 4K), mientras que otros modelos producen salida a su resolución predeterminada. Si necesitas un formato específico como JPEG o WebP, convierte la salida PNG usando una biblioteca como Pillow después de recibir la respuesta.

¿Qué pasó con Gemini 2.0 Flash Image y Gemini 3.0 Flash?

Los nombres de los modelos en la línea de imágenes de Gemini han evolucionado. gemini-2.0-flash-image era una versión anterior que ha sido reemplazada por gemini-2.5-flash-image (Nano Banana). El modelo de texto gemini-3.0-flash no está relacionado con la generación de imágenes. gemini-3-pro-image-preview (Nano Banana Pro) no debe confundirse con el obsoleto modelo de texto gemini-3.0-pro, que fue retirado el 9 de marzo de 2026. Utiliza siempre los IDs de API enumerados en esta guía en lugar de intuir el ID del modelo a partir de los patrones de nombres.

Conclusión: Elige Tu Camino a Seguir

La API de Imágenes de Gemini en 2026 ofrece una gama genuina de compensaciones entre cinco modelos distintos. Para la mayoría de los desarrolladores que inician un nuevo proyecto, Nano Banana 2 (gemini-3.1-flash-image-preview) es el mejor punto de partida predeterminado: es el modelo más reciente de la familia nativa de Gemini, tiene soporte de nivel gratuito para el desarrollo y ofrece mejoras de calidad sobre el Nano Banana original mientras mantiene los costos razonables a resolución 1K.

A medida que tu proyecto madura, la selección del modelo de producción debe estar impulsada por tus requisitos reales de calidad y volumen. Las aplicaciones de alto volumen donde la calidad de imagen es suficiente con Imagen 4 Fast encontrarán difícil superar los $0.02/imagen. Las aplicaciones donde la calidad de imagen es un diferenciador central del producto deben evaluar Nano Banana Pro e Imagen 4 Standard o Ultra en la calidad de salida real con sus tipos de prompts específicos, en lugar de tomar la decisión basándose únicamente en el precio.

Los desarrolladores que enfrentan restricciones de acceso geográfico tienen un camino práctico a través de las APIs relay: el cambio de integración es mínimo, la compatibilidad de la API es completa y el costo por imagen puede ser menor que los precios oficiales para modelos premium. Esto convierte a las APIs relay en una opción de producción viable en lugar de solo una solución alternativa.

El siguiente paso más importante para cualquier integración de la API de Imágenes de Gemini es ejecutar el código de prueba de la Sección 3 con los prompts reales de tu caso de uso y evaluar la calidad de salida entre modelos antes de realizar un compromiso arquitectónico. Las clasificaciones de calidad de modelos en guías como esta son directcionalmente correctas, pero el comportamiento específico por prompt varía lo suficiente como para que las pruebas directas con tu tipo de contenido sean irremplazables.