Blog

Tutorial

Cómo usar nano-banana-2 a través de la API de HiAPI: ejemplos disponibles de curl y Python Requests

Una guía para desarrolladores sobre cómo integrar nano-banana-2 en un pipeline de generación de imágenes

Nov 12, 2026
Imagen de portada minimalista: sobre un fondo de color arena cálido, franjas escalonadas horizontales en tono terracota y marrón se disponen escalonadamente hacia abajo como en un gráfico de columnas de mercurio.
En esta página

Qué puede hacer nano-banana-2 por ti y cuándo deberías usarlo

nano-banana-2 es un modelo de generación de imágenes al que se accede mediante una API HTTP. Envías un prompt, opcionalmente acompañas una imagen de origen, y recibes una imagen generada. Ese es todo el modelo mental que necesitas antes de escribir código.

Deberías usar nano-banana-2 cuando necesites generar imágenes de forma programática dentro de un producto o pipeline existente, en lugar de hacerlo a través de una ventana de chat: generación de materiales de marketing, creación de miniaturas y portadas, modificaciones iterativas basadas en una imagen de fondo, o tareas de procesamiento por lotes en las que la cantidad de imágenes la determina tu propio conjunto de datos. Como su interfaz es una API normal de solicitud/respuesta, puedes colocarla detrás de un worker de cola, un endpoint de backend o una herramienta CLI, sin necesidad de introducir un nuevo SDK para cada lenguaje.

Dos modos cubren la mayoría de los casos de uso:

  • Texto a imagen — describes con un prompt lo que quieres y obtienes una imagen.
  • Imagen a imagen — proporcionas una imagen de origen, añades un prompt que describe la transformación y recibes la imagen modificada.

La forma de la solicitud es idéntica en ambos modos, por lo que un único wrapper de cliente (que construirás más adelante en este artículo) puede manejar los dos. Si tu pipeline solo renderiza a partir de texto, puedes ignorar por completo el campo image. Si tu pipeline trata sobre editar material existente, entonces imagen a imagen es tu punto de entrada.

Lo que nano-banana-2 no hace por ti: no gestiona tus reintentos, tiempos de espera, almacenamiento ni idempotencia. Esas son las partes que construyes alrededor de la llamada, y en eso se centra la mayor parte del resto de este tutorial, porque llamar ingenuamente a requests.post dentro de un bucle es la causa más común de «la demo funciona, pero en producción no».

Antes de enviar tu primera solicitud

Antes de la primera llamada necesitas tener listas tres cosas.

1. Credenciales de la plataforma

Necesitas obtener acceso a la API desde la plataforma HiAPI, así como las credenciales asignadas a tu cuenta. Trátalas como secretas: cárgalas desde variables de entorno o un gestor de secretos, nunca las confirmes en el repositorio de código y nunca las pegues en artefactos empaquetados del cliente. Cada solicitud a continuación lee la clave desde una variable de entorno, de modo que no aparece ninguna información sensible en el código fuente.

export HIAPI_API_KEY="your-key-here"

2. Entorno del cliente

Si usas curl, solo necesitas un shell capaz de ejecutar curl; los ejemplos usan parámetros incluidos en la compilación estándar. Si usas Python, necesitas Python 3 y la biblioteca requests:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. Un lugar donde guardar la salida

La generación de imágenes devuelve datos de imagen; si se devuelven en línea en la respuesta o como una referencia que se puede obtener después depende de la forma de respuesta que devuelva tu cuenta. Decide de antemano si vas a guardar los bytes en disco, subirlos a un almacenamiento de objetos o devolver una URL a quien llama. Pensar en esto ahora evita el clásico momento incómodo de «funciona en el shell, pero no tengo dónde poner el archivo».

Para empezar no necesitas estimar cuotas ni precios. El principio general para una primera integración es: envía la solicitud válida más pequeña, confirma que obtienes una respuesta válida y luego añade parámetros. La siguiente sección hace exactamente eso.

Una solicitud curl mínima que funciona

A continuación tienes una llamada completa de texto a imagen. El endpoint, las cabeceras y el cuerpo son las únicas partes variables: el endpoint identifica el modelo y la operación en la plataforma HiAPI, las cabeceras llevan tus credenciales y el cuerpo JSON lleva la carga útil.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

Configura HIAPI_BASE_URL con la dirección base de la API que se muestra en el panel de tu cuenta de HiAPI, para no codificar el nombre del host directamente en el script. El cuerpo tiene tres campos y los tres importan:

  • model indica a la plataforma qué modelo ejecutar. Mantenlo explícito aunque uses un valor predeterminado en otro lugar; hace que los registros hablen por sí solos.
  • prompt es lenguaje natural. Describe con precisión el sujeto, la composición y el estilo; los prompts vagos producen imágenes vagas.
  • n es la cantidad de imágenes solicitadas para este prompt. Empieza con 1 al verificar que la conexión funciona.

Una respuesta correcta devuelve los datos de la imagen en el cuerpo de la respuesta. Inspecciónala antes de escribir cualquier parser: pasa la salida por jq o redirígela a un archivo y luego mira las claves de nivel superior. Estás confirmando dos cosas: que la solicitud fue aceptada y dónde está realmente la carga útil de la imagen dentro de la respuesta.

No te apresures a añadir parámetros en la primera llamada. Una línea base funcional que entiendes vale más que un cuerpo de solicitud enorme que copiaste. Una vez que esta llamada devuelva una imagen, cada sección posterior será una variante de ella.

La misma solicitud, escrita en Python

Porta la llamada curl a Python sin cambiar la carga útil. Mantener una única fuente de verdad (un dict) significa que el cuerpo que validaste en el shell es el mismo cuerpo que finalmente pones en producción.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """Envía una solicitud de texto a imagen y devuelve la respuesta JSON parseada."""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

Hay tres detalles que vale la pena destacar, porque son las partes que más se pasan por alto cuando se copia un fragmento de código.

Configura siempre timeout. Si no lo haces, una conexión bloqueada bloqueará tu worker de forma indefinida. El valor anterior es solo un punto de partida, no una regla fija; ajústalo según la latencia que observes realmente.

Usa json= en lugar de data=. Pasar el dict a json establece correctamente el tipo de contenido y serializa; pasar una cadena sin procesar a data es exactamente la causa de los errores de formato del cuerpo que parecen fallos del modelo.

Llama a raise_for_status() antes de parsear. Intentar parsear una respuesta 4xx con .json() para extraer campos de imagen produce errores posteriores confusos. Expón primero el código de estado HTTP.

Esta función es el wrapper reutilizable mencionado antes. La siguiente sección ampliará su carga útil en lugar de reemplazarla.

Cargas útiles de texto a imagen e imagen a imagen

La diferencia entre ambos modos es solo una: si el cuerpo de la solicitud incluye o no una imagen de origen. Todo lo demás —el endpoint, la cabecera de autenticación, el nombre del modelo— permanece igual.

Texto a imagen

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

Imagen a imagen

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

El concepto que debes interiorizar: en el modo imagen a imagen, el prompt describe la transformación, no la escena completa desde cero. «Convertir a una paleta cálida de atardecer» funciona mejor que volver a describir toda la imagen, porque la imagen de origen ya aporta el contenido.

Dos notas prácticas sobre el campo image:

  • Codifica la imagen de origen según el formato que la documentación de la API indique para ese campo, y mantén la carga útil codificada muy por debajo de tu presupuesto de tamaño de solicitud. Las entradas demasiado grandes son una de las principales causas de rechazo de solicitudes.
  • Si vas a aceptar cargas de usuarios, valida el tamaño y el formato antes de codificar. Fallar rápido de tu lado es mucho más barato que un ciclo de ida y vuelta que termina en un 4xx.

Añade un parámetro opcional image al wrapper de Python, y una sola función podrá servir a ambos modos:

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... la misma llamada de solicitud que antes

Como la rama es solo un if, tu código de llamada decide el modo mientras la capa de transporte permanece igual. Ese es el beneficio de mantener un único wrapper.

Gestionar tareas asíncronas y reintentos

La generación de imágenes puede tardar más que una llamada típica a una API JSON. Algunas respuestas devuelven la imagen terminada de inmediato; otras devuelven una tarea que debes consultar repetidamente para obtener el resultado. Incluso si tu primera llamada exitosa devuelve el resultado de inmediato, diseña para el escenario de sondeo; de lo contrario, tu pipeline se romperá cuando alguna generación tarde demasiado.

Un patrón robusto consta de tres partes: un bucle de sondeo con retroceso, una fecha límite estricta y una política de reintentos que distinga entre «aún no está listo» y «falló».

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

La ruta de la tarea y el vocabulario de estados deben coincidir con lo que especifique la referencia de API de tu cuenta de HiAPI; ajusta las claves anteriores a la forma correspondiente, pero conserva la estructura.

Reglas para mantenerlo saludable en producción:

  • Retroceso exponencial con límite superior. Sondear cada 200 ms desperdicia cuota y satura el endpoint; duplicar el tiempo de espera con un límite superior se estabiliza cerca del tiempo real de finalización.
  • Limita el número total de intentos y el tiempo total. El deadline no es negociable. Un bucle sin límites es esperar a que un día lento provoque una caída.
  • Reintenta solo errores reintentables. Los errores de red transitorios y las respuestas 5xx merecen un nuevo intento con jitter; las respuestas 4xx no, ya que reenviar una carga útil mal formada solo hace perder tiempo. Usa un número pequeño y acotado de reintentos (dos o tres) y registra cada uno.
  • Haz que los reintentos sean seguros. Si tu endpoint de creación de tareas acepta claves de idempotencia, envía una clave estable por cada solicitud lógica, para que un reenvío de reintento no produzca generaciones duplicadas.

Con una fecha límite, retroceso y un número acotado de reintentos, una generación lenta se convierte en un evento registrado y gestionado, en lugar de un worker colgado.

Depurar los errores que realmente encontrarás

Cuando una llamada falla, lee primero el código de estado sin procesar y el cuerpo completo de la respuesta antes de tocar cualquier parámetro del modelo. El cuerpo de la respuesta suele indicar el problema. Adivinar es más lento que registrar.

Fallos de autenticación

Un 401 o 403 casi siempre significa una de las siguientes cosas: falta la clave en la variable de entorno, el formato de la cabecera es incorrecto o las credenciales no están activas en este entorno. Revisa el valor literal de la cabecera que realmente envías; la falta del prefijo Bearer o un salto de línea extra introducido al copiar la clave son causas comunes.

Errores de carga útil

Un 400 con un mensaje sobre el cuerpo de la solicitud significa que el JSON en sí está mal: falta prompt, hay una coma extra, en Python usaste data= en lugar de json=, o el campo image no está codificado correctamente. Imprime una vez los bytes exactos que envías, revísalos y luego elimina la impresión.

Entrada rechazada

Las solicitudes de imagen a imagen que no pasan la validación suelen estar relacionadas con la imagen de entrada: demasiado grande, formato incorrecto o no se puede decodificar. Valida el tamaño y la codificación de tu lado antes de enviar, y devuelve un error claro a quien proporcionó la imagen, en lugar de reintentar.

Tiempos de espera y 5xx

Estos pertenecen a la categoría de reintentables. Distingue en los registros entre tiempos de espera de conexión y errores del servidor, y confirma que tus reintentos tienen un límite; de lo contrario, un 5xx persistente se convertirá en un bucle infinito.

Una secuencia de diagnóstico eficaz

  1. Registra el código de estado HTTP y el texto sin procesar de la respuesta para cada fallo.
  2. Verifica primero la ruta de las credenciales, antes que cualquier otra cosa.
  3. Reenvía la carga útil fallida con curl, eliminando tu código de cliente de la ecuación.
  4. Solo después de esto, ajusta prompt, image u otros parámetros del modelo.

Si el fallo persiste después de los cuatro pasos, captura el ID de solicitud (o el campo de correlación equivalente) de la respuesta y adjúntalo al contactar con soporte; esto convierte un informe vago en algo rastreable.

Prepararlo para producción

Antes de lanzar, revisa esta lista de verificación.

  • Secretos: la clave de API se carga desde variables de entorno o un gestor de secretos y no aparece en ningún registro, mensaje de error ni artefacto empaquetado del cliente.
  • Tiempos de espera: cada llamada HTTP —creación, sondeo y obtención de la imagen resultante— tiene un tiempo de espera explícito.
  • Límites: el sondeo tiene una fecha límite, los reintentos tienen un número máximo de intentos y el código distingue entre fallos reintentables y no reintentables.
  • Observabilidad: registra para cada llamada la forma de la solicitud (omite o aplica hash si el prompt puede contener datos de usuario), el código de estado, la latencia y el ID de correlación.
  • Conciencia de costos: la facturación sigue las dimensiones definidas por tu cuenta de HiAPI, así que rastrea cuántas generaciones y cuánta salida produce cada solicitud, e instrumenta tus propios contadores de uso para que los bucles descontrolados sean visibles antes de la factura.
  • Almacenamiento: las imágenes generadas se escriben en una ubicación persistente —almacenamiento de objetos o una base de datos— en lugar de quedarse en un directorio temporal que desaparece con el contenedor.

Ninguno de estos elementos es específico de nano-banana-2. Ese es precisamente el punto: la llamada al modelo es la parte sencilla, y todo lo que la rodea es higiene estándar de sistemas distribuidos. Construye el wrapper una vez, mantén la carga útil en un dict, y tanto texto a imagen como imagen a imagen lo obtienen gratis.

Empieza con la llamada curl, pórtala al wrapper de Python, añade el bucle de sondeo y luego ejecuta la lista de verificación. Para detalles del modelo y la referencia de API más reciente, consulta la documentación de nano-banana-2 en la plataforma HiAPI.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API