Ejemplos de código para generar imágenes con Gemini: JavaScript, Python y cURL

A 22 de marzo de 2026, la ruta más segura para código de generación de imágenes con Gemini es la API nativa con gemini-3.1-flash-image-preview. Empieza por ahí salvo que ya sepas que necesitas la vía más cara de gemini-3-pro-image-preview para gráficos con mucho texto, infografías o activos premium donde equivocarte salga caro.

Esa recomendación importa porque el stack actual de imágenes de Gemini se lee mal con demasiada facilidad en la primera página de resultados. Algunas páginas hablan de Gemini app, otras de AI Studio, otras son docs puras de API y no faltan tutoriales viejos centrados en la línea 2.5. Para un desarrollador, el primer paso correcto es más estrecho y más útil: elegir el modelo actual, copiar una request nativa que funcione, guardar una imagen real y solo después decidir si edición, Pro o Batch cambian de verdad la ruta.

Hay otro caveat que conviene dejar arriba del todo. Gemini Apps, AI Studio y Gemini API están relacionados, pero no comparten una sola regla simple de gratis frente a pago. La página oficial de billing sigue diciendo que las cuentas nuevas arrancan en Free tier, pero el post de Google para desarrolladores sobre Nano Banana 2, publicado el 26 de febrero de 2026, también deja claro que para usar ese modelo en AI Studio hace falta una API key de pago. Si pasas por alto esa diferencia, es fácil acabar depurando el problema equivocado antes incluso de validar tu código.

Resumen rápido

• Para código nuevo de image generation, empieza por la API nativa de Gemini y no por una capa genérica de compatibilidad. Ahí es donde imageSize, aspectRatio, la edición multi-turn y las funciones más útiles quedan más claras.
• La ruta por defecto hoy es gemini-3.1-flash-image-preview. Sube a gemini-3-pro-image-preview cuando la calidad del texto dentro de la imagen, la salida tipo infografía o el valor del activo justifiquen el coste extra.
• La primera request debería ser aburrida: genera una sola imagen, guárdala y verifica el resultado antes de añadir edición, grounding, Batch mode o un pipeline de prompts más complejo.
• En los modelos de imagen de Gemini 3 conviene fijar imageSize y aspectRatio de forma explícita. La documentación actual expone 512, 1K, 2K y 4K, además de más relaciones de aspecto que la línea legacy 2.5.
• Precios, reglas de pago, fechas de apagado y límites deben tratarse como hechos vivos. Ahora mismo gemini-2.5-flash-image sigue siendo la línea oficial más barata, pero la página de deprecations también marca su cierre para el 2 de octubre de 2026.

Si antes quieres aclarar la diferencia entre app, AI Studio y API, la mejor continuación es el tutorial de generación de imágenes con Gemini. Si lo siguiente que te preocupa es el coste, ve a la guía de precios de Gemini image generation API. Y si tu caso real es edición de imágenes, no generación desde cero, la página más útil será la guía de edición imagen a imagen en Gemini.

Primero elige la ruta de código correcta para Gemini Image

El error más caro en este tema no suele ser un prompt flojo, sino arrancar desde la superficie equivocada. Mucha gente busca "Gemini image generation code examples" después de haber visto cómo la app genera una imagen o cómo AI Studio la renderiza en el navegador. Eso hace que la API parezca más simple de lo que es. Pero la API no hereda por arte de magia las suposiciones de la app. Aun así tienes que escoger el model ID correcto, entender el billing, manejar la response y vigilar las cuotas del proyecto.

Para la mayoría de integraciones nuevas, la referencia correcta sigue siendo la documentación oficial sobre Gemini API image generation and editing. Ahí Google recomienda de forma explícita Gemini 3.1 Flash Image Preview como ruta principal actual y enseña las funciones que cambian el código de verdad: responseModalities, aspectRatio, imageSize, edición multi-turn y controles específicos de imagen. Por eso esta página se queda en la ruta nativa de Gemini y no toma OpenAI compatibility como centro de la explicación. La compatibilidad sirve para migrar, pero no para aprender una capacidad que todavía se está moviendo rápido.

Eso no significa que todas las image models de Gemini deban tratarse igual. La pricing page actual separa mejor los casos de uso que muchos tutoriales de terceros. gemini-3.1-flash-image-preview es la línea rápida por defecto. gemini-3-pro-image-preview es la línea premium. gemini-2.5-flash-image sigue activa y sigue siendo la fila oficial más barata, pero la página de deprecations ya le pone fecha de apagado: 2 de octubre de 2026. Así que en una guía nueva "más barato" ya no equivale a "mejor punto de partida".

La regla práctica es sencilla. Si estás construyendo algo nuevo, arranca con Flash Image. Si vas a generar posters, diagrams, infografías o cualquier activo donde el texto y la calidad del resultado manden, mantén Pro en el radar desde el principio. Y si eliges la línea 2.5 por economía, dilo claramente: estás escogiendo una rama legacy por coste, no la opción más preparada para el futuro.

Hay otra decisión de ruta que también importa. AI Studio puede servir como playground para iterar prompts, pero no conviene confundirlo con el contrato final de tu aplicación. El propio post de Nano Banana 2 deja claro lo del paid API key para ese modelo en AI Studio. Eso significa que la arquitectura, el logging y la planificación de cuotas deben pensarse como si fueras a vivir en la API aunque tus primeras pruebas ocurran en una UI.

Ejemplo en JavaScript: la vía más corta hoy para Node y backend

Si ya trabajas en Next.js, Node.js o cualquier entorno backend en JavaScript, la ruta actual más limpia es @google/genai. Mantén el cliente del lado del servidor, carga GEMINI_API_KEY desde variables de entorno y guarda el inlineData que te devuelve la API en disco o en object storage.

Es también el mejor primer ejemplo porque toca justo las piezas que más se rompen después: nombre de paquete actual, nombre de modelo actual, controles de imagen explícitos y parsing de la response. No hace falta construir el pipeline entero el primer día. Solo hace falta probar que una imagen vuelve, se guarda y respeta el tamaño y la proporción que pediste.

javascript
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const prompt = `
Create a clean 16:9 product hero image of a matte black travel mug
on a light concrete surface. Use soft studio lighting, crisp texture,
and calm negative space on the right for marketing copy.
`;

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: prompt,
  config: {
    responseModalities: ["IMAGE"],
    imageConfig: {
      aspectRatio: "16:9",
      imageSize: "2K",
    },
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    const buffer = Buffer.from(part.inlineData.data, "base64");
    fs.writeFileSync("travel-mug-hero.png", buffer);
  }
}

Aquí conviene quedarse con cuatro detalles. Primero: el modelo es gemini-3.1-flash-image-preview, no un ejemplo viejo de la era 2.5. Segundo: responseModalities: ["IMAGE"] hace que Gemini devuelva solo la imagen cuando no necesitas texto adicional. La documentación dice que el comportamiento por defecto mezcla texto e imagen, lo cual puede ser útil en flujos conversacionales, pero para el primer caso de "guardar el archivo" lo más limpio es imagen pura. Tercero: el control realmente útil vive en imageConfig. Si la forma de salida importa, dilo de forma explícita. Cuarto: este ejemplo debe quedarse en contexto server-side. No metas una API key permanente en frontend público porque el snippet sea corto.

Cuando eso ya funciona, la siguiente decisión razonable en JavaScript es si quieres salida de solo imagen o una respuesta mixta de texto e imagen. Para un worker backend suele ser más cómoda la primera. Para una herramienta de creación donde el usuario agradece explicaciones o sugerencias de iteración, la segunda puede ser mejor. Esa es una de las ventajas menos comentadas del flujo nativo de Gemini: se puede tratar como conversación, no solo como endpoint de imágenes.

JavaScript también es el lugar donde muchos equipos empiezan a complicarlo todo demasiado pronto. Tu primera request no necesita grounding, ni chat state persistente, ni un orchestration layer enorme. La progresión útil suele ser más aburrida: primera imagen, luego edición, luego almacenamiento, luego retries, luego cuotas y solo después extras como grounding.

Ejemplo en Python: la ruta actual más limpia para edición e iteración

Python suele ser la forma más cómoda de aprender Gemini image generation. La documentación oficial es clara, el SDK actual es compacto y los patrones de edición encajan muy bien con scripts o herramientas internas. Por eso Python es especialmente fuerte para pipelines visuales, operaciones internas, batch jobs y flujos donde lo importante no es pedir una sola imagen una vez, sino iterar sobre ella.

La mayor ventaja de Python aquí es que te deja pasar de "generar una imagen" a "editar una imagen existente" sin cambiar de mental model. Las docs de Gemini presentan generación y edición a través del mismo generate_content, con inputs distintos pero una estructura coherente. Para trabajo real con imágenes esto encaja mejor que las viejas APIs text-to-image que trataban cada cambio como si fuera un producto aparte.

python
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client()

base_image = Image.open("living-room.png")
prompt = """
Using the provided image of a living room, change only the blue sofa
to a vintage brown leather chesterfield sofa. Keep the pillows,
lighting, coffee table, and room layout unchanged.
"""

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[prompt, base_image],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="4:3",
            image_size="2K",
        ),
    ),
)

for part in response.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = part.as_image()
        image.save("living-room-edit.png")

En ese ejemplo mandan dos cosas. La primera es la disciplina del prompt. Si quieres una edición local, protege con claridad lo que no debe cambiar. Gemini sigue instrucciones bastante bien, pero no va a adivinar por sí solo que layout, lighting o props deben quedarse intactos. La segunda es que la imagen base va dentro de contents junto al texto. Ese es el mental model correcto para la edición actual en Gemini: aportas contexto y pides un cambio controlado, no saltas a un endpoint completamente distinto.

También es aquí donde los flujos multi-turn empiezan a ser más valiosos que un prompt gigantesco. La documentación de image generation recomienda edición conversacional y multi-turn. En práctica eso importa mucho: el mejor prompt de producción rara vez es el más largo. Normalmente es una primera instrucción clara, un resultado, y luego un follow-up que pide solo el delta. Si la primera imagen ya resolvió el 80 %, suele ser mejor seguir en el mismo contexto que empezar otra vez desde cero.

Python destaca en esas iteraciones porque se combina bien con pipelines de assets, hooks de moderación y postprocesado. Pero justo ahí aparece un error habitual: muchas veces el proof of concept funciona en notebook o script y nunca se vuelve para endurecerlo. Si ese flujo va a vivir en producción, conviene añadir retries, registrar qué modelo y tamaño pediste y observar el comportamiento de uso antes de que el script se convierta en infraestructura invisible.

Ejemplo en cURL y REST puro: cuando necesitas depuración de bajo nivel o integración agnóstica

Si el SDK te parece demasiado opaco, o si tu runtime no es Python ni Node, REST puro sigue siendo la fuente de verdad más limpia. cURL no es la forma más cómoda de construir una aplicación entera, pero sí la mejor de ver exactamente qué request espera Gemini API. Por eso resulta tan útil para depurar elección de modelo, serialización de payload, capas de proxy y diferencias entre AI Studio y tu código.

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a 16:9 studio photo of a white sneaker on a soft gray background with crisp side lighting and premium ecommerce styling."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

La razón para mantener un ejemplo en cURL no es la belleza del shell, sino la claridad. Si la request funciona en cURL y falla en el SDK, el problema probablemente está en la versión del cliente, en tu wrapper o en el parsing. Si también falla en cURL, el foco cambia al contrato de API, al billing del proyecto, a los límites o al modelo elegido. Eso acelera mucho la depuración.

Para lenguajes sin SDK oficial o entornos con pocas dependencias, REST puro también es el mejor punto de partida. Quizá luego lo envuelvas en Go, Rust, PHP o una plataforma interna, pero antes conviene ver el wire format real. cURL te obliga a mirar generateContent, contents, generationConfig, responseModalities e imageConfig de forma explícita. Eso ayuda después cuando necesitas explicar el contrato o construir tu propia capa interna.

La desventaja es obvia: tendrás que decodificar la imagen por tu cuenta y pierdes las ayudas del SDK para parts, chats o file inputs. Por eso aquí REST funciona mejor como truth source y herramienta de debugging que como ruta de comodidad diaria.

Edición, flujos multi-turn y opciones de mayor resolución que sí cambian tu código

Aquí es donde Gemini image generation se separa de los tutoriales superficiales. Demasiadas páginas se quedan en una sola llamada text-to-image. Eso sirve para una demo, pero no es donde vive el valor en la mayoría de productos. Los flujos reales necesitan ediciones controladas, imágenes de referencia, tamaños de salida más altos e iteraciones que preserven lo bueno de la versión anterior.

La documentación actual de Google es especialmente útil en esta parte. No se limita a enseñar una generación y ya está. También recomienda edición multi-turn y muestra ejemplos tipo chat donde primero se crea una infografía y luego se cambia el idioma del texto en un turno posterior. La importancia no está solo en el ejemplo, sino en el cambio de mental model: Gemini image generation no es únicamente un endpoint que devuelve píxeles. Es un sistema visual conversacional en el que una edición nueva puede apoyarse en el contexto anterior.

javascript
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const chat = ai.chats.create({
  model: "gemini-3.1-flash-image-preview",
  config: {
    responseModalities: ["TEXT", "IMAGE"],
  },
});

await chat.sendMessage({
  message:
    "Create a vibrant infographic that explains photosynthesis like a colorful kids cookbook.",
});

const response = await chat.sendMessage({
  message: "Update this infographic to be in Spanish. Do not change any other elements.",
  config: {
    responseModalities: ["TEXT", "IMAGE"],
    imageConfig: {
      aspectRatio: "16:9",
      imageSize: "2K",
    },
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    fs.writeFileSync(
      "photosynthesis-es.png",
      Buffer.from(part.inlineData.data, "base64")
    );
  }
}

En este punto imageSize y aspectRatio dejan de ser trivia. Las docs oficiales para la línea Gemini 3 exponen 512, 1K, 2K y 4K, además de ratios como 16:9, 9:16, 21:9, 4:1 y 1:4. Eso ya cambia cómo deberías escribir el código. Si construyes assets de ecommerce, banners, anuncios, piezas para redes o gráficos para tiendas de apps, cuanto más se aproxime la salida al formato final, menos postprocesado necesitarás después.

La línea Pro también debe entenderse aquí, no como un lujo genérico. La pricing page y la ayuda de Gemini Apps cuentan la misma historia desde ángulos distintos. Flash Image es el default rápido y más barato. Pro es la ruta cara cuando la calidad del texto, la limpieza de una infografía o el valor del activo justifican el coste. En otras palabras, Pro no es el primer modelo que enseñas, pero sí es el que debes nombrar cuando el trabajo se parece a poster copy, diagram labels o premium product art.

Hay otro límite de capacidad que merece mención. La pricing page actual separa el coste de Google Search grounding y de image-based grounding en la línea Gemini 3, y las docs de imágenes muestran flujos visuales con grounding. Eso significa que algunos workflows premium ya no son solo "prompt in, image out", sino que pueden incorporar contexto recuperado. Es potente, pero no debería contaminar el primer tutorial. Primero hay que enseñar la request base; el grounding entra después, cuando el producto de verdad lo necesite.

Precios, Batch mode y cuándo merece la pena Pro

En una página de code examples el precio no debería comerse toda la atención, pero tampoco puede desaparecer. Elegir modelo y resolución es una decisión de implementación, no una simple nota de compras.

La página oficial de precios da señales bastante concretas. Gemini 3.1 Flash Image Preview cuesta aproximadamente $0.045 en 0.5K, $0.067 en 1K, $0.101 en 2K y $0.151 en 4K en modo estándar. Gemini 3 Pro Image Preview cuesta alrededor de $0.134 en 1K o 2K y $0.24 en 4K. Para la línea legacy Gemini 2.5 Flash Image, Google todavía muestra unos $0.039 en estándar y $0.0195 en Batch. No son solo números de pricing: cambian cuál debería ser el ejemplo por defecto que enseñas.

¿Cuándo merece realmente la pena Pro? Cuando fallar con la imagen cuesta más que la diferencia de precio del modelo. Ese es el caso de posters, diagrams, infografías y activos premium donde la calidad del texto o la limpieza del render cambian el resultado. Si la tarea es variación rápida, ideación o producción sensible al coste, Flash Image sigue siendo un default más fuerte.

Batch mode es la segunda decisión económica que cambia la arquitectura. La pricing page deja bastante claro que, si vas a generar muchas imágenes y puedes tolerar más latencia, Batch reduce el coste de forma notable, sobre todo en la línea 2.5 y en Flash Image. No cambia la forma básica del primer ejemplo, pero sí lo que deberías recomendar cuando el lector pasa del prototipo a trabajos programados o colas de generación.

Y aquí conviene ser honesto con la línea 2.5. Sigue siendo útil. Sigue siendo oficial. Sigue siendo más barata. Pero si publicas una guía nueva con ejemplos de código, tienes que llamarla por lo que es ahora: una rama legacy orientada a coste, con reloj de retirada visible, no la mejor apuesta por defecto para nuevas integraciones.

Resolución de problemas: errores comunes en ejemplos de código para Gemini Image

El primer error es copiar un tutorial viejo de la línea 2.5 y asumir que todavía describe la mejor ruta de salida. Ya no. Las docs actuales, la pricing page y los materiales de lanzamiento empujan a los desarrolladores hacia la línea Gemini 3 para imágenes. Si sigues usando gemini-2.5-flash-image, que sea porque elegiste conscientemente la vía legacy barata, no porque un resultado antiguo de búsqueda te arrastró allí.

El segundo error es tratar app, AI Studio y Gemini API como si compartieran el mismo contrato de producto. No lo comparten. La ayuda de Gemini Apps sirve para entender el comportamiento de Nano Banana 2 y Nano Banana Pro en la superficie de consumo. AI Studio sirve para experimentar con prompts. Pero el contrato que de verdad gobierna tu código es la API, y las páginas oficiales de billing, launch y docs dejan claro que las claves de pago y las cuotas siguen importando.

El tercer error es no fijar controles explícitos de imagen. Si la forma de salida importa, define aspectRatio. Si importa el tamaño, define imageSize. No supongas que el valor por defecto coincide con las necesidades de tu producto. Las docs dicen de forma explícita que, si no lo haces, el modelo puede heredar el tamaño de la imagen de entrada o generar una salida cuadrada. Para experimentar vale; para producción suele ser un mal default.

El cuarto error es tratar la generación de imágenes como un endpoint one-shot cuando el flujo real pide edición multi-turn. El stack actual de Gemini funciona mejor cuando conservas el contexto de un resultado parcial bueno y pides un delta concreto. Eso suele ser más rápido, más barato y más controlable que inflar el prompt y empezar cada vez desde cero.

El quinto error es ignorar las cuotas a nivel de proyecto. La página de rate limits dice que los límites se aplican por proyecto, no por API key, y que las requests per day se reinician a medianoche del horario del Pacífico. Por eso siguen apareciendo tantos 429 confusos aunque el desarrollador sienta que ha usado poco la API. La solución no es memorizar una cifra de una captura. La solución es tratar las cuotas como estado vivo del proyecto y comprobarlas en AI Studio.

El sexto error es asumir que la fila más barata es automáticamente la mejor para enseñar primero. Esa lógica pudo tener más sentido antes en la historia de Gemini Image. En 2026 ya no tanto. La secuencia educativa más responsable es current default primero, rama legacy barata después y Pro premium al final. Así ayudas al lector a tomar una buena primera decisión en vez de optimizar demasiado pronto por coste.

El séptimo error es olvidar que todas las imágenes generadas llevan SynthID watermark. No siempre rompe el workflow, pero es una característica real del producto y una página seria de implementación debería decirlo de forma explícita. Si tu problema ya no es "qué ejemplo copio" sino "por qué hoy dejó de funcionar como esperaba", las mejores continuaciones en este repo son Gemini image generation limit reset y Gemini image API free tier.

Conclusión

Los mejores Gemini image generation code examples de 2026 no son los más vistosos, sino los que hacen obvia la siguiente decisión de implementación.

Empieza con la API nativa de Gemini. Para la mayoría de flujos nuevos, el modelo por defecto sigue siendo gemini-3.1-flash-image-preview. Guarda primero una imagen real en JavaScript, Python o cURL y solo después añade complejidad. En cuanto importe la forma de salida, fija aspectRatio e imageSize de manera explícita. Sube a gemini-3-pro-image-preview solo cuando el texto dentro de la imagen, la densidad tipo infografía o el valor premium del activo cambien de verdad el resultado. Y trata gemini-2.5-flash-image como una rama legacy barata, no como la ruta futura por defecto.

Cuando tomas bien esas route decisions desde el principio, el resto de la integración suele aclararse bastante. La parte difícil rara vez es el código puro. Suele ser fiarte del ejemplo correcto, en la superficie correcta y con el modelo correcto antes de que los tutoriales viejos y las señales mezcladas del producto te envíen por un camino más lento.