Generación por lotes: cola, webhooks y clave de idempotencia

import os
import threading
import time
from concurrent.futures import ThreadPoolExecutor

import requests

API = "https://api.rendergrid.io/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['RENDERGRID_API_KEY']}"}
IN_FLIGHT = 20  # tareas a la vez; la cuenta admite 100 en cola o en proceso
SEND_EVERY = 0.6  # segundos entre envíos: 100 por minuto, bajo el límite de 120
POLL_EVERY = 5  # como máximo una consulta cada 5 segundos por tarea
MAX_WAIT = 300  # ajuste del ejemplo, no un plazo del modelo

PROMPTS = [
    "Tubo blanco liso sobre una base durazno, frente a un panel en arco",
    "Tubo blanco liso sobre un bloque durazno, junto a unos peldaños bajos",
    "Tubo blanco liso sobre una base redonda, delante de un disco grande",
]
jobs = [
    {
        "key": f"catalog-8412-{n}",  # una clave por operación, guardada con el lote
        "payload": {
            "model": "nano-banana-2.1",
            "prompt": prompt,
            "resolution": "1K",
            "aspect_ratio": "1:1",
        },
        "id": None,
        "result": None,
    }
    for n, prompt in enumerate(PROMPTS, start=1)
]

pace = threading.Lock()
next_send = 0.0


def wait_turn():
    global next_send
    with pace:
        now = time.monotonic()
        start = max(now, next_send)
        next_send = start + SEND_EVERY
    time.sleep(start - now)


def submit(job):
    headers = {**HEADERS, "X-Idempotency-Key": job["key"]}
    for attempt in range(5):
        wait_turn()
        resp = requests.post(
            f"{API}/images/generate", headers=headers, json=job["payload"], timeout=(5, 30)
        )
        if resp.status_code == 202:
            return resp.json()["id"]
        if resp.status_code != 429 or attempt == 4:
            raise RuntimeError(f"HTTP {resp.status_code}")
        # 429: esperar al menos Retry-After y repetir con la misma clave
        wait = resp.headers.get("Retry-After", "")
        time.sleep((int(wait) if wait.isdigit() else 2) + 1)


def run(job):
    try:
        if job["id"] is None:
            job["id"] = submit(job)
        deadline = time.monotonic() + MAX_WAIT
        while time.monotonic() < deadline:
            time.sleep(POLL_EVERY)
            resp = requests.get(
                f"{API}/creations/{job['id']}", headers=HEADERS, timeout=(5, 20)
            )
            if resp.status_code == 200 and resp.json()["status"] in ("completed", "failed"):
                job["result"] = resp.json()
                return
    except (requests.RequestException, RuntimeError):
        pass  # la operación queda en el registro sin resultado


with ThreadPoolExecutor(max_workers=IN_FLIGHT) as pool:
    list(pool.map(run, jobs))

pending = [job for job in jobs if job["result"] is None]
print(f"{len(jobs) - len(pending)} terminadas, {len(pending)} por revisar")

// Node.js 22+, archivo .mjs
const API = "https://api.rendergrid.io/api/public/v1";
const HEADERS = { Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}` };
const IN_FLIGHT = 20; // tareas a la vez; la cuenta admite 100 en cola o en proceso
const SEND_EVERY = 600; // ms entre envíos: 100 por minuto, bajo el límite de 120
const POLL_EVERY = 5_000; // como máximo una consulta cada 5 segundos por tarea
const MAX_WAIT = 300_000; // ajuste del ejemplo, no un plazo del modelo
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const PROMPTS = [
  "Tubo blanco liso sobre una base durazno, frente a un panel en arco",
  "Tubo blanco liso sobre un bloque durazno, junto a unos peldaños bajos",
  "Tubo blanco liso sobre una base redonda, delante de un disco grande",
];
const jobs = PROMPTS.map((prompt, n) => ({
  key: `catalog-8412-${n + 1}`, // una clave por operación, guardada con el lote
  payload: { model: "nano-banana-2.1", prompt, resolution: "1K", aspect_ratio: "1:1" },
  id: null,
  result: null,
}));

let nextSend = 0;
async function waitTurn() {
  const start = Math.max(Date.now(), nextSend);
  nextSend = start + SEND_EVERY;
  await sleep(start - Date.now());
}

async function submit(job) {
  for (let attempt = 0; attempt < 5; attempt++) {
    await waitTurn();
    const resp = await fetch(`${API}/images/generate`, {
      method: "POST",
      headers: { ...HEADERS, "Content-Type": "application/json", "X-Idempotency-Key": job.key },
      body: JSON.stringify(job.payload),
      signal: AbortSignal.timeout(30_000),
    });
    if (resp.status === 202) return (await resp.json()).id;
    if (resp.status !== 429 || attempt === 4) throw new Error(`HTTP ${resp.status}`);
    // 429: esperar al menos Retry-After y repetir con la misma clave
    const wait = Number(resp.headers.get("Retry-After"));
    await sleep((wait > 0 ? wait : 2) * 1_000 + 1_000);
  }
}

async function run(job) {
  try {
    job.id ??= await submit(job);
    const deadline = Date.now() + MAX_WAIT;
    while (Date.now() < deadline) {
      await sleep(POLL_EVERY);
      const resp = await fetch(`${API}/creations/${job.id}`, {
        headers: HEADERS,
        signal: AbortSignal.timeout(20_000),
      });
      if (!resp.ok) continue;
      const data = await resp.json();
      if (["completed", "failed"].includes(data.status)) {
        job.result = data;
        return;
      }
    }
  } catch {
    // la operación queda en el registro sin resultado
  }
}

const queue = [...jobs];
await Promise.all(
  Array.from({ length: IN_FLIGHT }, async () => {
    for (let job = queue.shift(); job; job = queue.shift()) await run(job);
  }),
);

const pending = jobs.filter((job) => job.result === null);
console.log(`${jobs.length - pending.length} terminadas, ${pending.length} por revisar`);

# Con webhook_url, Rendergrid avisa a esa dirección cuando la tarea termina
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: catalog-8412-1" \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "Tubo blanco liso sobre una base durazno, luz suave desde la izquierda",
    "resolution": "1K",
    "aspect_ratio": "1:1",
    "webhook_url": "https://example.com/webhooks/rendergrid"
  }'

import hashlib
import hmac
import json
import os
import queue
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["WEBHOOK_SECRET"].encode("utf-8")  # el secreto completo, con whsec_
TOLERANCE = 300  # segundos, como en los ejemplos de la documentación
events = queue.Queue()  # otro proceso descarga las imágenes
seen = set()  # en producción, un almacén persistente


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        timestamp = self.headers.get("X-Timestamp", "")
        signature = self.headers.get("X-Webhook-Signature-256", "")
        signed = timestamp.encode("ascii", "ignore") + b"." + raw
        expected = "sha256=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
        fresh = (
            timestamp.isascii()
            and timestamp.isdigit()
            and abs(time.time() - int(timestamp)) <= TOLERANCE
        )
        if not (fresh and signature.isascii() and hmac.compare_digest(expected, signature)):
            return self.reply(401)
        try:
            event = json.loads(raw)
        except ValueError:
            return self.reply(400)
        marker = (event.get("id"), event.get("event"))
        if event.get("id") != "test" and marker not in seen:
            seen.add(marker)
            events.put(event)
        self.reply(200)

    def reply(self, status):
        self.send_response(status)
        self.send_header("Content-Length", "0")
        self.end_headers()


HTTPServer(("", 8080), Receiver).serve_forever()

// Node.js 22+, archivo .mjs
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = Buffer.from(process.env.WEBHOOK_SECRET, "utf8"); // el secreto completo, con whsec_
const TOLERANCE = 300; // segundos, como en los ejemplos de la documentación
const events = []; // otro proceso descarga las imágenes
const seen = new Set(); // en producción, un almacén persistente

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const raw = Buffer.concat(chunks);
  const timestamp = req.headers["x-timestamp"] ?? "";
  const signature = req.headers["x-webhook-signature-256"] ?? "";
  const expected =
    "sha256=" +
    createHmac("sha256", SECRET).update(`${timestamp}.`, "ascii").update(raw).digest("hex");
  const fresh =
    /^[0-9]{1,12}$/.test(timestamp) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE;
  const a = Buffer.from(expected, "ascii");
  const b = Buffer.from(signature, "ascii");
  if (!fresh || a.length !== b.length || !timingSafeEqual(a, b)) {
    res.writeHead(401).end();
    return;
  }
  let event;
  try {
    event = JSON.parse(raw.toString("utf8"));
  } catch {
    res.writeHead(400).end();
    return;
  }
  const marker = `${event.id}:${event.event}`;
  if (event.id !== "test" && !seen.has(marker)) {
    seen.add(marker);
    events.push(event);
  }
  res.writeHead(200).end();
}).listen(8080);

# Si no llega respuesta, repite este mismo comando: misma clave y mismo cuerpo
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: catalog-8412-1" \
  -d '{
    "model": "nano-banana-2.1",
    "prompt": "Tubo blanco liso sobre una base durazno, luz suave desde la izquierda",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'

import os

import requests

API = "https://api.rendergrid.io/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['RENDERGRID_API_KEY']}"}


def send(payload, key):
    return requests.post(
        f"{API}/images/generate",
        headers={**HEADERS, "X-Idempotency-Key": key},
        json=payload,
        timeout=(5, 30),
    )


payload = {
    "model": "nano-banana-2.1",
    "prompt": "Tubo blanco liso sobre una base durazno, luz suave desde la izquierda",
    "resolution": "1K",
    "aspect_ratio": "1:1",
}
key = "catalog-8412-1"  # el número de operación de tu sistema, guardado antes de enviar
try:
    resp = send(payload, key)
except (requests.Timeout, requests.ConnectionError):
    # No sabes si la solicitud llegó: repite con la misma clave y el mismo cuerpo
    resp = send(payload, key)
resp.raise_for_status()
print(resp.json()["id"])

// Node.js 22+, archivo .mjs
const API = "https://api.rendergrid.io/api/public/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.RENDERGRID_API_KEY}`,
  "Content-Type": "application/json",
};

async function send(payload, key) {
  return fetch(`${API}/images/generate`, {
    method: "POST",
    headers: { ...HEADERS, "X-Idempotency-Key": key },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(30_000),
  });
}

const payload = {
  model: "nano-banana-2.1",
  prompt: "Tubo blanco liso sobre una base durazno, luz suave desde la izquierda",
  resolution: "1K",
  aspect_ratio: "1:1",
};
const key = "catalog-8412-1"; // el número de operación de tu sistema, guardado antes de enviar
let resp;
try {
  resp = await send(payload, key);
} catch {
  // no sabes si la solicitud llegó: repite con la misma clave y el mismo cuerpo
  resp = await send(payload, key);
}
if (resp.status !== 202) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
console.log((await resp.json()).id);