Cómo usar la API de Nano Banana 2 Lite: curl, Python y una solicitud ejecutable

Nano-Banana-2-Lite es la opción económica de la familia de modelos de imagen Nano-Banana en hiapi: usa el mismo workflow basado en tareas que sus hermanos mayores, tiene un precio por imagen más bajo y admite tanto generación de texto a imagen como edición con imágenes de referencia. Esta guía te lleva por un flujo de integración completo y ejecutable —crear la tarea, consultar la tarea, descargar el resultado— con ejemplos en curl y Python, y explica los detalles de schema en los que se diferencia de Nano-Banana-2 y Nano-Banana-Pro.

Qué vas a construir y qué necesitas preparar

Objetivo: enviar un prompt a Nano-Banana-2-Lite, esperar a que se genere la imagen y guardarla en disco.

Solo necesitas una cosa: una API key de hiapi (sk-...). Obténla desde tu hiapi dashboard. El costo por imagen aparece en la pricing page y en la página del modelo Nano Banana 2 Lite.

Todos los modelos de imagen en hiapi funcionan a través de una API de tareas asíncrona unificada: creas una tarea con POST /v1/tasks y luego consultas GET /v1/tasks/{id} o recibes un webhook cuando la tarea termina.

Solicitud mínima ejecutable (curl)

Crear la tarea:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "Una ilustración en acuarela de un faro al amanecer, paleta de tonos pastel suaves",
      "aspect_ratio": "3:2"
    }
  }'

El id de la tarea en la respuesta está en data.taskId. Consúltalo:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Cuando data.status sea "success", la URL de la imagen está en data.output[0].url. Descárgala de inmediato — las URL de salida están firmadas y tienen expiración (expireAt), así que guarda los bytes, no el enlace.

Dos reglas de schema que suelen causar problemas, tomadas directamente de la validación de la propia API:

• El id del modelo distingue mayúsculas y minúsculas. "model": "nano-banana-2-lite" devuelve 400 MODEL_UNAVAILABLE ("model not available via /v1/tasks"). Usa el id exacto Nano-Banana-2-Lite.
• prompt y aspect_ratio son obligatorios. Omitir cualquiera de los dos devuelve 400 INVALID_REQUEST con el mensaje missing required field. Valores válidos de aspect_ratio: auto, 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, 8:1.

El mismo flujo en Python

No se necesita SDK — la API de tareas es JSON puro sobre HTTPS:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Crear la tarea
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "Una ilustración en acuarela de un faro al amanecer, paleta de tonos pastel suaves",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Consultar hasta que la tarea alcance un estado terminal
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Descargar de inmediato — las URL de salida están firmadas y expiran
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Edición con imágenes de referencia: image_urls, no image_input

Nano-Banana-2-Lite admite edición de imágenes, pero su campo de imágenes de referencia es image_urls — un array de hasta 10 URL accesibles públicamente:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Reemplaza el fondo por un fondo de estudio blanco limpio, mantén el producto sin cambios",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

Este es el error más común de la familia: Nano-Banana-2 y Nano-Banana-Pro usan image_input para el mismo propósito, mientras que Lite rechaza ese campo (additional properties 'image_input' not allowed). Nombres de campo como input_urls, images o reference_images se rechazan en los tres modelos. Si migras código entre niveles, normalmente el único cambio necesario es renombrar este campo.

Lite vs. Nano-Banana-2 vs. Pro: diferencias de schema importantes

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Entradas obligatorias	prompt, aspect_ratio	prompt	prompt
Imágenes de referencia	image_urls (≤10)	image_input	image_input
Control de resolution	No aceptado	Aceptado	Aceptado

Lite mantiene una superficie de interfaz mínima: prompt, relación de aspecto, imágenes de referencia opcionales. No hay resolution, seed, n ni negative_prompt — enviar cualquiera de ellos falla la validación con additional properties ... not allowed. Si necesitas control explícito de resolución (1K/2K/4K) o un nivel de mayor fidelidad, sube a Nano-Banana-2 o Nano-Banana-Pro; si generas en lote —miniaturas, borradores, ciclos iterativos, variantes masivas— el menor costo por imagen de Lite es precisamente su razón de ser.

Refuerzo para producción

Usa webhooks en lugar de sondeo cuando sea posible. Añade un bloque callback al crear la tarea y hiapi hará POST del resultado final a tu endpoint:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when solo acepta "final" — recibirás un único callback, ya sea de éxito o de fallo. El sondeo es adecuado para scripts y notebooks; los callbacks son mejores para servidores porque te evitan gestionar bucles de sondeo y tiempos de espera. Si de verdad vas a sondear, un intervalo de 2–5 segundos con una fecha límite estricta (como en el ejemplo de Python) es suficiente.

Gestiona errores en dos niveles. Los fallos a nivel de solicitud se devuelven como errores HTTP — una key inválida o no autorizada devuelve 401 con {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, y los errores de schema devuelven 400 INVALID_REQUEST con el mensaje de validación exacto. Los fallos a nivel de tarea llegan con status: "fail" y un objeto error en la propia tarea; maneja ambas rutas en tu código.

Haz que los reintentos sean idempotentes. La creación de tareas no es idempotente — reintentar una solicitud de creación que se agotó puede producir dos tareas (y dos cobros). Persiste el taskId en cuanto lo recibas, y tras un reinicio continúa consultando el id existente en lugar de recrear a ciegas.

Guarda los bytes, no las URL. Las URL de salida expiran. Descarga la imagen a tu propio almacenamiento antes de hacer cualquier otra cosa con ella.

Lecturas relacionadas

• Página del modelo Nano Banana 2 Lite — parámetros, precios en vivo, playground
• GPT Image 2 vs Nano Banana 2: comparación lado a lado con el mismo prompt
• Mantener la consistencia de personajes con Nano-Banana en hiapi
• Documentación de hiapi y precios

Preguntas frecuentes

¿Por qué recibo "model not available via /v1/tasks"? El id del modelo distingue mayúsculas y minúsculas. Usa exactamente Nano-Banana-2-Lite; las variantes en minúsculas se rechazan con 400 MODEL_UNAVAILABLE.

¿Nano-Banana-2-Lite admite edición de imagen a imagen? Sí. Pasa las imágenes de referencia en el array image_urls (hasta 10 URL). Puede manejar reemplazo de fondo, transferencia de estilo y flujos de edición guiados por instrucciones a partir del prompt.

¿Por qué mi código de Nano-Banana-2 falla en Lite con "additional properties 'image_input' not allowed"? Los distintos niveles usan nombres de campo diferentes para las imágenes de referencia: Lite espera image_urls, mientras que Nano-Banana-2 y Pro esperan image_input. Renombra el campo al cambiar de nivel.

¿Puedo establecer resolution, seed o la cantidad de imágenes? En Lite no — su schema de entrada solo acepta prompt, aspect_ratio e image_urls. Para tener control de resolution en 1K/2K/4K, usa Nano-Banana-2 o Nano-Banana-Pro.

¿Cuánto tiempo son válidas las URL de las imágenes de salida? Son URL firmadas con marca de tiempo de expiración (expireAt en el objeto de salida). Descarga los bytes de inmediato y guárdalos en tu propio almacenamiento; nunca hagas hotlinking de la salida de una tarea.

¿Qué significa 401 permission_denied? Tu API key no es válida o no tiene permiso para usar este modelo. Revisa la key en tu dashboard y asegúrate de enviarla como Authorization: Bearer sk-....

¿Cuánto cuesta cada imagen de Nano-Banana-2-Lite? Se factura por uso, por imagen, y está posicionado como el nivel de menor costo de la familia Nano-Banana. Consulta las tarifas actuales en la pricing page.