Cómo usar Nano-Banana-2-Lite a través de la API de HiAPI: curl, Python y una solicitud funcional

Qué es Nano-Banana-2-Lite y cuándo usarlo

Nano-Banana-2-Lite es el nivel de ultra bajo coste dentro de la familia Nano-Banana en HiAPI. Está orientado a escenarios de generación de imágenes de alta concurrencia y sensibles al coste, donde valoras más la previsibilidad del gasto y la iteración rápida que la máxima fidelidad. Si estás prototipando una función, generando miniaturas o variantes en lote, o ejecutando tareas en segundo plano que toleran un modelo más ligero, este nivel es el punto de partida adecuado.

Úsalo cuando el resultado sea solo una pieza de un flujo mayor: visuales de borrador, imágenes de marcador de posición, experimentos por lotes o pruebas A/B que necesitan muchas candidatas a bajo coste. Para los materiales principales finales, o escenarios que requieren el máximo detalle, pasa a un nivel superior. La interfaz de la API se mantiene igual, así que no necesitas reescribir tu integración para cambiar de modelo.

Requisitos previos y estructura de la solicitud

Antes de llamar a Nano-Banana-2-Lite, asegúrate de contar con:

• Una cuenta de HiAPI y una clave de API. Guárdala en una variable de entorno, por ejemplo HIAPI_API_KEY; nunca la confirmes en el control de código fuente.
• Una terminal con curl para la primera prueba, y Python 3.8+ con la biblioteca requests para la versión en script.
• Un prompt que describa la imagen que deseas. Empieza simple; después puedes añadir entradas de referencia.

Cada solicitud a HiAPI sigue la misma estructura: envía un POST con un cuerpo JSON al endpoint del modelo. El cuerpo lleva el nombre del modelo, el prompt y cualquier parámetro opcional. Como la generación es asíncrona, la llamada de envío devuelve un identificador de tarea y luego consultas esa tarea. La respuesta es JSON, y los errores incluyen un código de estado y un mensaje que puedes registrar.

Tu carga útil necesita como mínimo model establecido en nano-banana-2-lite y un prompt. Los campos opcionales como reference_images y la configuración de salida se tratan en las secciones siguientes.

Una solicitud curl funcional

A continuación tienes un ejemplo completo y listo para copiar y llamar, que envía una tarea básica. Sustituye el prompt de marcador de posición por el tuyo.

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

La respuesta contiene el id de la tarea y un campo status. Las tareas recién enviadas suelen devolver queued o processing. Guarda ese id; lo usarás en el paso de consulta. Si recibes 401, comprueba si HIAPI_API_KEY se exportó en tu shell. Si recibes 422, revisa el mensaje de error para localizar el campo problemático.

Enviar la misma solicitud con Python

Traslada la llamada curl a Python para poder integrarla en un script o servicio. Este ejemplo usa requests y lee la clave desde una variable de entorno.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Mantén el cuerpo de la solicitud en un diccionario para poder ampliarlo con campos opcionales sin reescribir la llamada. Para el paso de envío, un tiempo de espera de 30 segundos es razonable, ya que el trabajo pesado ocurre de forma asíncrona.

Añadir entradas de referencia opcionales

Las entradas de referencia te permiten guiar la generación con contexto visual. En HiAPI las adjuntas como un array reference_images dentro del mismo cuerpo JSON. Cada elemento es una URL de acceso público o un URI de datos base64. Usa imágenes de referencia cuando quieras conservar la composición, igualar un estilo o mantener coherente una imagen de producto entre varias variantes.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Incluye referencias solo cuando aporten una señal útil. Cada referencia son datos adicionales que hay que transmitir y puede diluir un prompt sencillo. Para tareas directas de texto a imagen, omite el campo por completo. Cuando sí uses referencias, mantenlas relevantes y pocas; una o dos imágenes bien elegidas suelen superar a un conjunto grande.

Consultar el resultado asíncrono

La generación de imágenes es asíncrona: envías la tarea y luego consultas el endpoint de la tarea hasta que el estado sea terminal. El patrón es el mismo en curl y en Python.

Con curl, consulta la tarea por su id:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

En Python, envuelve la consulta en un bucle con retardo para no golpear la API con demasiada frecuencia:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Empieza con un intervalo corto y aplica un retroceso progresivo si consultas muchas tareas. Establece siempre un número máximo de intentos para que una tarea atascada no bloquee indefinidamente tu proceso de trabajo. Trata failed como estado terminal y registra el mensaje de error.

Descargar y verificar el resultado

Cuando la tarea tiene éxito, la respuesta contiene una o más URL de salida. Obtén el archivo, guárdalo localmente y luego verifica lo que has recibido.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Haz comprobaciones básicas sobre lo descargado: confirma que el tipo de contenido es una imagen, verifica que el tamaño del archivo no sea cero y sea razonable, y ábrelo una vez para confirmar que coincide con tu prompt. Registra el id de la tarea junto con el nombre del archivo local para poder rastrear cualquier material hasta su solicitud.

Lista de comprobación de costes y fallos antes de producción

Nano-Banana-2-Lite tiene el precio del nivel de ultra bajo coste; la facturación sigue la medición estándar de generación de imágenes de la plataforma. Consulta el panel de precios actual del sitio web para obtener las tarifas exactas, en lugar de codificar suposiciones fijas.

Antes de lanzar a producción, adopta estos hábitos:

• Reintentos con retroceso progresivo. Reintenta errores transitorios (tiempos de espera, 5xx) un número pequeño de veces con un retardo creciente; no reintentes errores de validación 4xx.
• Limita las consultas. Usa un intervalo fijo y un número máximo de intentos. Registra el estado final y el tiempo transcurrido.
• Registra el id de la tarea y el prompt. Guarda el id de la tarea, el prompt, el modelo y cualquier entrada de referencia junto con cada salida, para poder reproducir o auditar las ejecuciones.
• Valida las entradas pronto. Comprueba la longitud del prompt y las URL de referencia antes de enviar, para evitar desperdiciar tareas.

Con estas comprobaciones, Nano-Banana-2-Lite es un caballo de batalla predecible y de bajo coste para generación por lotes y en segundo plano. Explora la página del modelo en HiAPI para conocer los parámetros y tarifas más recientes.