Solicitudes síncronas y asíncronas
Dos formas de llamar a la API de imágenes: espera la imagen en una solicitud, o envía async true, recibe un id de tarea al instante y consulta tareas o usa un webhook.
Hay dos formas de crear una imagen. Aceptan los mismos parámetros, cuestan lo mismo y comparten los mismos límites; elige en cada solicitud.
| Síncrona (por defecto) | Asíncrona | |
|---|---|---|
| Cómo | Envía la solicitud y espera | Añade async: true, recibe al instante un id de tarea |
| La respuesta llega | En la misma respuesta, tras entre 20 segundos y unos minutos | Más tarde: consultas tú, o llamamos a tu webhook |
| Conexión abierta | Hasta que la imagen está lista | Menos de un segundo |
| Ejecución más larga | 7 minutos | 10 minutos |
| Devuelve | Datos de la imagen (b64_json) o un enlace (url) | Un enlace (url) |
| Funciona con | Los SDK de OpenAI y cualquier herramienta hecha para la API OpenAI Images | Cualquier cliente HTTP |
| Bueno para | Scripts, back ends, una imagen cada vez | Páginas web, muchas imágenes a la vez, modelos lentos, funciones serverless con límites de tiempo cortos |
Las tres llamadas
| Llamada | Qué hace |
|---|---|
POST /v1/images/generations o /v1/images/edits con async: true | Inicia una tarea. Responde 202 con el id de la tarea |
GET /v1/images/tasks?ids=a,b,c | El estado de hasta 100 tareas en una solicitud |
GET /v1/images/tasks/{id} | El estado de una tarea |
1. Inicia una tarea
Añade async: true al cuerpo de POST /v1/images/generations, o como campo de formulario en POST /v1/images/edits.
curl https://api.cheapestimagen.com/v1/images/generations \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true}'La respuesta es 202 Accepted, en mucho menos de un segundo:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}Guarda el id. Tres cosas que debes saber:
- Solo enlaces. Las imágenes de una tarea se devuelven como enlaces, así que omite
response_formato ponlo enurl.b64_jsonse rechaza con un400. - Las solicitudes incorrectas fallan aquí, no después. Un parámetro incorrecto (
400), créditos insuficientes (402) o demasiadas solicitudes (429) se responden al instante, como en una solicitud síncrona. No se crea ninguna tarea. - ¿Sin campo en el cuerpo? La cabecera
Prefer: respond-asynchace lo mismo queasync: true.
2. Lee las tareas
Varias tareas en una solicitud
Cuando esperas más de una tarea, pídelas todas a la vez. Una página que inició 10 tareas envía una solicitud de consulta, no 10.
curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
-H "Authorization: Bearer YOUR_KEY"{
"object": "list",
"data": [
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "succeeded",
"created": 1795062073,
"finished": 1795062098,
"model": "gpt-image-2.6",
"result": {
"created": 1795062098,
"data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
}
},
{
"id": "req_26e50328772b7d62f59d355a",
"object": "image.task",
"status": "in_progress",
"created": 1795062074,
"finished": null,
"model": "gpt-image-2.6"
}
],
"not_found": []
}idsadmite hasta 100 ids de tarea, separados por comas.datacontiene las tareas en el orden en que las pediste.- Un id que no es una tarea de tu cuenta, o cuyas imágenes ya no se conservan, aparece en
not_found. No hace fallar la solicitud.
Una tarea
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"La respuesta es el objeto de la tarea solo. Un id desconocido responde 404.
Qué dice una tarea
status | Significado | Campo adicional |
|---|---|---|
in_progress | Se está creando la imagen | ninguno |
succeeded | Terminada | result: exactamente lo que habría devuelto la llamada síncrona, { created, data: [{ url }] } |
failed | No funcionó | error: exactamente el error que habría devuelto la llamada síncrona |
Una tarea fallida tiene este aspecto:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "failed",
"created": 1795062073,
"finished": 1795062110,
"model": "gpt-image-2.6",
"error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}Una tarea fallida no se cobra. La única excepción es la misma que en las solicitudes síncronas: un rechazo en los canales estables de Nano Banana.
Cada cuánto consultar
Basta con cada 2 a 5 segundos. Leer tareas es gratis y no es una solicitud de imagen: no cuenta para las solicitudes en curso. Una tarea se puede leer durante 72 horas, mientras se conserven sus imágenes.
Ejemplo: una página web que inicia 10 imágenes
Una solicitud por imagen para iniciarlas y después una solicitud cada 3 segundos para todas.
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// Inicia 10 tareas.
const prompts = Array.from({ length: 10 }, (_, i) => `a red fox in the snow, variation ${i + 1}`);
const started = await Promise.all(prompts.map((prompt) =>
fetch(`${API}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
}).then((r) => r.json())
));
// Consulta todas con una sola solicitud hasta que ninguna esté en curso.
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
await new Promise((r) => setTimeout(r, 3000));
const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
waiting = waiting.filter((id) => !done[id]);
}
for (const task of Object.values(done)) {
console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}No pongas tu clave de API en una página web pública. Llama a la API desde tu propio servidor y deja que la página hable con él.
Ejemplo: Python
import time, requests
API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
ids = [
requests.post(f"{API}/images/generations", headers=HEADERS, json={
"model": "gpt-image-2.6", "prompt": f"a red fox in the snow, variation {i}", "async": True,
}).json()["id"]
for i in range(10)
]
done = {}
while len(done) < len(ids):
time.sleep(3)
waiting = [i for i in ids if i not in done]
tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})
for t in done.values():
print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])Con el SDK de OpenAI, pasa el campo mediante extra_body={"async": True} y lee las tareas con una solicitud HTTP normal.
Webhook en lugar de consulta
Añade webhook_url y nosotros enviamos con POST la tarea terminada a esa dirección:
{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }- La dirección debe ser
https://en un nombre de host público. - El cuerpo es el objeto de la tarea, el mismo JSON que
GET /v1/images/tasks/{id}. - Responde con cualquier
2xxen 10 segundos. Si no, lo intentamos dos veces más, a los 3 y a los 15 segundos, y después paramos. - Para que la llamada vaya firmada, envía con la solicitud un secreto propio como
webhook_secret(de 16 a 128 caracteres). Sin él la llamada no va firmada: trátala como un aviso, toma elidy lee la tarea con tu clave antes de fiarte del contenido. - La tarea sigue siendo legible haya llegado o no el webhook, así que una llamada perdida no hace perder nada.
Comprueba la firma
Con webhook_secret, la llamada lleva la cabecera x-webhook-signature: t=1763560000,v1=5f2b…. t es la hora de la llamada en segundos Unix, y v1 es el HMAC-SHA256, en hexadecimal, del texto <t>.<body> calculado con tu secreto. Calcula el mismo valor a partir del cuerpo bruto de la solicitud y compáralo; rechaza las llamadas cuyo t tenga más de unos minutos.
import hashlib, hmac, time
def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300import { createHmac, timingSafeEqual } from 'node:crypto';
function isOurs(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}Usa el cuerpo exactamente como llegó, antes de analizar el JSON. El secreto se usa para esta única solicitud y no se guarda con tu cuenta.
Límites
Una solicitud asíncrona cuenta como una síncrona: 300 solicitudes por minuto y 50 en curso por cuenta. Una solicitud enviada mientras hay 50 en ejecución se rechaza con 429; espera a que termine una. Leer tareas no se cuenta.
Idempotency-Key funciona igual: mientras una solicitud con esa clave está en curso o después de que tuviera éxito, una repetición responde 409.
Proporciones y tamaños
Los tamaños de imagen que puedes pasar en el campo size de la API de Cheapest Imagen: hasta 19 proporciones en 1K, 2K y 4K, y tamaños personalizados.
Límites de uso y generación masiva
Los límites de la API de Cheapest Imagen (300 por minuto, 50 a la vez), qué significa un 429 y cómo generar miles de imágenes con reintentos que nunca cobran dos veces.