API de Nano Banana Pro: inicio rápido y primera imagen

01¿Qué necesitas antes de la primera solicitud?

Son cuatro cosas, en este orden:

• Una clave de API. Créala en el portal; se muestra una sola vez. Guárdala en la variable de entorno RENDERGRID_API_KEY de tu servidor, de donde la leen los ejemplos. Los pasos están en Claves y acceso.

• Saldo. La recarga es solo en USDT: se hace en la sección «Saldo y recargas» del portal o a través de un gestor de cuenta, y el pago tiene su propia ventana de 30–50 minutos. Hazla antes de empezar.

• Un lenguaje que envíe solicitudes HTTPS. Los ejemplos usan curl, Python con requests y JavaScript con Node.js 22 o superior.

• Un prompt. Es obligatorio y admite hasta 20 000 caracteres; uno vacío recibe 400 y no se cobra.

Esta guía es la de Nano Banana Pro; la de Nano Banana 2.1 es otra guía de inicio rápido.

02¿Cómo envías la primera solicitud?

Todo empieza con un POST a /images/generate, con Authorization: Bearer y tu clave. El cuerpo lleva model y prompt; resolution y aspect_ratio son opcionales. Los ejemplos piden 1K y relación 1:1, con el prompt que dio las imágenes de esta guía.

X-Idempotency-Key lleva una clave nueva por cada imagen nueva; si repites la misma solicitud porque no llegó la respuesta, envía la misma clave y no pagas dos veces. Hay más en reintentos sin doble cargo, y todos los campos están en Crear una imagen.

# Hacen falta bash, curl y uuidgen. La clave de idempotencia es una por solicitud.
IDEMPOTENCY_KEY="$(uuidgen)" || exit 1
curl --fail-with-body --max-time 30 \
  -X POST https://api.rendergrid.io/api/public/v1/images/generate \
  -H "Authorization: Bearer $RENDERGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "Frasco rectangular ámbar de perfume, abierto, sobre papel gris carbón plegado; la tapa redondeada descansa aparte a un lado. El cuello se ve con claridad. Luz desde arriba a la derecha para crear un reflejo dorado fino y sombra en el pliegue. Ambos objetos completos, con márgenes amplios. Sin texto, logotipos, personas ni marcas de agua.",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'

import os
import uuid
import requests

key = os.environ["RENDERGRID_API_KEY"]
payload = {
    "model": "nano-banana-pro",
    "prompt": "Frasco rectangular ámbar de perfume, abierto, sobre papel gris carbón plegado; la tapa redondeada descansa aparte a un lado. El cuello se ve con claridad. Luz desde arriba a la derecha para crear un reflejo dorado fino y sombra en el pliegue. Ambos objetos completos, con márgenes amplios. Sin texto, logotipos, personas ni marcas de agua.",
    "resolution": "1K",
    "aspect_ratio": "1:1",
}
response = requests.post(
    "https://api.rendergrid.io/api/public/v1/images/generate",
    headers={
        "Authorization": f"Bearer {key}",
        # nueva en cada imagen nueva; al repetir la misma solicitud, la misma
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
    timeout=(10, 120),
)
response.raise_for_status()
creation = response.json()
print(creation["id"], creation["status"], creation["cost"])

// Node.js 22+, archivo .mjs
import { randomUUID } from "node:crypto";

const API = "https://api.rendergrid.io/api/public/v1";
const prompt =
  "Frasco rectangular ámbar de perfume, abierto, sobre papel gris carbón plegado; la tapa redondeada descansa aparte a un lado. El cuello se ve con claridad. Luz desde arriba a la derecha para crear un reflejo dorado fino y sombra en el pliegue. Ambos objetos completos, con márgenes amplios. Sin texto, logotipos, personas ni marcas de agua.";
const response = await fetch(`${API}/images/generate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`,
    "Content-Type": "application/json",
    // nueva en cada imagen nueva; al repetir la misma solicitud, la misma
    "X-Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "nano-banana-pro",
    prompt,
    resolution: "1K",
    aspect_ratio: "1:1",
  }),
  signal: AbortSignal.timeout(120_000),
});
if (response.status !== 202) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const creation = await response.json();
console.log(creation.id, creation.status, creation.cost);

La respuesta es 202 Accepted: «solicitud aceptada», no «imagen lista». Guarda el id: con él consultas el resultado. cost es el importe cargado por la imagen, en dólares estadounidenses, escrito como número.

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "queued",
  "task_id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "cost": 0.04
}

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "processing"
}

03¿Cómo compruebas el estado y recoges el resultado?

El 202 solo confirma que la tarea quedó aceptada; la imagen se genera en segundo plano. Consulta GET /creations/{id} con tu id. El estado pasa por queued (en cola), processing (en proceso), completed (lista, con result_urls) y failed (sin imagen). Los dos últimos son finales: al verlos, deja de consultar.

Consulta como máximo una vez cada 5 segundos por tarea; una consulta más temprana recibe 429. No hay un plazo prometido de generación: depende del modelo y de la carga. Tiempo promedio de espera de los últimos 7 días — 39 s. Limita el tiempo total de espera en tu código: si se agota, guarda el id y sigue más tarde, porque tu tiempo de espera agotado no cancela la tarea.

CREATION_ID="5b0214ae-9e39-460a-820a-f6ae3e24400b"  # el id de la respuesta 202
curl --fail-with-body --max-time 20 \
  "https://api.rendergrid.io/api/public/v1/creations/$CREATION_ID" \
  -H "Authorization: Bearer $RENDERGRID_API_KEY"

import os
import time
import requests

API = "https://api.rendergrid.io/api/public/v1"
key = os.environ["RENDERGRID_API_KEY"]
headers = {"Authorization": f"Bearer {key}"}
creation_id = "5b0214ae-9e39-460a-820a-f6ae3e24400b"  # el id de la respuesta 202

while True:
    r = requests.get(f"{API}/creations/{creation_id}", headers=headers, timeout=(5, 20))
    r.raise_for_status()
    creation = r.json()
    if creation["status"] in ("completed", "failed"):
        break
    time.sleep(5)  # como máximo una consulta cada 5 segundos

if creation["status"] == "completed":
    print(creation["result_urls"])
else:
    print(creation["error"], creation["failure"])

// Node.js 22+, archivo .mjs
const API = "https://api.rendergrid.io/api/public/v1";
const headers = { Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}` };
const creationId = "5b0214ae-9e39-460a-820a-f6ae3e24400b"; // el id de la respuesta 202

let creation;
do {
  // como máximo una consulta cada 5 segundos
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const res = await fetch(`${API}/creations/${creationId}`, { headers });
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  }
  creation = await res.json();
} while (["queued", "processing"].includes(creation.status));

console.log(creation.status);
console.log(creation.result_urls ?? creation.error);

El ejemplo de curl consulta una sola vez; repítelo a mano o en un bucle. Así se ven la respuesta final y la de una consulta demasiado temprana:

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "completed",
  "result_urls": [
    "https://…"
  ]
}

{
  "error": {
    "code": "ERR_RATE_LIMIT",
    "message": "polled too soon — retry after the minimum interval",
    "details": { "min_interval_seconds": 5 }
  }
}

Guarda la imagen cuando llegue completed: los enlaces de result_urls valen un día y después el archivo se elimina. Úsalos tal cual. Una respuesta 200 puede traer status: "failed": es el resultado de la tarea, no un error de la consulta.

En lugar de consultar, pasa webhook_url en la solicitud, una dirección HTTPS pública de hasta 2 048 caracteres, y te avisamos cuando la tarea pasa a completed o failed. Deja la consulta como reserva: el aviso puede retrasarse o no llegar. Más en Webhooks y en generación por lotes, webhooks e idempotencia.

04¿Qué cambia entre 1K, 2K y 4K?

resolution acepta 1K, 2K y 4K; para cambiarla, modifica solo ese valor del cuerpo, por ejemplo "resolution": "2K". No es un número libre de píxeles: width y height no se aceptan. Con relación 1:1, las tres imágenes de esta guía miden 1 024 × 1 024, 2 048 × 2 048 y 4 096 × 4 096 píxeles.

aspect_ratio admite 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 5:4, 4:5 y 21:9, además de auto; no hay relaciones extremas como 1:4 o 1:8. Si falta, será 1:1. Un valor no admitido recibe 400 antes del cargo.

Estas tres imágenes salen del mismo prompt, con relación 1:1 y un solo intento por resolución.

Prompt: frasco de perfume ámbar

Frasco rectangular ámbar de perfume, abierto, sobre papel gris carbón plegado; la tapa redondeada descansa aparte a un lado. El cuello se ve con claridad. Luz desde arriba a la derecha para crear un reflejo dorado fino y sombra en el pliegue. Ambos objetos completos, con márgenes amplios. Sin texto, logotipos, personas ni marcas de agua.

1K, 2K y 4K, 1:1, un intento por resoluciónCopiar prompt

No son ampliaciones de una misma imagen: cada solicitud genera una imagen nueva, y por eso cambia la composición. El prompt no fija el ángulo ni la posición del frasco, y cada intento eligió una disposición: en 1K, inclinado en diagonal; en 2K, tumbado con el cuello hacia la cámara; en 4K, visto desde arriba.

Compara también cada imagen con el prompt, que pide un frasco abierto con el cuello a la vista y luz desde arriba a la derecha. Las de 1K y 2K enseñan el cuello con su rosca, sin pulverizador; la de 4K lleva uno montado y sus sombras caen hacia la derecha. En 1K el papel de la derecha es gris claro y en 2K el que queda bajo los objetos se ve pardo, no gris carbón. Son desviaciones de esos intentos, no una regla de cada resolución.

05¿Cuánto cuesta cada resolución?

El precio de una imagen de Nano Banana Pro depende de la resolución: $0,04 en 1K, $0,04 en 2K y $0,07 en 4K. Se cobra al aceptar la solicitud y llega en el campo cost de la respuesta 202.

Una solicitud sin resolution se genera y se cobra en 2K, la resolución predeterminada de Nano Banana Pro.

Los precios de todos los modelos están en la página de precios; la comparativa con el precio oficial del fabricante, en el precio de la API de Nano Banana Pro. Precios verificados el 26 de octubre de 2026.

06¿Qué hacer si la solicitud falla?

Una solicitud puede fallar en tres momentos:

1. Antes del cargo. Un 400 ERR_INVALID_REQUEST no cobra nada: falta el prompt o está vacío, o el modelo no admite la resolution o la aspect_ratio. error.details indica qué corregir.
2. Al aceptarla. Sin saldo suficiente, o con el límite mensual de la clave agotado, llega 402 ERR_INSUFFICIENT_BALANCE. Con más de 120 solicitudes por minuto, 429 ERR_RATE_LIMIT; con 100 generaciones en cola o en proceso, 429 ERR_QUOTA_EXCEEDED. Espera como mínimo lo que indique Retry-After; hay más en Límites y en cómo tratar un error 429.
3. Con la tarea ya aceptada. El estado pasa a failed, con error (un texto para mostrar) y failure (type, code y retryable). Basa tu lógica en failure, no en el texto de error.

Una solicitud fallida es gratis: el importe vuelve de inmediato al saldo. Un intento nuevo es una solicitud nueva con una clave de idempotencia nueva, y se paga como cualquier otra. Repetir una solicitud ya aceptada con la misma clave devuelve la misma respuesta 202, con los mismos id, status, task_id y cost, que puede seguir diciendo queued; no reinicia una tarea que ya pasó a failed. Cómo se devuelve el importe se explica en la guía de la solicitud fallida.

07¿Qué no cubre este artículo?

• Tres imágenes no son una medición. Son tres intentos con un mismo prompt, uno por resolución: no dicen nada de velocidad ni de fiabilidad.
• Un intento por resolución. No medimos cuánto varía un intento de otro; las composiciones de arriba ya difieren mucho.
• Solo la relación 1:1 y solo texto a imagen. Las demás relaciones de aspecto no se probaron aquí, y para imágenes de referencia está Imágenes de referencia.
• Sin tiempos de generación. No prometemos ninguno.

08Preguntas frecuentes

09Fuentes

1. Documentación de Rendergrid: inicio rápidoClave, solicitud, estado y descarga.
2. Documentación de Rendergrid: crear una imagenCampos y comprobaciones previas al cargo.
3. Documentación de Rendergrid: tareas y estadosEstados, respuestas y frecuencia de consulta.
4. Documentación de Rendergrid: modelos y parámetrosResoluciones y relaciones de aspecto.
5. Documentación de Rendergrid: reintentos sin doble cargoLa clave de idempotencia.
6. Precios de RendergridPrecio por imagen de cada modelo y resolución.
7. Las imágenes de esta guíaCada pie indica el modelo, la resolución y la relación de aspecto.