Nano Banana 2.1 · API

Inicio rápido

Tres pasos: enviar el trabajo, consultarlo y quedarte con el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "2K"}'

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2.1"
}

curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2.1",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}

Paso 3 · data[0].url es la imagen (PNG). Se guarda 60 días; descárgala a tu propio almacenamiento si la necesitas más tiempo.

import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. enviar
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2.1",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2.1.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Cuerpo de la petición

Ejemplo de petición

# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

import time, requests

base, key = "https://nezhagate.com/v1", "YOUR_API_KEY"
h = {"Authorization": f"Bearer {key}"}
job = requests.post(f"{base}/images/generations", headers=h,
                    json={"model": "nano-banana-2.1", "prompt": "an ink-wash poster", "size": "16:9", "resolution": "2K"}).json()
while True:
    r = requests.get(f"{base}/images/jobs/{job['id']}", headers=h).json()
    if r["status"] in ("succeeded", "failed"): break
    time.sleep(3)
print(r.get("data", [{}])[0].get("url"))

const base = "https://nezhagate.com/v1", key = "YOUR_API_KEY";
const h = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
const job = await (await fetch(`${base}/images/generations`, { method: "POST", headers: h,
  body: JSON.stringify({ model: "nano-banana-2.1", prompt: "an ink-wash poster", size: "16:9", resolution: "2K" }) })).json();
let r;
do { await new Promise(s => setTimeout(s, 3000));
     r = await (await fetch(`${base}/images/jobs/${job.id}`, { headers: h })).json();
} while (r.status !== "succeeded" && r.status !== "failed");
console.log(r.data?.[0]?.url);

Respuesta

{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2.1"
}

Precio

Se cobra por imagen y el precio depende solo del nivel de resolución: la proporción y si es texto a imagen o imagen a imagen no cambian nada. Al enviar se retiene el precio del nivel y, si el trabajo falla, se reembolsa por completo. 1 crédito = $0.005.

Cada trabajo devuelve exactamente una imagen: envíes el n que envíes, recibes una imagen y pagas una. Para varias imágenes, envía varios trabajos a la vez (una cuenta genera hasta 50 al mismo tiempo).

Proporción, resolución y tamaño de salida

Pon la proporción en size y el nivel en resolution (1K por defecto, 2K o 4K). El modelo dibuja directamente en la proporción elegida; no dibuja un cuadrado para recortarlo después. La imagen entregada tiene un lado largo de 1024 / 2048 / 4096 píxeles y el otro sigue la proporción. Proporciones habituales:

Además de estas siete, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8 y 8:1 también se dibujan de forma nativa (con la misma regla del lado largo). Cualquier otra proporción se dibuja en la forma horizontal, vertical o cuadrada más cercana y luego se recorta a la tuya, lo que puede cortar parte de la imagen.

size también puede ser un tamaño en píxeles (p. ej. 1536x1024): la imagen se entrega exactamente con ese tamaño y el nivel lo decide el lado más largo: hasta 1536 es 1K, hasta 2048 es 2K y por encima es 4K. resolution solo acepta 1K / 2K / 4K (en mayúsculas o minúsculas); cualquier otro valor se ignora y el nivel sale de size, 1K por defecto. Sin size obtienes un cuadrado 1:1.

Imagen a imagen e imágenes de referencia

• Envía image (una imagen) o images (varias, hasta 8; si mandas más, solo se usan las 8 primeras) y el trabajo pasa a ser imagen a imagen; explica en el prompt qué quieres cambiar. POST /v1/images/edits admite los mismos parámetros.
• Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 sin más, de hasta 16 MB cada una, en un formato común como JPEG, PNG o WebP.
• La URL tiene que descargar la imagen en sí: no una página web, ni una dirección que pida iniciar sesión o bloquee el hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 y el motivo; no se crea ningún trabajo ni se cobra nada.
• La proporción de salida la decide size, no la referencia. Para mantener la proporción original, pon en size la de la imagen.
• Alojamos las referencias por ti y las guardamos 7 días.

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Estado del trabajo y campos

GET /v1/images/jobs/{id} siempre devuelve id, object (image.generation.job), status, created (segundos Unix) y model; los demás campos dependen del estado:

Consulta cada 2-3 segundos. Una cuenta genera hasta 50 imágenes a la vez; los demás trabajos esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa por completo. Los registros de los trabajos se guardan 3 días; después, el id devuelve 404, pero el enlace de la imagen sigue siendo válido durante sus 60 días. Solo la cuenta que envió un trabajo puede consultarlo.

Cuánto tarda

Tiempo habitual desde el envío hasta el resultado, como referencia. Imagen a imagen tarda de unos segundos a una docena más; un trabajo que la pasarela repite en otra línea puede tardar 1-2 minutos.

Errores y reembolsos

Todos los errores tienen la misma forma, {"error": {"message", "type", "code", "param"}}; decide según code.

Errores devueltos al enviar (no se crea ningún trabajo ni se cobra nada)

Trabajos fallidos (el trabajo se aceptó y terminó con status failed; la retención se reembolsa por completo)

Usa un webhook en lugar de consultar

En producción, añade callback_url al enviar. Cuando el trabajo termine, bien o mal, enviaremos por POST a esa URL el mismo JSON que devuelve la consulta, como image.completed o image.failed, con cabeceras de firma que puedes verificar. También puedes fijar una URL para toda la cuenta en Ajustes > Webhook. Documentación de webhooks

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'