¿Cómo usar la API de Nano Banana 2? Genera tu primera imagen en 5 minutos

TL;DR

• Qué es: Nano Banana 2, de Google, usa un único ID de modelo nano-banana-2 tanto para texto a imagen como para edición con imágenes de referencia, con hasta 14 imágenes de referencia por solicitud. Ya está disponible en HiAPI: abre la página del modelo, escribe un prompt y genera; los nuevos usuarios reciben 200 créditos al registrarse.
• Cuánto cuesta: se cobra por imagen: 1K $0.036, 2K $0.057, 4K $0.086; las imágenes de referencia no tienen costo adicional y los fallos se reembolsan automáticamente.
• Cómo llamar a la API: POST https://api.hiapi.ai/v1/tasks, con model establecido en nano-banana-2; obtén el taskId y luego consulta o espera el callback, y descarga data.output[0].url.

¿Qué puede hacer Nano Banana 2?

• Un modelo, dos usos. Si solo das un prompt, es texto a imagen; si añades image_input, se convierte en edición con imágenes de referencia, sin cambiar de endpoint ni de modo.
• Hasta 14 imágenes de referencia por solicitud. Puedes enviar juntas varias vistas de un producto, imágenes de modelo y de escenario; ideal para cambiar el escenario de un mismo producto, cambiar la ropa y crear conjuntos de imágenes de marca.
• 14 relaciones de aspecto fijas más auto. Además de las habituales 1:1, 4:5, 16:9 y 21:9, también hay 1:4, 4:1, 1:8 y 8:1; si no estás seguro, usa el valor predeterminado auto.
• Tres niveles: 1K, 2K y 4K. Usa 1K para probar prompts y 2K o 4K para las imágenes finales; la salida predeterminada es PNG.

La siguiente es una imagen de ejemplo de la página del modelo Nano Banana 2, generada en 4:3 y 1K:

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

Generar con este prompt →

Dos rutas para empezar: ¿prueba en línea o API?

Si primero quieres ver el resultado, elige la prueba en línea; si vas a integrarlo en tu producto, elige la API. Ambas rutas usan el mismo modelo y los mismos precios.

Prueba en línea (unos 1 minuto)

1. Abre la página del modelo Nano Banana 2, o haz clic directamente en el enlace debajo de la imagen anterior; el prompt se rellenará automáticamente.
2. Regístrate o inicia sesión; las cuentas nuevas incluyen 200 créditos.
3. Elige la relación de aspecto y la resolución; a precio normal, una imagen 1K cuesta 72 créditos.
4. Haz clic en generar y, si te gusta el resultado, descárgalo.

Conexión a la API (unos 5 minutos)

1. Crea una API Key (sk-...) en la consola de HiAPI.
2. Haz POST /v1/tasks para crear una tarea y obtén data.taskId en la respuesta.
3. Consulta con GET /v1/tasks/{id}, o incluye callback.url en el cuerpo de la solicitud y espera la notificación.
4. Cuando data.status pase a success, descarga la imagen desde data.output[0].url.

Una imagen 1K cuesta $0.036; con $10 puedes generar unas 277 imágenes, suficiente para ajustar bien los prompts. Consulta todos los parámetros en la documentación en chino.

La primera imagen: versión curl

Crear la tarea:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

El ID de tarea devuelto está en data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consultar el resultado:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

El único campo obligatorio es prompt. aspect_ratio es auto por defecto, resolution es 1K por defecto y output_format es png por defecto (también puedes usar jpg).

La primera imagen: versión Python

Primero instala requests (python3 -m pip install requests) y define HIAPI_API_KEY en la terminal (export HIAPI_API_KEY="sk-YOUR_KEY"). El siguiente ejemplo crea una tarea, consulta su estado durante un máximo de 10 minutos y luego descarga la imagen; si se agota el tiempo, conserva el taskId para seguir consultando:

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Edición con imágenes de referencia: basta con añadir image_input

Añade image_input dentro de input y la misma solicitud se convierte en una edición. A continuación se coloca la imagen de un frasco de sérum sobre fondo blanco en una encimera de baño:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input es un array de URL, con un máximo de 14, y deben ser enlaces de imagen accesibles públicamente de forma directa; no se admite SVG. Si en el prompt indicas claramente "qué conservar" (this exact serum bottle, unchanged), la etiqueta del producto y la forma del frasco se mantendrán con mayor estabilidad. Encontrarás el prompt completo y las imágenes resultantes de este mismo producto con cambio de escenario en la guía completa de prompts de Nano Banana 2.

3 cosas que tener en cuenta antes de lanzar

1. Usa callbacks en el servidor. Añade en el nivel superior del cuerpo de la solicitud "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; la tarea notificará automáticamente al terminar, tanto si tiene éxito como si falla; deduplica por taskId.
2. Incluye una clave de idempotencia al reintentar. Cada POST /v1/tasks crea por defecto una nueva tarea y se cobra por separado. Añade la cabecera Idempotency-Key, genera y guarda una clave para la misma tarea de negocio, y si hay un tiempo de espera de red, reintenta con la misma cuenta, la misma clave y exactamente el mismo cuerpo de solicitud; así solo se creará una tarea.
3. Descarga el resultado en cuanto lo obtengas. Los enlaces de salida tienen una validez limitada; guarda primero la imagen en tu propio almacenamiento y luego procesa lo demás.

Errores comunes, uno por línea

• 400 additional properties ... not allowed → nombre de campo mal escrito, o uso de campos de otro modelo (por ejemplo, image_urls de Nano Banana 2 Lite, o size) → cámbialo a image_input, resolution.
• 400, valor de aspect_ratio incorrecto → se envió una relación de aspecto fuera de la lista → elige uno de los 15 valores válidos.
• 401 permission_denied → falta la Key, está mal escrita o ha sido revocada → revisa la cabecera Authorization: Bearer sk-... y, si es necesario, vuelve a crearla en la consola.
• 402 → saldo insuficiente; la tarea no se creó y no se cobró → recarga y vuelve a intentarlo.
• El status de la tarea es fail → corrige la solicitud según el error devuelto; no la reintentes tal cual; el importe preautorizado se reembolsará automáticamente en su totalidad.

Preguntas frecuentes

¿Cómo se escribe el ID del modelo? Escribe nano-banana-2. Los nombres de los parámetros son exactamente iguales que en Nano Banana 2.1; cambia a gemini-nano-banana-2.1 para usar la 2.1.

¿Las imágenes de referencia tienen costo adicional? No. El precio solo depende de la resolución de salida; es igual si envías 1 o 14 imágenes de referencia.

¿Cuántas imágenes se generan por solicitud? Una tarea genera una imagen. Si necesitas varias, crea varias tareas en paralelo; se cobra por imagen.

¿Cómo obtener el precio promocional por tiempo limitado? No hace falta cambiar el código. El 50 % de descuento por el Día del Programador estará vigente hasta las 00:00 (hora de Pekín) del 2026-11-09; tanto la API como la prueba en línea aplican automáticamente el 50 % de descuento, y una imagen 1K cuesta $0.018.

Artículos de la serie Nano Banana 2

• Página del modelo Nano Banana 2: generación en línea, 200 créditos de regalo al registrarte
• Cuánto cuesta la API de Nano Banana 2: precio unitario 1K/2K/4K y presupuesto mensual
• GPT Image 2.5 vs Nano Banana 2: comparación de 9 imágenes con el mismo prompt
• Guía completa de prompts de Nano Banana 2: 5 escenarios para copiar y generar directamente
• Precio de la API de Nano Banana 2.1: cuánto más barato que NB 2
• Precio de la API de Nano Banana Pro: cuánto cuesta cada imagen
• Documentación de integración en chino de Nano Banana 2: todos los parámetros

Pruébalo ahora: haz clic en Generar con este prompt → debajo de la imagen de la selva tropical de arriba; el prompt ya está rellenado, elige la relación 4:3 y resolución 1K, ejecuta y descarga el resultado; a precio normal cuesta $0.036 por imagen.