Guía de la API de Nano Banana: llamar a nano-banana, nano-banana-2 y nano-banana-pro en HiAPI

Qué ofrece la familia de modelos Nano Banana

La generación de imágenes rara vez se queda en una sola configuración. Al principio de un proyecto necesitas bocetos rápidos para explorar ideas; más adelante necesitas renderizados refinados para entregar. La familia Nano Banana en HiAPI está construida precisamente en torno a esa realidad: una interfaz, tres variantes, cada una ajustada a un punto distinto de la curva de calidad y velocidad.

La nomenclatura es intencionada. nano-banana es la opción básica: úsala cuando aún necesitas retroalimentación visual rápida mientras das forma a un prompt o a un diseño. nano-banana-2 da un paso más en fidelidad y adherencia al prompt, y suele ser la elección cuando la salida está cerca de la definitiva pero aún quieres seguir iterando. nano-banana-pro es la variante de mayor fidelidad de la familia, adecuada para renderizados finales donde el detalle y la composición son lo más importante.

Lo que comparten importa tanto como lo que los diferencia. Las tres se invocan a través del mismo endpoint de HiAPI. Te autenticas una vez, construyes una vez la solicitud y, al cambiar, solo modificas el identificador del modelo. Esto significa que una aplicación puede lanzar solicitudes con el modelo base y después volver a ejecutar el mismo prompt con una variante más potente sin tocar el código de la capa de transporte.

Una familia así también mantiene simple tu arquitectura. En lugar de integrar un proveedor independiente por cada nivel de calidad, conservas un único cliente, una única ruta de manejo de errores y un único punto de observación del uso. La selección de modelo se convierte en un parámetro, no en una integración.

Por qué una familia y no un solo modelo

Los distintos pasos de un flujo de trabajo tienen necesidades distintas. La exploración de prompts, los bocetos de diseño y las vistas previas para el cliente priorizan la velocidad; las imágenes principales y el material de marketing priorizan la fidelidad. Tratar la selección de modelo como una decisión en tiempo de ejecución te permite emparejar cada paso con la variante adecuada sin reconstruir el pipeline.

Elegir entre nano-banana, nano-banana-2 y nano-banana-pro

Elige la variante haciéndote dos preguntas: ¿qué tan cerca está esta salida de la versión final y cuántos intentos harán falta para llegar a ella? Todo lo demás se deriva de ahí.

nano-banana: para volumen y exploración

Usa el modelo base cuando aún estés decidiendo qué aspecto debe tener la imagen. Las reformulaciones de prompts, las pruebas de estilo y las miniaturas de diseño se benefician de una respuesta rápida, y un renderizado aproximado suele responder mejor a tus preguntas que una descripción. Mantenlo como opción predeterminada durante el desarrollo.

nano-banana-2: para iteración casi final

Cambia a nano-banana-2 cuando la composición esté estable y estés refinando detalles: espaciado, fidelidad del sujeto, cuán estrechamente sigue la salida al prompt. Es la opción intermedia pragmática: adherencia notablemente mayor sin tener que pasar por la ruta de máxima fidelidad en cada vista previa.

nano-banana-pro: para el renderizado final

Reserva nano-banana-pro para la salida que vas a entregar. Las imágenes principales, las imágenes de producto y cualquier contenido que el cliente vaya a examinar de cerca merecen la variante más potente. No la configures como predeterminada: déjala para el último paso, de modo que tus iteraciones exploratorias sigan siendo económicas.

Una regla de enrutamiento práctica

Una estrategia de escalado sencilla funciona para la mayoría de los equipos:

• Usa nano-banana por defecto para todos los prompts nuevos.
• Cuando la estructura sea correcta pero la calidad no baste, escala el prompt a nano-banana-2.
• Una vez fijado el prompt, ejecuta la versión final una vez en nano-banana-pro.

Esto mantiene la iteración rápida y predecible, y hace que tus patrones de uso sean fáciles de entender. La facturación sigue al uso y varía según la variante, así que confirma las tarifas y los límites vigentes en la documentación en vivo del modelo en lugar de codificar de forma fija cualquier cifra en tu código.

Patrones de prompts comunes a todas las variantes

Lo más costoso que puedes hacer es escribir prompts que solo funcionen en un modelo. Estructúralos de modo que cambiar de variante requiera una sola línea.

El prompt en cuatro bloques

Escribe cada prompt como cuatro secciones etiquetadas, en este orden:

1. Sujeto: qué hay en la imagen, enunciado de forma llana.
2. Estilo: el tratamiento visual: fotografía, ilustración, acuarela, renderizado 3D.
3. Composición: encuadre, ángulo de cámara, posición, espacio negativo.
4. Restricciones: qué evitar y cualquier requisito estricto.

Un ejemplo completado:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Como los bloques son independientes, puedes reforzar el estilo o relajar la composición sin reescribir todo el prompt, y la misma estructura se entiende con facilidad en cada variante de la familia.

Mantén los prompts independientes del modelo

Evita formulaciones que den por sentadas características de un modelo concreto. Describe el resultado que quieres, no los pasos que debería seguir un modelo específico. Cuando necesites comparar variantes, cambia solo el ID del modelo y mantén el prompt idéntico byte a byte, para que la comparación sea significativa.

Versiona los prompts como versionas el código

Guarda los prompts como cadenas en un archivo de configuración o en una pequeña biblioteca de prompts, indexados por nombre y versión. Cuando una variante produzca mejores resultados gracias a un ajuste fino, registra ese cambio. Esto es justo lo que permite pasar de nano-banana a nano-banana-pro en la entrega sin sorpresas.

Las restricciones negativas importan

Si un prompt produce sistemáticamente texto, logotipos u objetos no deseados, añádelos explícitamente al bloque de restricciones. Entre variantes, las restricciones negativas claras suelen ser más fiables que una redacción ingeniosa.

Construir solicitudes funcionales en HiAPI

Cada variante se invoca a través del mismo endpoint de HiAPI. Una solicitud tiene cuatro partes variables: la URL base, la cabecera de autenticación, el campo del modelo y el payload.

La forma de la solicitud

Una llamada mínima de generación de imágenes se ve así:

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Guarda la clave de API en una variable de entorno o en un gestor de secretos, nunca en el código fuente. El campo model es lo único que hay que cambiar al alternar entre variantes, y el campo prompt lleva la estructura de cuatro bloques de la sección anterior.

En Python, la misma llamada requiere solo unas pocas líneas:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

Qué contiene la respuesta

La respuesta transporta el resultado de la imagen, normalmente una URL o un payload codificado, además de metadatos que identifican el modelo que procesó la solicitud. Lee de vuelta el campo del modelo y regístralo: es la forma más económica de saber después qué variante generó un recurso determinado.

Confirma los parámetros antes de entregar

El conjunto exacto de parámetros opcionales varía según la variante y evoluciona con el tiempo. Antes de codificar de forma fija cualquier cosa que no sea model y prompt, consulta la documentación en vivo del modelo para obtener los nombres de campo y los valores aceptables actuales. Trata cualquier cosa no documentada como no compatible, en lugar de adivinarla.

Manejar respuestas, fallos y reintentos

La generación de imágenes es una llamada de red con un modelo detrás, así que planifica las partes que pueden fallar.

Valida antes de confiar

Tras cada respuesta, comprueba tres cosas: el estado HTTP, la presencia de un payload de imagen y si el modelo devuelto coincide con el que solicitaste. Ante cualquier discrepancia, falla de forma explícita en lugar de propagar un recurso defectuoso aguas abajo.

Reintenta solo los fallos que merecen reintento

No todos los errores merecen un reintento. Un prompt mal formado o un nombre de modelo no válido fallarán igual todas las veces: corrige la solicitud. Los fallos transitorios, como tiempos de espera agotados, conexiones reiniciadas y respuestas de límite de tasa, sí merecen reintento.

Usa un backoff exponencial acotado con jitter:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

Limita el número total de intentos para que una solicitud defectuosa no entre en un bucle infinito, y registra el modelo y el hash del prompt de cada intento para poder ver si una variante concreta es inestable.

Degradación consciente

Si una variante falla de forma persistente, recurrir a otro miembro de la familia mantiene vivo el pipeline. Como las tres comparten la forma de la solicitud, la degradación consiste simplemente en usar un valor de model distinto al reintentar. Decide el orden de antemano, por ejemplo, pasar de nano-banana-pro a nano-banana-2 cuando una llamada de alta fidelidad falle repetidamente, y registra cuándo se activa la degradación para que notes el patrón.

Haz visibles los fallos

Valida el payload devuelto antes de almacenarlo y emite métricas sobre reintentos y degradaciones. Cuando la tasa de errores suba, querrás saberlo antes de que un lote de tareas genere silenciosamente resultados vacíos.

Reforzar antes de la entrega

Antes de exponer la generación de imágenes a los usuarios, repasa esta lista.

Confirma los ID y los parámetros

Los identificadores de modelo cambian. Vuelve a verificar los nombres de modelo actuales de la familia Nano Banana y confirma cada parámetro opcional con la documentación en vivo. No entregues valores que solo existan en ejemplos antiguos.

Centraliza la configuración

Coloca los ID de modelo, las plantillas de prompt y los límites de reintento en un único módulo de configuración. Cuando escales un prompt de nano-banana a nano-banana-pro, debería ser un cambio de configuración, no un cambio de código repartido por varios archivos.

Registra lo importante

Para cada llamada, registra el modelo, la versión del prompt, el estado de la respuesta, la latencia y si hubo reintentos o degradaciones. Aplica hash a los prompts largos para que los registros sigan siendo legibles. Esto es justo lo que permite responder a «¿por qué esta imagen se veía distinta ayer?».

Supervisa el uso al escalar

Como la facturación sigue al uso, vigila el número de llamadas y la combinación de variantes. Que cada solicitud escale silenciosamente a nano-banana-pro podría convertir una herramienta de exploración en un problema de costes. Enruta con criterio: variantes económicas para iterar y variantes más potentes para la salida final.

Prueba el endpoint

Escribe una pequeña prueba de humo que invoque cada variante una vez con un prompt fijo y verifique que la respuesta sea válida. Ejecútala antes de cada publicación contra la documentación vigente, para que los cambios de modelo nunca te sorprendan en producción.

Entrega con un único cliente, una biblioteca de prompts compartida y una estrategia de enrutamiento consciente, y la familia Nano Banana en HiAPI será la única dependencia que necesites para escalar del boceto al renderizado final sin reescribir la integración.