Blog

Tutorial

Cómo usar Nano-Banana a través de la API de HiAPI: curl, Python y solicitudes ejecutables

Nov 12, 2026
Planos de vidrio translúcido superpuestos y abstractos que refractan un fondo gris claro en franjas de tonos azules fríos, usados como imagen de portada del tutorial
En esta página

Qué ofrece Nano-Banana como API a los desarrolladores

Nano-Banana es un modelo de generación de imágenes expuesto a través de la API de HiAPI. Envías un prompt —y, si lo necesitas, una o varias imágenes de referencia— y recibes la imagen generada. El modelo mental es así de simple. Sin alojar el modelo localmente, sin GPU, sin aprender un SDK adicional: el mismo método de autenticación, la misma envoltura de solicitud y el mismo mecanismo de tareas asíncronas que usas con otros modelos de HiAPI se aplican aquí igualmente.

Antes de escribir código, conviene tener claro qué es y qué no es el endpoint de generación de imágenes. Es un endpoint creativo: un mismo prompt puede producir resultados distintos en ejecuciones diferentes, y debes diseñar tu flujo de trabajo para tolerarlo. No es una transformación determinista como el escalado o la conversión de formato. Si necesitas reproducibilidad exacta a nivel de píxel, almacena en caché las salidas que hayas validado, en lugar de suponer que una regeneración dará el mismo resultado.

Una integración típica consta de tres fases:

  1. Enviar una solicitud de generación con el prompt y cualquier entrada opcional.
  2. Esperar a que la tarea de generación termine, ya que generar imágenes tarda más que una simple completación de texto.
  3. Obtener la salida, almacenarla y decidir si la aceptas o si ajustas el prompt y vuelves a intentarlo.

Hay dos cosas que merece la pena decidir desde el principio, porque condicionan todo lo demás: si tu prompt es solo texto o usa imágenes de referencia (lo que cambia la carga de la solicitud), y si necesitas mantener la coherencia de un personaje entre varias generaciones (lo que casi siempre implica usar imágenes de referencia). Las siguientes secciones se irán desplegando desde la estructura de la solicitud hacia fuera, y podrás ir ajustando los ejemplos sobre la marcha.

Anatomía de una solicitud a Nano-Banana

Toda solicitud a Nano-Banana a través de HiAPI comparte el mismo esqueleto. Lo que cambia es la carga.

Endpoint y autenticación

La solicitud se envía a la URL base de HiAPI y el modelo concreto se especifica en la carga de la solicitud, no en una URL de nivel superior construida a mano. Te autenticas llevando tu clave de API en la cabecera Authorization. Guarda la clave en una variable de entorno; nunca la incluyas directamente en el código fuente ni la confirmes en el repositorio.

Nombre del modelo

El identificador del modelo es un campo del cuerpo JSON de tu solicitud. Trátalo como una cadena que debes copiar literalmente de la lista de modelos, no como algo que construyes tú, para que los cambios de nombre no rompan tu código en silencio.

Carga del prompt

Como mínimo, debes enviar un prompt de texto que describa la imagen objetivo. Aquí, la calidad del prompt influye en la calidad de la salida mucho más que cualquier otro campo. Sé concreto sobre el sujeto, la composición, la iluminación y el estilo. Un prompt vago genera una imagen vaga, y ningún ajuste de parámetros puede salvar un prompt que no expresa lo que realmente necesitas.

Imágenes de referencia opcionales

Si incluyes imágenes de referencia, forman parte del mismo cuerpo de la solicitud, normalmente como URL de imagen o datos de imagen codificados, según el formato que acepte el modelo. Las imágenes de referencia pueden anclar elementos como la cara, la ropa o el estilo artístico general de un personaje. Omítelas cuando generes solo a partir de texto; inclúyelas cuando la salida deba parecerse a un objeto concreto.

Campos relacionados con la salida

Algunos campos afectan a la forma del resultado más que a su contenido: por ejemplo, el tamaño de salida o la relación de aspecto solicitados. Conviene tratarlos como valores solicitados, no como valores garantizados: el tamaño que devuelve el modelo puede diferir ligeramente. El código posterior debe leer el tamaño real devuelto, en lugar de suponer que obtendrás lo que solicitaste.

A continuación se muestra la estructura conceptual, con valores de marcador de posición:

{
  "model": "<nano-banana-model-id>",
  "prompt": "Un zorro rojo sentado entre hierba alta durante la hora dorada, poca profundidad de campo",
  "reference_images": [],
  "size": "1024x1024"
}

Consulta la documentación de parámetros del modelo para conocer los nombres de campo y formatos exactos que acepta; la estructura anterior es solo un patrón genérico y no sustituye a la documentación normativa.

Solicitud curl ejecutable

La forma más rápida de confirmar que tu clave funciona y que la carga es válida es hacer una llamada curl. Primero configura el entorno:

export HIAPI_API_KEY="your-api-key-here"

Después envía la solicitud de generación:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<nano-banana-model-id>",
    "prompt": "Un zorro rojo sentado entre hierba alta durante la hora dorada, poca profundidad de campo",
    "size": "1024x1024"
  }'

Función de cada parte:

  • URL — la ruta de generación de imágenes de HiAPI. Una sola URL base sirve a todos los modelos; el modelo se especifica en el cuerpo de la solicitud.
  • Authorization — tu clave, leída del entorno, para que no acabe en el historial del shell ni en el control de código fuente.
  • Content-Type — debe ser application/json; un error común de principiante es olvidarlo, lo que produce errores de análisis.
  • Cuerpo de la solicitud — la carga JSON de la sección anterior, que contiene el prompt que realmente quieres.

Interpretar la respuesta

La respuesta te dice qué ha ocurrido. Hay dos tipos de resultado que conviene conocer:

  • Resultado síncrono — algunas llamadas devuelven directamente datos de imagen o una URL de imagen. Si ves una URL, descárgala y guárdala lo antes posible, en lugar de confiar en que estará disponible a largo plazo.
  • Identificador de tarea — si la generación es asíncrona, la respuesta incluye un identificador para consultar el estado. Ese es el tema de la sección asíncrona a continuación.

Si quieres ver la línea de estado HTTP y las cabeceras de respuesta además del cuerpo, añade -i al comando curl; cuando hay un error, resulta muy útil para distinguir si el problema es de autenticación o de carga.

La misma llamada en Python

Para cualquier cosa que no sea un script desechable, usa Python. La biblioteca requests mantiene los ejemplos ligeros en dependencias y hace que la capa HTTP sea explícita y visible.

import os
import requests

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

payload = {
    "model": "<nano-banana-model-id>",
    "prompt": "Un zorro rojo sentado entre hierba alta durante la hora dorada, poca profundidad de campo",
    "size": "1024x1024",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Algunos hábitos que conviene adquirir desde el principio:

  • Establece un timeout. La generación de imágenes es lenta; sin timeout, tu proceso de trabajo podría quedarse colgado indefinidamente. Para llamadas síncronas, un timeout generoso es un punto de partida razonable, pero ajústalo según tu carga.
  • Usa raise_for_status(). Convierte las respuestas 4xx y 5xx en excepciones capturables, en lugar de analizar silenciosamente un cuerpo de error como si fuera un resultado.
  • Encapsula en una función. El fragmento anterior es un script; en un servicio necesitarás una función que reciba un prompt y devuelva datos de imagen o un identificador de tarea, de modo que el resto de tu código no tenga que preocuparse por los detalles HTTP.

Si la respuesta incluye una URL de imagen, descárgala y guárdala de inmediato:

for item in data.get("data", []):
    url = item.get("url")
    if url:
        img = requests.get(url, timeout=60)
        img.raise_for_status()
        with open("output.png", "wb") as f:
            f.write(img.content)

La fuente de datos real de tu aplicación debe ser tu propio almacenamiento, no una URL remota temporal.

Gestionar tareas asíncronas

La generación de imágenes suele tardar más de lo que conviene mantener abierta una única conexión HTTP. Los modelos de HiAPI que funcionan así devuelven un identificador de tarea al enviar la solicitud, y luego consultas el endpoint de estado de la tarea hasta que el trabajo termina. Este patrón se aplica a todos los modelos asíncronos de la plataforma, así que aprendelo una sola vez.

Primero enviar, luego consultar

Tu POST inicial devuelve algo parecido a un ID de tarea. Después consultas el endpoint de estado con ese ID. La lógica que necesitas es:

import time

def poll_task(task_id, api_key, interval=2, max_wait=300):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.hiapi.ai/v1/tasks/{task_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("succeeded", "completed", "failed", "error"):
            return body
        time.sleep(interval)
    raise TimeoutError(f"La tarea {task_id} no terminó en {max_wait} segundos")

Tres reglas que te ahorrarán tropiezos

  1. Limita siempre el tiempo total de espera. Un trabajo que nunca termina no puede bloquear tu proceso de trabajo. El max_wait anterior es tu vía de escape.
  2. Usa retroceso exponencial. Un intervalo fijo corto va bien para uso interactivo; para trabajos por lotes, aumenta el intervalo a medida que crece la espera, para no saturar el endpoint de estado.
  3. Verifica el estado final. succeeded significa que puedes leer la salida; failed significa que debes leer la carga de error en lugar de reintentar a ciegas. Reintentar una carga mal formada solo hace perder tiempo.

Persiste el ID de tarea junto con tus propios registros de trabajo. Si tu proceso se reinicia a mitad de la consulta, puedes seguir consultando sin volver a enviar la solicitud y pagar por una generación duplicada.

Imágenes de referencia y coherencia de personajes

Los prompts solo de texto van bien para imágenes puntuales, pero se quedan cortos cuando necesitas el mismo personaje en diez escenas distintas. Describir una cara con palabras y esperar que el modelo la reproduzca de forma estable casi nunca funciona: pequeñas variaciones en la redacción generan personas diferentes.

Las imágenes de referencia resuelven esto. Incluyes una o varias imágenes junto con el prompt de texto en la solicitud, y el modelo las usa como ancla visual. La coherencia de personajes es el caso de uso central:

  • Hoja de personaje — una imagen de referencia limpia, varios prompts de escena, manteniendo la misma cara y ropa.
  • Anclaje de estilo — la imagen de referencia fija el lenguaje visual y el prompt guía el contenido.
  • Fotografía de producto — la imagen de referencia de un objeto mantiene su diseño estable en distintos fondos.

En la solicitud, esto significa rellenar el campo de imágenes de referencia en lugar de enviar un valor vacío. Proporciona las imágenes como URL o como datos codificados, según lo que admita la especificación de parámetros del modelo, y mantén las imágenes de referencia limpias: un sujeto claro es mejor que una escena desordenada, porque el modelo capta todo lo que hay en el encuadre, no solo la parte que te interesa.

Un patrón práctico para el flujo de trabajo:

  1. Genera el personaje una vez a partir de un prompt de texto detallado.
  2. Revísalo, acéptalo o vuelve a generarlo hasta que estés satisfecho.
  3. Usa esa imagen validada como imagen de referencia para cada escena posterior.

Este es el flujo de trabajo nano banana API python en esencia: fijar el personaje una vez y luego cambiar solo la parte de escena del prompt. Cuenta con la iteración: las imágenes de referencia mejoran la coherencia pero no son perfectas, así que incluye un paso de revisión en lugar de suponer que cada salida es utilizable.

Resolución de salida y limitaciones reales

La resolución es el punto donde más fácilmente surgen problemas por suposiciones, así que trátala con cuidado.

Tamaño solicitado frente a tamaño real

Puedes solicitar un tamaño de salida, pero debes tratarlo como una sugerencia. El tamaño que devuelve el modelo puede diferir del solicitado, sobre todo con relaciones de aspecto poco habituales. Lo robusto es leer las dimensiones reales de la imagen que recibes y tratarlas de forma genérica: tu almacenamiento, tus miniaturas y tu maquetación deben basarse en el archivo real, no en el valor solicitado.

Qué determina la calidad

La calidad de la salida la determina principalmente el prompt y, cuando se usan, las imágenes de referencia. Un prompt bien compuesto, con sujeto e iluminación claros, produce mejores imágenes que un prompt vago con un tamaño solicitado mayor. No uses la resolución para compensar un prompt mal descrito.

Planifica en torno a las limitaciones

  • No codifiques las dimensiones de forma fija en el código posterior. Léelas de la imagen devuelta.
  • Valida antes de almacenar. Si tu aplicación exige un tamaño mínimo, comprueba las dimensiones reales tras la generación y vuelve a generar si no alcanzan; no supongas que la solicitud ya ha impuesto ese requisito.
  • Vigila el tamaño de archivo. Las salidas de mayor resolución implican cargas mayores; descarga en streaming o con búfer en lugar de cargar todo en memoria dentro de un bucle.
  • Procesa por lotes con prudencia. Los límites de concurrencia son por cuenta; si vas a generar muchas imágenes, añade un pequeño grupo de workers con reintentos y retroceso exponencial, en lugar de disparar solicitudes sin control en un bucle ilimitado.

Para conocer las capacidades autorizadas de Nano-Banana y los valores aceptados, consulta la documentación del modelo, no las cargas de ejemplo de este artículo. La facturación sigue el modelo normal de pago por uso de la plataforma; consulta el panel de precios para las tarifas actuales, no este tutorial.

Solucionar errores comunes

La mayoría de los fallos en una primera integración pertenecen a unas pocas categorías. Esto es lo que hay que comprobar en cada una.

401 / 403 — autenticación

Tu clave falta, está mal formada o no se envía. Confirma que la cabecera Authorization existe, lleva el prefijo Bearer y que la variable de entorno se ha exportado realmente al shell o proceso que ejecuta el código. Los saltos de línea sobrantes al final de la clave copiada causan este problema con más frecuencia de la que cabría esperar.

400 — carga mal formada

Normalmente es una de estas cosas: JSON no válido (comillas sobrantes o comas finales), Content-Type incorrecto, falta un campo obligatorio (como prompt o model), o el campo de imágenes de referencia se envía en un formato que el modelo no acepta. Imprime el cuerpo exacto de la solicitud que estás enviando y compáralo campo por campo con la especificación de parámetros.

404 — ruta o modelo incorrectos

La ruta del endpoint es incorrecta, o el identificador del modelo no coincide con ningún modelo de la plataforma. Copia el nombre del modelo literalmente desde la lista en lugar de escribirlo de memoria.

Timeouts y consultas de estado estancadas

En llamadas síncronas, un timeout demasiado corto interrumpe trabajos que podrían haber tenido éxito. En trabajos asíncronos, una consulta de estado estancada suele significar que tu lógica de consulta sale antes de tiempo, o que la comprobación de estados finales no coincide con las cadenas de estado que devuelve realmente la API; registra los valores de estado sin procesar y verifícalos. Mantén siempre un tiempo máximo de espera para que los trabajos atascados fallen de forma visible en lugar de colgarse.

Resultado vacío

Recibir 200 sin imagen casi siempre es un problema de contenido, no un bug: puede que el prompt sea demasiado vago o que haya sido filtrado. Antes de dar por hecho que la API falla, revisa el cuerpo de la respuesta en busca de campos de error o motivo, y luego ajusta y aclara el prompt.

Fallos al reintentar

Si la misma carga a veces funciona y a veces falla, es probable que hayas alcanzado un límite de tasa o que hayas encontrado un error transitorio del servidor. Añade retroceso exponencial alrededor del envío y de las consultas de estado, y no reintentes un 400: corrige la carga.

Si tienes dudas, el diagnóstico más rápido es hacer una llamada curl mínima con un prompt sencillo. Si funciona, el problema está en tu carga o en tu código, no en las credenciales.

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