DEV Community

Cover image for Cómo usar la API Nano Banana 2.1
Roobia
Roobia

Posted on Originally published at apidog.com

Cómo usar la API Nano Banana 2.1

Google lanzó Nano Banana 2.1 el 6 de octubre de 2026. Puedes usarlo mediante la API de Gemini con el ID gemini-nano-banana-2.1. Es una actualización de Nano Banana 2 (Gemini 3.1 Flash Image) con mejor calidad visual, edición estilo máscara y mayor consistencia de personajes entre interacciones. Además, cuesta la mitad por imagen que Nano Banana 2 en las resoluciones que ambos comparten.

Prueba Apidog hoy

Esta guía parte de una terminal vacía y termina con una imagen guardada. También cubre relaciones de aspecto, salida en 2K y 4K, edición, cambios en múltiples turnos, imágenes de referencia, fundamentación con búsqueda y costos. Puedes guardar cada solicitud en Apidog para comparar 2.1 con el modelo que utilizas actualmente.

¿Quieres el contexto primero? Lee Qué es Nano Banana 2.1 para conocer los cambios y lo que Google todavía no ha publicado.

Lo que necesitas

Elemento Valor
URL base https://generativelanguage.googleapis.com/v1beta
Encabezado de autenticación x-goog-api-key: $GEMINI_API_KEY
ID del modelo gemini-nano-banana-2.1
Endpoint POST /v1beta/interactions
Resoluciones 1K (predeterminado), 2K, 4K
Entradas Texto, imágenes (hasta 14 referencias), video
SDK de Python pip install google-genai
SDK de JavaScript npm install @google/genai

Todos los ejemplos usan la API de Interacciones, que es la API usada por la documentación de generación de imágenes de Google para 2.1.

Paso 1: Obtén una clave de API de Gemini

  1. Abre Google AI Studio e inicia sesión.
  2. Ve a Obtener clave de API y crea una clave en un proyecto de Google Cloud.
  3. Activa la facturación para el proyecto. Google lista el nivel gratuito de Nano Banana 2.1 como “No disponible”, por lo que las llamadas a la API requieren un proyecto de pago.
  4. Exporta la clave en tu terminal: 
export GEMINI_API_KEY="your-key-here"
Enter fullscreen mode Exit fullscreen mode

Google vincula 2.1 al entorno de pruebas de AI Studio, útil para probar prompts, pero no ha publicado cuánto puede generar una cuenta gratuita allí. Consulta cómo usar Nano Banana 2.1 gratis para esa ruta y obtener una clave de API de Gemini para una configuración más detallada.

Paso 2: Genera tu primera imagen

curl

Envía un prompt de texto al endpoint de Interacciones:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {
        "type": "text",
        "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

La respuesta es JSON. La imagen llega como datos base64 en un bloque de contenido de imagen, por lo que necesitas un SDK o un script para decodificarla y guardarla.

Python

Instala el SDK:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

Genera y guarda la imagen:

from google import genai
import base64

client = genai.Client()  # Lee GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
Enter fullscreen mode Exit fullscreen mode

interaction.output_image devuelve el último bloque de imagen generado. El campo data está codificado en base64, así que debes decodificarlo antes de escribir el archivo.

JavaScript

Instala el SDK:

npm install @google/genai
Enter fullscreen mode Exit fullscreen mode

Genera y guarda la imagen:

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
});

const image = interaction.output_image;

if (image) {
  fs.writeFileSync("nano-banana.png", Buffer.from(image.data, "base64"));
}
Enter fullscreen mode Exit fullscreen mode

Los modelos de imagen Gemini 3 “piensan” antes de dibujar. El modelo puede producir hasta dos imágenes de pensamiento intermedias mientras planifica la composición. No se te cobra por ellas y este comportamiento no se puede desactivar mediante la API.

Paso 3: Define relación de aspecto, resolución y salida solo de imagen

Usa response_format para controlar la respuesta. Al establecer "type": "image", la API devuelve solo la imagen y omite texto conversacional. Esto reduce el tamaño de la respuesta y simplifica el procesamiento.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A product shot of a matte black coffee grinder on a marble counter",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

Puntos importantes:

  • image_size acepta 1K, 2K y 4K. Usa K mayúscula: valores como 2k son rechazados.
  • Nano Banana 2.1 no ofrece un nivel de 512px. Ese nivel pertenece a Nano Banana 2.
  • Las relaciones de aspecto admitidas incluyen 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 y 8:1.
  • Una imagen 16:9 en 2K mide 2752x1536. En 4K mide 5504x3072.
  • Si necesitas texto e imagen, pasa una lista: 
response_format=[
    {"type": "text"},
    {"type": "image"},
]
Enter fullscreen mode Exit fullscreen mode

Paso 4: Edita una imagen existente

Envía la imagen original como un bloque image codificado en base64 junto con la instrucción de edición.

import base64

with open("living_room.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": (
                "Using the provided image of a living room, change only the blue sofa "
                "to be a vintage, brown leather chesterfield sofa. Keep the rest of "
                "the room, including the pillows on the sofa and the lighting, unchanged."
            ),
        },
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/png",
        },
    ],
)
Enter fullscreen mode Exit fullscreen mode

Inpainting estilo máscara sin archivo de máscara

No existe una carga de máscara independiente. Defines la zona editable mediante texto.

Usando la imagen proporcionada, cambia solo el [elemento específico] a [nuevo elemento/descripción]. Mantén todo lo demás en la imagen exactamente igual, preservando el estilo, la iluminación y la composición originales.

Para reducir cambios no deseados:

  1. Nombra un único elemento.
  2. Describe el reemplazo de forma concreta.
  3. Indica explícitamente qué debe permanecer igual.

Por ejemplo, evita prompts vagos como “haz que el sofá sea más bonito”, ya que pueden provocar que el modelo redibuje gran parte de la habitación.

Paso 5: Itera con edición de múltiples turnos

La edición en múltiples turnos es la forma recomendada por Google para refinar una imagen. Pasa el id de la interacción anterior como previous_interaction_id y envía solamente el siguiente cambio.

interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Update this infographic to be in Spanish. Do not change any other elements of the image.",
    previous_interaction_id=interaction.id,
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

Con REST, el mismo campo se envía en el cuerpo:

{
  "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>"
}
Enter fullscreen mode Exit fullscreen mode

La consistencia mejorada de personajes de 2.1 es especialmente relevante aquí: un personaje o producto debería permanecer reconocible durante varias rondas de edición.

Paso 6: Combina hasta 14 imágenes de referencia

Agrega más bloques image a la lista input. Para 2.1, Google documenta hasta 10 imágenes de objetos de alta fidelidad y hasta 4 imágenes de personajes, con un máximo de 14 referencias.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": "An office group photo of these people, they are making funny faces.",
        },
        {"type": "image", "data": person_1_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_2_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_3_b64, "mime_type": "image/png"},
    ],
    response_format={
        "type": "image",
        "aspect_ratio": "5:4",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

Las imágenes de referencia cuentan como tokens de entrada. La entrada de 2.1 cuesta tres veces más que la de Nano Banana 2, por lo que los flujos con muchas referencias reducen la diferencia de precio. Mide el uso antes de migrar.

Paso 7: Fundamenta imágenes con la Búsqueda de Google

Para imágenes basadas en datos actuales, como un mapa del tiempo o un evento reciente, agrega la herramienta de búsqueda.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A detailed painting of a Timareta butterfly resting on a flower",
    tools=[
        {
            "type": "google_search",
            "search_types": ["web_search", "image_search"],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Usar solo {"type": "google_search"} habilita la búsqueda web. Agregar image_search permite al modelo usar imágenes web como contexto visual; esta capacidad solo está disponible en 2.1 y Nano Banana 2.

La fundamentación no puede usar imágenes de personas reales obtenidas de la búsqueda. Si muestras resultados fundamentados a usuarios finales, Google exige mostrar las search_suggestions devueltas en el paso google_search_result.

Paso 8: Pruébalo en Apidog

Los scripts son útiles para automatizar generación. Para validar rápidamente que un prompt, una clave y un modelo siguen funcionando, guarda la solicitud en Apidog.

  1. Crea un entorno y agrega una variable GEMINI_API_KEY con tu clave.
  2. Crea una solicitud: 
   POST https://generativelanguage.googleapis.com/v1beta/interactions
Enter fullscreen mode Exit fullscreen mode
  1. Agrega el encabezado: 
   x-goog-api-key: {{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode
  1. Pega un cuerpo JSON con model, input y response_format.
  2. Envía la solicitud.
  3. Agrega un script post-respuesta con estas aserciones: 
pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("response contains an image block", () => {
  const steps = pm.response.json().steps || [];

  const hasImage = steps.some(
    (s) =>
      s.type === "model_output" &&
      (s.content || []).some((c) => c.type === "image" && c.data)
  );

  pm.expect(hasImage).to.be.true;
});
Enter fullscreen mode Exit fullscreen mode
  1. Duplica la solicitud y cambia model a gemini-3.1-flash-image.
  2. Ejecuta ambas solicitudes con el mismo prompt.

Así tendrás una comparación lado a lado de Nano Banana 2.1 y Nano Banana 2, con estado, tiempo y tamaño de respuesta para cada ejecución. Para comparar más características, consulta Nano Banana 2.1 vs Nano Banana 2 vs Pro.

Lo que cuesta

Nivel de pago, según la página de precios de Google el 7 de octubre de 2026:

Modelo Entrada / 1M Imagen 1K Imagen 2K Imagen 4K Lote 1K
Nano Banana 2.1 $1.50 $0.0336 $0.0504 $0.0756 $0.0168
Nano Banana 2 $0.50 $0.067 $0.101 $0.151 $0.034
Nano Banana Pro $2.00 $0.134 $0.134 $0.24 $0.067

La salida de imagen para 2.1 cuesta $30 por 1 millón de tokens:

  • Una imagen 1K usa 1,120 tokens.
  • Una imagen 2K usa 1,680 tokens.
  • Una imagen 4K usa 2,520 tokens.

La salida de texto y “pensamiento” cuesta $7.50 por 1 millón de tokens. La fundamentación de búsqueda incluye 5,000 solicitudes gratuitas al mes, compartidas entre los modelos Gemini 3.x. Después cuesta $14 por cada 1,000 solicitudes.

Ejemplo práctico

Supón que generas 1,000 imágenes de productos en 2K desde prompts cortos de aproximadamente 100 tokens de entrada cada uno:

  • Salida: 1,000 x $0.0504 = $50.40
  • Entrada: 100,000 tokens x $1.50 / 1M = $0.15
  • Total aproximado: $50.55, más cualquier token de texto de “pensamiento”

El mismo trabajo en Nano Banana 2 cuesta aproximadamente $101.

Con la API por lotes, el precio de 2K para 2.1 baja a $0.0252. El costo de salida se reduce a $25.20 si puedes esperar. Los trabajos por lotes intercambian un tiempo de respuesta de hasta 24 horas por límites de tasa más altos.

Consulta el desglose de precios de la API de Nano Banana 2 para más detalles.

Errores comunes

Estos son comportamientos generales de la API de Gemini, no errores específicos de 2.1 documentados.

Error Causa probable Solución
400 INVALID_ARGUMENT image_size en minúsculas, relación no admitida o input mal formado Usa 2K, no 2k; verifica la lista de relaciones y la estructura del cuerpo
403 PERMISSION_DENIED Clave incorrecta o proyecto sin facturación Verifica la clave y habilita la facturación
404 NOT_FOUND Error tipográfico en el ID del modelo Usa exactamente gemini-nano-banana-2.1
429 RESOURCE_EXHAUSTED Límite de tasa alcanzado Espera y reintenta, o usa lotes
500 / 503 Problema temporal del servidor Reintenta con retroceso exponencial
200 pero sin imagen Prompt bloqueado o respuesta solo de texto Establece "type": "image" y reformula el prompt

Preguntas frecuentes

  • ¿Existe un nivel gratuito para la API de Nano Banana 2.1?

    No. Google lista el nivel gratuito de la API como “No disponible”. El entorno de pruebas de AI Studio está vinculado a 2.1, pero Google no ha publicado un límite gratuito para él.

  • ¿Es 2.1 un reemplazo directo para Nano Banana 2?

    Mayormente. Cambia el ID del modelo a gemini-nano-banana-2.1. Pierdes el nivel de 512px y los tokens de entrada cuestan más, por lo que debes verificar el costo de ediciones con muchas referencias.

  • ¿Las imágenes generadas llevan una marca de agua?

    Sí. Todas las salidas incluyen una marca de agua SynthID.

  • ¿Puedo generar una imagen a partir de un video?

    Sí. 2.1 acepta un bloque de entrada video, como una URL de YouTube, junto con el prompt de texto.

  • ¿La guía anterior de la API de Nano Banana 2 sigue siendo aplicable?

    Los conceptos siguen siendo aplicables. Consulta la guía de la API de Nano Banana 2 para el modelo anterior.

Resumen

Nano Banana 2.1 promete mejores imágenes a la mitad del precio por imagen de Nano Banana 2, manteniendo la misma estructura de la API de Interacciones. Obtén una clave con facturación, genera una imagen y guarda la solicitud en Apidog con aserciones de estado e imagen.

Después, duplica la solicitud con el ID del modelo anterior. En una tarde podrás comprobar si Nano Banana 2.1 justifica el cambio para tus prompts.

Top comments (0)