Tutorial
Tutorial de la API de Nano-Banana-2: uso de curl y Python Requests que funcionan a través de hiapi
En esta página
Preparativos antes de la primera llamada
Antes de enviar cualquier solicitud a Nano-Banana-2, prepara cuatro cosas. Ninguna lleva mucho tiempo, y tenerlas todas listas convierte la primera solicitud en un ejercicio de copiar y pegar en lugar de una búsqueda del tesoro.
1. Cuenta de hiapi y clave de API
Cada solicitud se autentica mediante una clave de API vinculada a tu cuenta de hiapi. Crea la clave en el panel de tu cuenta y guárdala en un lugar seguro: un gestor de contraseñas o una variable de entorno en tu máquina. Trátala como una contraseña: nunca la confirmes en un repositorio de código ni la pegues en documentos compartidos.
En tu máquina, expórtala una vez por cada sesión de shell, para que los ejemplos siguientes puedan leerla sin codificar nada de forma rígida:
export HIAPI_API_KEY="your_api_key_here"
2. URL base de la API
La URL base es la dirección raíz sobre la que se construyen todas las solicitudes. Al construir un endpoint, añades la ruta del modelo después de ella. Coloca la URL base en una variable de configuración en tu código, no dispersa en varios archivos; así, si cambia, solo tendrás que modificar una línea.
3. Cliente para enviar solicitudes
Para empezar solo necesitas uno de los siguientes:
- curl: casi con seguridad ya está instalado. Úsalo para confirmar que tu clave y tu cuerpo de solicitud son correctos antes de escribir cualquier código de aplicación.
- Python 3 más la biblioteca
requests(pip install requests). La mayoría de los lectores usarán esto para construir integraciones reales.
Tener ambos a mano es útil: curl aísla la solicitud de tu código, de modo que si algo falla sabrás si el problema está en la llamada a la API o en la aplicación.
4. Tener claro qué vas a generar
Nano-Banana-2 admite tanto texto a imagen como imagen a imagen. Decide de antemano qué modo necesitas, porque la estructura del cuerpo de la solicitud es distinta (se detalla más adelante). Para la primera llamada, empieza con texto a imagen: es la que tiene menos variables.
Con la clave exportada, el cliente instalado y la indicación pensada, ya puedes pasar a ver la solicitud en sí.
Componentes de una solicitud a Nano-Banana-2
Una llamada a Nano-Banana-2 es una solicitud POST con un cuerpo JSON. Cada campo cumple su función; entenderlos por separado significa que, cuando algo falle, podrás cambiar una cosa a la vez.
Endpoint
La solicitud se envía a la URL base de la API de hiapi, con la ruta del modelo Nano-Banana-2 añadida. El método es siempre POST, porque estás enviando una carga pendiente de procesar, no obteniendo un recurso.
Encabezados de la solicitud
Hay dos encabezados importantes:
Content-Type: application/json: indica a la API cómo interpretar tu cuerpo de solicitud.Authorization: transporta tu clave de API. Los ejemplos siguientes la leen de la variable de entorno que exportaste antes.
Si falta cualquiera de los encabezados o tiene un formato incorrecto, la solicitud fallará antes de que el modelo la vea. Esta es la causa individual más común de errores desconcertantes.
Campos del cuerpo de la solicitud
Una solicitud de texto a imagen lleva los siguientes campos:
model: especifica que el modelo a ejecutar es Nano-Banana-2. Escríbelo explícitamente aunque exista un valor predeterminado; esto hace que tu código se explique por sí mismo y te protege si el valor predeterminado cambia.prompt: describe en lenguaje natural la imagen que deseas. Aquí es donde ocurrirá la mayor parte de tu trabajo de iteración. Sé específico: sujeto, composición, estilo, iluminación. Las indicaciones vagas producen resultados vagos.- Entrada de imagen: ausente o vacía en texto a imagen. En imagen a imagen, transporta tu imagen de referencia (hay más detalles en la sección de imagen a imagen).
- Parámetros de salida y tamaño: campos específicos del modelo que afectan a la forma o proporción del resultado devuelto. Configura solo los campos que la documentación del modelo indique que admite; en API estrictas, los campos desconocidos suelen provocar el rechazo de la solicitud en lugar de ignorarse silenciosamente.
Contenido devuelto
La respuesta es JSON. Según cómo se construya la llamada, recibirás directamente los datos de la imagen generada o una referencia a ellos. Tu código cliente debe comprobar primero el estado HTTP y después el cuerpo de la respuesta; no supongas que una respuesta con forma de 200 contiene una imagen sin verificarlo.
La estructura completa es esta: una solicitud POST autenticada con un cuerpo JSON explícito y pequeño. Todo el resto de este tutorial son variantes de esta forma.
Una solicitud curl que funciona
Esta es la llamada completa mínima que puedes enviar. Ejecútala en una terminal donde ya hayas exportado la clave de API y en segundos sabrás si la cuenta, la clave y la ruta de red funcionan correctamente.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Configura la URL base una vez en el shell junto con la clave:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Usa la URL base que aparece en tu panel de hiapi; ese es el valor autoritativo de tu cuenta).
Leer la salida
curl imprime la respuesta sin procesar en stdout. Si la llamada tiene éxito, verás un JSON que contiene la imagen generada. Canalízalo a través de python -m json.tool para formatear la salida y confirmar la estructura:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Interpretar lo que ves
- Respuesta correcta: confirma que tu clave es válida, el endpoint es correcto y el cuerpo de la solicitud se puede analizar. Guarda este comando que funciona: es tu línea base.
- Respuesta de error: indica que algo está mal en las tres líneas de encabezados o en el cuerpo de la solicitud. Copia el texto del error; la sección de depuración relaciona los errores comunes con sus soluciones.
El valor de empezar con curl está en el aislamiento. Tu clave, tus encabezados y tu JSON están todos visibles en un solo lugar, así que un fallo apunta a la solicitud misma, no a tu código de aplicación. Una vez que este comando funciona, trasladarlo a Python es una tarea mecánica.
La misma solicitud implementada en Python
Esta es la misma llamada implementada con requests. El cuerpo de la solicitud es el mismo dict que viste en el cuerpo de curl: la API no cambia en absoluto, solo cambia la forma en que la envías.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Por qué está escrito así
json=payloadhace querequestsserialice el dict por ti y configureContent-Type. Aun así puedes pasar el encabezado explícitamente; no hace daño y hace que la solicitud se explique por sí misma.timeout=120: la generación de imágenes no es instantánea. Un tiempo de espera amplio evita que el cliente se rinda mientras el modelo aún está trabajando. Ajusta este valor según tu caso de uso.raise_for_status()convierte las respuestas que no son 2xx en excepciones, de modo que los fallos se revelan de inmediato en lugar de filtrarse silenciosamente en tu código de procesamiento de resultados.- Las variables de entorno mantienen la clave alejada del código fuente. En producción, insértala desde el almacén de secretos de la plataforma, no desde un archivo
.envque podría confirmarse en el repositorio.
Extraer la imagen
El cuerpo de la respuesta es JSON. Inspecciónalo una vez de forma interactiva para conocer la estructura exacta y luego extrae explícitamente el campo de la imagen:
image_url = data["image_url"] # confirma el nombre de la clave con una respuesta real
Si tu respuesta transporta datos base64 en lugar de una URL, decodifícalos y escríbelos:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
No adivines los nombres de los campos: imprime la respuesta sin procesar en tu primera llamada exitosa y toma los valores según lo que realmente exista. Este único hábito previene la mayoría de los defectos de integración.
Texto a imagen frente a imagen a imagen con imagen de referencia
Hasta aquí todo ha sido texto a imagen: introduces una indicación y obtienes una imagen. Nano-Banana-2 también admite imagen a imagen, donde proporcionas una imagen de referencia que el modelo usa como guía. Saber cuándo cambiar de modo y cómo cambia el cuerpo de la solicitud es la diferencia entre una llamada exitosa y una rechazada.
Cuándo usar cada modo
- Texto a imagen: tienes una idea expresada en palabras y ninguna imagen de partida. Es ideal para exploración, ilustración y cualquier contenido generado desde cero.
- Imagen a imagen: tienes una imagen existente y quieres una variante, un cambio de estilo o una edición que conserve su estructura o su sujeto. Este es el modo para iterar diseños, igualar un estilo visual o transformar fotografías.
Si tu indicación es «haz que se vea como…» o «mantén la disposición pero…», entonces necesitas imagen a imagen.
Cómo cambia la solicitud con una imagen de referencia
El endpoint y los encabezados no cambian. Lo que cambia es el cuerpo de la solicitud: añades un campo de imagen de referencia junto a la indicación. Según cómo se proporcione la imagen, ese campo transporta una URL o datos de imagen codificados. Ten en cuenta estas reglas:
- Si pasas un enlace, usa una URL accesible públicamente de forma directa. Las páginas que requieren inicio de sesión o que redirigen a través de autenticación fallarán: la API necesita obtener los bytes directamente.
- Usa el formato esperado. Los formatos comunes como PNG y JPEG son seguros; los archivos inusuales o dañados son una causa frecuente de rechazo de la solicitud.
- Comprueba los límites de tamaño antes de subir. Las imágenes grandes suelen ser la causa de errores en el cuerpo de la solicitud.
- Mantén la indicación enfocada. Cuando hay una imagen de referencia, describe la transformación que deseas en lugar de volver a describir la imagen de referencia.
Un cuerpo de solicitud de imagen a imagen esquemático es el siguiente:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Como siempre, confirma los nombres exactos de los campos con tu primera respuesta exitosa. El principio es simple: texto a imagen solo lleva una indicación; imagen a imagen añade una imagen de referencia verificada sobre la misma forma de solicitud. Primero demuestra que el flujo funciona con texto a imagen y después añade la imagen de referencia.
Gestionar errores y depurar solicitudes fallidas
Los fallos en las llamadas a Nano-Banana-2 se reducen a tres categorías. Aprende a reconocer cada una y podrás corregir la mayoría de los problemas en un minuto.
Errores de autenticación
Si ves un error de autenticación, significa que la clave no llegó correctamente a la API. Comprueba en orden:
- ¿
HIAPI_API_KEYestá realmente exportada en el shell o entorno que ejecuta la solicitud? Ejecutaecho $HIAPI_API_KEYpara confirmarlo. - ¿El encabezado
Authorizationexiste y tiene el formato correcto? Tanto el esquema como la clave importan. - ¿La clave se ha revocado o rotado en el panel?
- ¿Estás accediendo a la URL base correcta de tu cuenta?
Un 401 o un 403 casi siempre significa una de estas cuatro situaciones. La clave en sí rara vez es el problema: normalmente lo es el mecanismo que la transporta.
Errores de formato en el cuerpo de la solicitud
Los errores del tipo 400 suelen significar que la API no puede analizar o validar tu cuerpo de solicitud:
- JSON no válido: comas sobrantes, comillas simples en lugar de dobles o caracteres sin escapar. Canalizar la salida de curl a
python -m json.tooly construir el cuerpo de la solicitud en código en lugar de a mano ayuda. - Faltan campos obligatorios:
modelypromptson los que más se olvidan; envía siempre ambos de forma explícita. - Campos desconocidos o no admitidos: las API estrictas rechazan los campos que no reconocen. Elimina todo lo superfluo hasta que la solicitud pase y luego vuelve a añadir un elemento a la vez.
- Tipos de valor incorrectos: números enviados como cadenas, o un arreglo donde se espera un único valor. Ajusta los tipos exactamente a los de la documentación.
Entradas de imagen deficientes
Solo afecta a imagen a imagen, pero es lo más frustrante cuando ocurre: URL de imagen que requieren autenticación, URL que están detrás de una redirección, URL que devuelven HTML en lugar de una imagen, tamaños demasiado grandes o formatos no admitidos. Confirma que la URL carga directamente en un navegador sin iniciar sesión y comprueba el tipo y el tamaño del archivo frente a los límites antes de enviarlo.
Una secuencia de depuración eficaz
- Lee literalmente el mensaje de error y el código de estado; suelen señalar el problema.
- Reproduce la solicitud fallida en curl con los campos mínimos y luego vuelve a añadir complejidad paso a paso.
- Imprime el cuerpo completo de la respuesta antes de procesarlo; no confíes en tus suposiciones sobre su estructura.
Si la llamada mínima con curl tiene éxito pero tu aplicación falla, entonces el defecto está en tu código, no en la API. Esa es la demarcación de diagnóstico más rápida que puedes hacer.
Integrarlo en tu aplicación
Una solicitud que funciona es un buen comienzo; una integración fiable necesita algo más a su alrededor. A continuación te mostramos cómo pasar de una llamada puntual a algo en lo que puedas confiar.
Encapsular la llamada en una función
Aísla la solicitud en una función que reciba la indicación (y opcionalmente una imagen de referencia) y devuelva el resultado. Mantén dentro de esa función los encabezados, la URL base y la construcción del cuerpo de la solicitud, para que el resto del código base nunca entre en contacto con ellos. Cuando la API cambie, solo tendrás que editar un lugar.
Gestionar los reintentos con criterio
La generación puede fallar temporalmente por motivos ajenos a tu cuerpo de solicitud. Reintenta con retroceso exponencial, pero solo para fallos reintentables: tiempos de espera agotados y ciertos errores del lado del servidor. Nunca reintentes errores de autenticación ni de validación del cuerpo de la solicitud; fallarán de la misma manera cada vez y solo aumentarán la carga. Limita el número de intentos para que los problemas persistentes se revelen en lugar de quedarse colgados.
Tiempos de espera y concurrencia
Configura un tiempo de espera suficientemente amplio para la generación pero con un límite superior, y ajústalo después de medir tiempos de respuesta reales. Si vas a emitir muchas solicitudes, respeta límites de concurrencia razonables en lugar de enviarlas todas a la vez: una cola con un grupo de trabajadores es más predecible que llamadas paralelas sin restricción.
Almacenar lo que generas
La respuesta te entrega la imagen generada. Cópiala de inmediato a tu propio almacenamiento en lugar de depender de que la URL devuelta siga siendo válida indefinidamente. Nombra los archivos de forma determinista y registra la indicación y los parámetros junto a cada salida; necesitarás esa trazabilidad más adelante cuando iteres las indicaciones.
Mantener las claves fuera del código
Lee la clave de API desde variables de entorno o un gestor de secretos en cada entorno. Rota las claves con regularidad. Si una clave aparece donde no debería, revócala en el panel.
Empezar poco a poco y luego ampliar
Haz que una indicación funcione en curl, trasládala a Python, añade el manejo de errores de la sección anterior y solo entonces construye las colas y el almacenamiento que la rodean. Cada paso demuestra el anterior.
Con una llamada curl verificada, un cliente Python equivalente y las tres categorías de errores gestionadas, tienes el camino completo desde la primera solicitud hasta la integración en producción.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio