Guía de uso

¿Cómo usar la API de Nano Banana Pro? Tu primera imagen en 5 minutos

4 pasos para probarlo en línea y 4 pasos para integrar la API, con ejemplos de curl y Python listos para ejecutar, ejemplos de edición con imagen de referencia y una guía rápida de errores comunes.

Oct 12, 2026

TL;DR

Qué es: Gemini 3 Pro Image de Google, el modelo insignia de la serie Nano Banana; la generación de imágenes desde texto y la edición con imagen de referencia comparten el mismo ID de modelo nano-banana-pro. Ya está disponible en HiAPI; abre la página del modelo, introduce un prompt y genera. Los usuarios nuevos reciben 200 créditos al registrarse, suficientes para 1 imagen en 2K al precio habitual.
Cuánto cuesta: se cobra por imagen; 1K y 2K cuestan lo mismo, $0.057, y 4K cuesta $0.1, calculado por cada imagen de salida. Es aproximadamente un 57 %–58 % más barato que el precio estándar oficial de Google, y las imágenes de referencia no tienen coste adicional.
Cómo llamar a la API: POST https://api.hiapi.ai/v1/tasks, con model establecido en nano-banana-pro; obtén el taskId, consulta el resultado o espera la callback y descarga data.output[0].url.

El coste de los tokens de entrada de Google se calcula aparte; la comparación de precios anterior se refiere al precio por imagen de salida.

¿Qué puede hacer Nano Banana Pro?

2K sin coste adicional. 1K y 2K cuestan $0.057 por imagen; genera directamente en 2K. 4K cuesta $0.1 por imagen y queda reservado para impresión y pantallas grandes.
Texto dentro de la imagen. Frases cortas en inglés como rótulos, títulos de pósteres o fechas se escriben directamente en el prompt; las dos líneas del rótulo de pan de oro de la imagen siguiente salieron correctas a la primera, sin ningún retoque posterior.
Hasta 8 imágenes de referencia. Si solo escribes un prompt, es generación desde texto; si añades image_input, se convierte en edición o fusión de varias imágenes. El mismo ID de modelo, sin necesidad de mantener dos conjuntos de código.
10 relaciones de aspecto más auto. Están disponibles las proporciones habituales: 1:1, 4:5, 3:4, 9:16, 16:9, 21:9, etc. Para imágenes alargadas como 1:4 u 8:1, o para enviar más de 8 imágenes de referencia a la vez, elige Nano Banana 2 (hasta 14).

Imagen original de Nano Banana Pro, sin retocar, salida de 1536×2752.

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

Generar con este prompt →, elige la relación de aspecto 9:16 y la resolución 2K.

Dos formas de empezar: ¿prueba en línea o API?

Si primero quieres ver el resultado, elige la prueba en línea; si quieres integrarlo en tu producto, elige la API. Ambos caminos usan el mismo modelo y el mismo precio.

Prueba en línea (aproximadamente 1 minuto)

Abre la página del modelo Nano Banana Pro, o haz clic directamente en el enlace que aparece debajo de la imagen del rótulo; el prompt se rellenará automáticamente.
Regístrate o inicia sesión; las cuentas nuevas incluyen 200 créditos.
Elige la relación de aspecto y la resolución; al precio habitual, 1K y 2K cuestan 114 créditos por imagen.
Haz clic en ejecutar y, si te gusta el resultado, descárgalo.

Integración de la API (aproximadamente 5 minutos)

Crea una API Key (sk-...) en la consola de HiAPI.
Usa POST /v1/tasks para crear la tarea; en la respuesta obtendrás data.taskId.
Consulta con GET /v1/tasks/{id} o incluye callback.url en la solicitud y espera la notificación.
Cuando data.status pase a success, descarga la imagen desde data.output[0].url.

Una imagen en 2K cuesta $0.057; con $10 puedes generar unas 175. El Día del Programador tiene un 50 % de descuento por tiempo limitado hasta las 00:00 (hora de Pekín) del 2026-11-09; durante ese periodo, 1K y 2K cuestan $0.0285 por imagen y con los mismos $10 puedes generar unas 350. Consulta todos los parámetros en la documentación en chino.

Tu primera imagen: versión curl

Crear la tarea:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

El ID de tarea devuelto está en data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consultar el resultado:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

El único campo obligatorio es prompt. aspect_ratio tiene como valor predeterminado auto, resolution tiene 1K y output_format tiene png; también puedes elegir jpg. 1K y 2K cuestan lo mismo, así que se recomienda incluir "resolution": "2K" en cada solicitud.

Tu primera imagen: versión Python

Primero instala requests (python3 -m pip install requests) y define HIAPI_API_KEY en la terminal (export HIAPI_API_KEY="sk-YOUR_KEY"). El ejemplo siguiente crea la tarea, consulta su estado durante un máximo de 10 minutos y descarga la imagen; si se agota el tiempo, conserva el taskId para seguir consultando:

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-pro.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Edición con imagen de referencia: basta con añadir un campo

Añade image_input dentro de input y la misma solicitud se convierte en una edición. A continuación usamos un póster de museo de ciencias generado con Nano Banana Pro como imagen de referencia y cambiamos solo la línea de la fecha:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

image_input admite hasta 8 URL públicas y es compatible con JPEG, PNG y WebP. En el prompt, describe por separado "qué cambiar" y "qué conservar"; cuanto más concretos sean los elementos que se conservan, más fiel se mantendrá la imagen original.

3 cosas que tener en cuenta antes de publicar

Usa callbacks en el servidor. Añade en el nivel superior del cuerpo de la solicitud "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; recibirás una notificación automática al terminar la tarea y evitarás el sondeo. La callback puede llegar más de una vez; deduplica por taskId.
No repitas el POST por un timeout. Cada POST /v1/tasks crea una tarea nueva y se factura por separado. Guarda el taskId; antes de reintentar, comprueba la duplicación en tu propio sistema.
Escribe resolution explícitamente en cada solicitud. El valor predeterminado es 1K; como 2K cuesta lo mismo, puedes elegir 2K directamente en las versiones finales; 4K tiene un precio unitario mayor, así que úsalo solo en la entrega final.

Errores comunes, uno por línea

400, indica que un campo no está permitido → el nombre del campo está mal escrito o se ha usado un campo de otro modelo (por ejemplo, image_urls) → cámbialo a image_input.
400, indica que el valor de aspect_ratio no es válido → se ha usado una relación de aspecto que no está en la lista (por ejemplo, 8:1) → elige una de las 10 relaciones de aspecto y auto; para imágenes alargadas, cambia a Nano Banana 2.
401 → falta la Key, está mal escrita o ha sido revocada → revisa la cabecera Authorization: Bearer sk-... y, si es necesario, vuelve a crear la Key en la consola.
La creación se realizó correctamente, pero la tarea queda en fail → revisa el error devuelto por la tarea; si la imagen de referencia no se puede abrir o el formato no es compatible, cámbiala por una JPEG, PNG o WebP accesible públicamente y vuelve a enviarla.
El enlace de la imagen deja de abrirse al caducar → el enlace de salida tiene un periodo de validez → descarga el resultado en cuanto lo recibas y guarda el archivo en sí.

Las tareas fallidas no se cobran.

Preguntas frecuentes

¿Cómo elegir entre Nano Banana Pro y Nano Banana 2? Para generar en 2K, ambos cuestan lo mismo: $0.057 por imagen. Si necesitas relaciones de aspecto alargadas o más de 8 imágenes de referencia, elige Nano Banana 2; si quieres usar el modelo insignia de la serie Nano Banana para crear la imagen principal de una marca, elige Pro.

¿Las imágenes de referencia tienen coste adicional? No. El precio solo depende de la resolución de salida; enviar 1 u 8 imágenes de referencia cuesta lo mismo.

¿Se puede cambiar directamente desde Nano Banana 2? Sí. Los nombres de los campos son los mismos (prompt, image_input, aspect_ratio, resolution, output_format); basta con cambiar model a nano-banana-pro, siempre que la relación de aspecto esté entre las 10 compatibles con Pro.

¿Cuántas imágenes se pueden generar a la vez? Cada tarea genera una imagen. Para generar varias, crea varias tareas en paralelo; se factura por imagen.

Artículos de la serie Nano Banana Pro

Pruébalo ahora: haz clic en Generar con este prompt → que aparece debajo de la imagen del rótulo; el prompt ya está rellenado. Elige 9:16 y 2K, cambia el texto entrecomillado por el nombre de tu propio negocio y ejecuta.

EtiquetasGeneración de imágenes guía-de-api Integración de API Tutorial