Crear una imagen

01Solicitud

Envía un JSON con los encabezados Authorization y Content-Type: application/json. Para cada imagen nueva usa un X-Idempotency-Key nuevo y, al repetir la misma solicitud, el anterior: así no pagarás dos veces (más información).

# 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": "Taza de cerámica sobre mármol, luz suave de ventana",
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'

import os
import uuid
import requests

key = os.environ["RENDERGRID_API_KEY"]
payload = {
    "model": "nano-banana-pro",
    "prompt": "Taza de cerámica sobre mármol, luz suave de ventana",
    "resolution": "2K",
    "aspect_ratio": "16:9",
}
response = requests.post(
    "https://api.rendergrid.io/api/public/v1/images/generate",
    headers={
        "Authorization": f"Bearer {key}",
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
    timeout=(10, 120),
)
response.raise_for_status()
creation = response.json()  # 202: {id, status, task_id, cost}
print(creation["id"])

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

const API = "https://api.rendergrid.io/api/public/v1";
const response = await fetch(`${API}/images/generate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`,
    "Content-Type": "application/json",
    "X-Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "nano-banana-pro",
    prompt: "Taza de cerámica sobre mármol, luz suave de ventana",
    resolution: "2K",
    aspect_ratio: "16:9",
  }),
  signal: AbortSignal.timeout(120_000),
});
if (response.status !== 202) {
  const body = await response.text();
  throw new Error(`HTTP ${response.status}: ${body}`);
}
// respuesta 202: {id, status, task_id, cost}
const creation = await response.json();
console.log(creation.id);

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

id

Identificador de la tarea. Con él obtendrás el resultado: Tareas y estados.

status

Justo después de aceptarse, queued.

task_id

Identificador de la tarea. En GET /creations/{id} usa id.

cost

El importe cargado por la imagen, en dólares: un número con precisión de hasta cuatro decimales.

202 Accepted significa «solicitud aceptada», no «imagen lista».

02Construye la solicitud

Construye el cuerpo de la solicitud y mira el precio. Cada modelo tiene sus propias resoluciones y relaciones de aspecto. Una opción en gris no se puede elegir: púlsala y verás la respuesta con la que la API la rechazaría, sin hacer ningún cargo.

{
  "model": "nano-banana-pro",
  "prompt": "Taza de cerámica sobre mármol, luz suave de ventana",
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

03Campos de la solicitud

El tamaño de la imagen lo define resolution: es el nivel de tamaño del modelo, no un número exacto de píxeles. Los campos width y height no se aceptan. Si necesitas un tamaño exacto, mira las dimensiones del archivo recibido.

04Qué se comprueba antes del cargo

Estas comprobaciones se hacen antes del cargo. Si la API respondió 400 ERR_INVALID_REQUEST, el saldo no cambió y error.details indica qué corregir.

• Falta prompt, está vacío o solo tiene espacios.
• El modelo elegido no tiene la resolution o la aspect_ratio indicada: details.supported trae la lista de valores admitidos.
• Se envía n mayor que 1, o bien width o height.
• Hay una máscara (mask, mask_file_id): las máscaras no se admiten. Envía la imagen original como imagen de referencia y describe la edición en el prompt.
• Imágenes de referencia de dos familias a la vez (por ejemplo, image_file_ids e image_urls) o más de 14.
• La dirección webhook_url no es válida o está prohibida.

05Precio y cargo

El precio depende del modelo y de la resolución. Por ejemplo, Nano Banana Pro cuesta $0,04 en 1K y $0,07 en 4K, y GPT Image 2, $0,02 por imagen. Todos los precios, en dólares estadounidenses, están en la página «Modelos y parámetros» y en la respuesta de GET /models.

El cargo se hace al aceptar la solicitud, antes de empezar el trabajo, y llega en el campo cost. Puedes comprobar el saldo con la solicitud GET /balance.

06Qué sigue