Cómo usar la API de Nano Banana 2: clave, solicitud y resultado

Para usar la API de Nano Banana 2, crea una clave de API, envía el cuerpo de solicitud generateContent de Google con un campo model a un único endpoint y sondea la tarea que devuelve hasta que la URL de la imagen esté lista. Los mismos pasos sirven para Nano Banana Pro y Nano Banana 2 Lite; solo cambia el valor de model.

Esta guía recorre cada paso con código que funciona y después muestra cómo editar con imágenes de referencia y cómo delegar el trabajo a un agente de programación.

¿Qué necesitas antes de la primera solicitud?

1. Una clave de API. Créala en la página de claves de API y guárdala en tu servidor. Nunca la pongas en código del navegador.
2. Créditos. Añade saldo en la página de facturación. Los créditos nunca caducan y las solicitudes fallidas no se cobran.
3. Un ID de modelo. gemini-3.1-flash-image cobra un precio fijo por imagen; gemini-3.1-flash-image-official factura por tokens. Consulta la guía de precios para elegir.

export SEEDROUTER_API_KEY="your-key"

¿Cómo se envía una solicitud a Nano Banana 2?

Envía la solicitud por POST a /v1/images/generations. El cuerpo tiene la forma generateContent de Google más model:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

La respuesta es una tarea, no una imagen:

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

Si ya llamas a la API de Google, el cuerpo que envías es el mismo que enviarías a generateContent. No se admite llamar directamente a /v1beta/models/...:generateContent en SeedRouter; usa este endpoint.

¿Cómo se obtiene la imagen?

Sondea la tarea cada pocos segundos hasta que status sea completed o failed. En Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Una tarea completada tiene la URL de la imagen en output.data[0].url, junto con el uso de tokens. Con "responseModalities": ["TEXT", "IMAGE"], el texto que escriba el modelo llega en output.text. Descarga la imagen a tu propio almacenamiento si la necesitas a largo plazo.

Que se agote el tiempo de espera al sondear no significa que la imagen haya fallado. Conserva el identificador de tarea y vuelve a consultarla; enviar una solicitud nueva supone pagar una segunda imagen.

¿Cómo se edita una imagen o se usan referencias?

Añade partes fileData junto al texto. Cada una es una URL pública con su tipo MIME:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

Nano Banana 2 acepta hasta 14 referencias por solicitud: imágenes, vídeos o PDF, cada uno de menos de 50 MB. Las referencias deben ser URL; no se acepta inlineData en base64. Si no se puede descargar una URL, la tarea falla y no se cobra. Para una edición posterior, envía los turnos anteriores como entradas user y model y termina con un nuevo turno user.

¿Qué ajustes importan más?

La referencia de la API de Nano Banana 2 enumera cada campo y límite. Los campos desconocidos se rechazan antes de cobrar nada, y el grounding con la Búsqueda de Google (tools) aún no está disponible.

¿Cómo dejas que un agente de programación use la API de Nano Banana 2?

Un agente de programación como Claude Code, Codex o Cursor puede llamar a la API con un comando de shell o un script corto. SeedRouter no ofrece un servidor MCP ni una skill empaquetada; este prompt es toda la integración. Exporta primero la clave y después pega:

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

El paso de aprobación importa: el agente gasta tu saldo, así que nunca debería enviar solicitudes por su cuenta.

Preguntas frecuentes

¿Cómo obtengo una clave de API de Nano Banana 2?

Inicia sesión, abre la página de claves de API y crea una clave. La misma clave sirve para Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite y los demás modelos de SeedRouter.

¿La API de Nano Banana 2 admite solicitudes por lotes?

Envía una solicitud por imagen y sondea las tareas en paralelo. Cada solicitud devuelve una imagen y cada tarea se factura por separado.

¿Qué errores debo gestionar?

Un 400 significa que el cuerpo incumplió una regla, como un campo desconocido o un tamaño no admitido, y no se cobra nada. Una tarea que termina en failed lleva un mensaje de error y tampoco se cobra. La guía de errores enumera cada código y cuándo reintentar.

Envía tu primera solicitud

Crea una clave, añade un saldo pequeño y ejecuta el ejemplo de Python anterior, o prueba la misma solicitud sin código en el playground de Nano Banana 2. Para prompts complejos, cambia el modelo a gemini-3-pro-image para usar Nano Banana Pro.