API de generación de imágenes asíncrona: Jobs, Polling, Webhooks y Retries

Una API de generación de imágenes asíncrona le permite enviar una solicitud de generación, recibir inmediatamente un identificador de trabajo y recuperar la imagen terminada más tarde, en lugar de mantener abierta una conexión HTTP. Este tutorial cubre el ciclo de vida del trabajo, cuándo usar polling frente a webhooks, y cómo diseñar reintentos para que un trabajo lento o fallido no corrompa la experiencia de su producto.

Puntos clave

• La generación de imágenes se basa en trabajos, no en solicitud-respuesta, porque la latencia de generación (de segundos a decenas de segundos) es poco fiable para mantenerla en una conexión síncrona.
• El polling es más sencillo de construir y depurar; los webhooks reducen la latencia y el volumen de solicitudes, pero requieren un endpoint público, verificación de firmas y un manejo idempotente de entregas duplicadas.
• La lógica de reintento debe distinguir entre fallos de envío, trabajos bloqueados y entregas de webhooks perdidas; cada uno necesita una ruta de recuperación diferente.
• Los nombres exactos de los endpoints, los nombres de los campos y las estructuras de los payloads de los webhooks difieren según el proveedor y la propia superficie de la API de TokenLab. Confirme siempre los detalles actuales en docs.tokenlab.sh antes de realizar el despliegue.

Por qué las APIs de generación de imágenes son asíncronas

Las APIs de completado de texto a menudo pueden devolver una respuesta en la misma conexión porque la generación de tokens es lo suficientemente rápida como para hacer streaming. Los modelos de generación de imágenes, ya sean basados en difusión o autorregresivos, suelen tardar más y tienen una latencia más variable dependiendo de la resolución, la elección del modelo y la profundidad de la cola. Mantener abierta una solicitud HTTP síncrona durante decenas de segundos es frágil: los tiempos de espera del cliente, los límites de inactividad del balanceador de carga y las caídas de la red móvil aumentan la posibilidad de perder un resultado completado por el que ya pagó para generar.

El patrón estándar, utilizado por los proveedores de generación de imágenes, es un modelo de trabajo: usted envía una solicitud y recibe un identificador de trabajo y un estado inicial (comúnmente algo como queued o processing). Luego, usted realiza polling a un endpoint de estado o recibe una notificación por webhook cuando el trabajo alcanza un estado terminal, y obtiene las URLs finales de la imagen o los datos binarios en una llamada separada.

TokenLab expone el acceso a múltiples modelos de imagen, incluyendo la familia Nano Banana 2, Nano Banana Pro y Nano Banana 2 Lite, GPT Image 2, Reve 2.0 y MAI-Image-2.5, a través de una única superficie de API. Consulte el directorio de modelos de imagen para ver la lista actual y la guía de tareas de generación de imágenes asíncronas para conocer el comportamiento del endpoint de trabajo específico de TokenLab. El patrón general a continuación se aplica independientemente del modelo subyacente que llame, pero los nombres exactos de los campos y los valores de estado están documentados en docs.tokenlab.sh y deben verificarse allí en lugar de asumirlos a partir de este artículo.

El ciclo de vida del trabajo: Enviar, hacer Polling, Recuperar

A nivel conceptual, un trabajo de imagen asíncrono tiene tres etapas:

1. Enviar (Submit): POST con un prompt y parámetros, recibe un ID de trabajo y un estado inicial.
2. Verificar estado (Check status): ya sea haciendo polling a un endpoint GET usando el ID del trabajo, o esperando un evento de webhook.
3. Recuperar salida (Retrieve output): una vez que el estado es terminal (succeeded o failed), obtenga la(s) URL(s) de la imagen o el detalle del error.

Aquí hay un patrón de polling ilustrativo en Python. Trate las rutas de los endpoints y los nombres de los campos como marcadores de posición; confirme la forma actual del endpoint de trabajo de TokenLab en la documentación de la API antes de usar esto en producción.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # verifique la URL base actual en docs.tokenlab.sh
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit_image_job(prompt, model="nano-banana-2"):
    resp = requests.post(
        f"{API_BASE}/images/jobs",
        headers=HEADERS,
        json={"prompt": prompt, "model": model, "idempotency_key": generate_key()},
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

def poll_job(job_id, max_wait_seconds=120, interval=2, backoff=1.5):
    waited = 0
    while waited < max_wait_seconds:
        resp = requests.get(f"{API_BASE}/images/jobs/{job_id}", headers=HEADERS)
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        waited += interval
        interval = min(interval * backoff, 15)
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait_seconds}s")

job_id = submit_image_job("a studio product shot on white background")
result = poll_job(job_id)
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
else:
    print("job failed:", result.get("error"))

La idempotency_key en la llamada de envío es importante: si ocurre un error de red después de que se creó el trabajo pero antes de que su cliente recibiera el ID del trabajo, reintentar la llamada de envío con la misma clave debería devolver el trabajo existente en lugar de crear una generación duplicada. Confirme si el endpoint de trabajo de TokenLab admite claves de idempotencia en los documentos actuales, ya que este es un patrón común pero no universal entre los proveedores.

Polling vs. Webhooks: Ventajas y desventajas

Ambos enfoques son válidos; la elección correcta depende de su patrón de tráfico y su infraestructura.

El Polling es más sencillo de implementar y probar localmente, no requiere un endpoint público y funciona bien para cargas de trabajo de bajo volumen o por lotes donde unos pocos segundos extra de latencia no importan. Sus desventajas son un suelo de latencia igual a su intervalo de polling y un volumen de solicitudes innecesario si hace polling de manera demasiado agresiva en trabajos de larga duración.

Los Webhooks envían una notificación a su servidor cuando un trabajo cambia de estado, lo que reduce la latencia y disminuye las llamadas de verificación de estado desperdiciadas. El costo es operativo: necesita un endpoint HTTPS alcanzable públicamente, verificación de firma para confirmar que el payload realmente provino del proveedor, y manejo de entregas duplicadas o fuera de orden.

La documentación de eventos de webhook de OpenAI referencia la forma general de este patrón para operaciones asíncronas: su endpoint recibe un evento con un tipo y un identificador de objeto, y la práctica recomendada es tratar el payload del webhook como una notificación para ir a buscar el estado actual del recurso a través de la API, en lugar de confiar en el cuerpo del webhook como la fuente final de verdad. Ese patrón de "pull-after-push" vale la pena adoptarlo independientemente del proveedor de imágenes que esté integrando, porque lo protege si un payload de webhook se trunca, se retrasa o se entrega más de una vez.

Implementación segura de Webhooks

Si elige webhooks para la finalización de trabajos de imagen, las siguientes prácticas reducen la posibilidad de fallos silenciosos:

• Verifique la firma en cada solicitud de webhook entrante antes de procesarla. Rechace cualquier cosa que no coincida y registre los rechazos por separado del tráfico normal para que pueda detectar rápidamente un secreto mal configurado.
• Responda rápido, procese después. Reconozca el webhook con un estado 200 tan pronto como lo haya validado, luego delegue el trabajo real (obtener la imagen, escribir en el almacenamiento, notificar a su usuario) a un trabajo en segundo plano o una cola. Los proveedores generalmente reintentan la entrega del webhook si no obtienen una respuesta 2xx oportuna, lo que puede causar un procesamiento duplicado si su manejador es lento y síncrono.
• Deduplique por ID de trabajo. Almacene los IDs de trabajo procesados (o un hash del evento) para que una entrega reintentada no regenere una notificación o reprocese una escritura de archivo.
• Vuelva a obtener el recurso usando el ID de trabajo del payload del webhook en lugar de confiar en las URLs de salida incrustadas como necesariamente finales, de acuerdo con el patrón de "pull-after-push" descrito anteriormente.

Un boceto de manejador mínimo:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # use a real store in production

@app.route("/webhooks/image-jobs", methods=["POST"])
def handle_webhook():
    if not verify_signature(request):
        abort(401)

    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("id")
    if job_id in processed_job_ids:
        return "", 200  # already handled, acknowledge and skip

    enqueue_background_task("fetch_and_store_image", job_id)
    processed_job_ids.add(job_id)
    return "", 200

Verifique los nombres exactos de los eventos de webhook, la estructura del payload y el encabezado de firma utilizados para la finalización de trabajos de imagen frente a la documentación actual del proveedor y, por separado, frente al soporte de webhooks de TokenLab como se describe en docs.tokenlab.sh, ya que estos detalles son específicos del proveedor y pueden cambiar.

Diseño de reintentos: Tres clases de fallos

Los trabajos de imagen asíncronos fallan de tres maneras distintas, y cada una necesita su propio manejo:

1. Fallos de envío: el POST para crear un trabajo devuelve un 4xx o 5xx. Para errores 5xx y de red, reintente con retroceso exponencial y jitter, reutilizando la misma clave de idempotencia para no crear trabajos duplicados. Para errores 4xx (prompt incorrecto, modelo no válido, cuota excedida), reintentar sin cambiar la solicitud solo volverá a fallar; muestre el error al llamador.
2. Trabajos bloqueados: un trabajo permanece en un estado no terminal mucho después del tiempo de generación esperado. Establezca un umbral de espera máximo por modelo (el tiempo de generación varía según el modelo y la resolución) y trate los trabajos que lo excedan como fallidos para los propósitos de su aplicación, incluso si el proveedor aún no los ha marcado formalmente como fallidos. Regístrelos por separado, ya que una tasa creciente de trabajos bloqueados a menudo indica un incidente del lado del proveedor.
3. Entregas de webhook perdidas: su endpoint estaba caído o la entrega se descartó, y nunca llega ningún evento. Es por esto que vale la pena mantener un respaldo de polling incluso en un diseño de "webhooks primero": un barrido periódico que verifique el estado de cualquier trabajo con más de unos minutos sin un estado terminal detecta trabajos cuyo webhook falló silenciosamente al llegar.

Lista de verificación de decisiones

Utilice esta lista de verificación al decidir cómo configurar la finalización de trabajos para una función de generación de imágenes.

Escenario	Enfoque recomendado	Por qué
Bajo volumen, herramienta interna o script por lotes	Polling	Más sencillo de construir; no se necesita endpoint público
Función orientada al usuario donde la latencia importa	Webhooks, con barrido de respaldo de polling	Menor latencia; el respaldo detecta entregas perdidas
Alto volumen de trabajos (miles/día)	Webhooks	Evita un volumen excesivo de solicitudes de verificación de estado
Sin capacidad para exponer un endpoint HTTPS público	Polling	Los webhooks requieren un receptor alcanzable
Necesidad de prevención estricta de duplicados	Claves de idempotencia al enviar, deduplicación por ID de trabajo al recibir	Protege contra envíos reintentados y entregas de webhook duplicadas
Múltiples modelos de imagen en una pipeline	Normalice el estado del trabajo y el manejo de errores en su propia capa	Los proveedores subyacentes (vea la comparación de modelos de imagen) no comparten taxonomías de estado idénticas

Limitaciones

Este artículo describe un patrón general para APIs de trabajos de imagen asíncronos y no afirma rutas de endpoint exactas, nombres de campos, valores de tiempo de espera o nombres de eventos de webhook para TokenLab o para cualquier proveedor de modelo subyacente específico más allá de lo citado anteriormente. Los vocabularios de estado de trabajo, los encabezados de reintento y los esquemas de firma de webhook varían entre proveedores y pueden cambiar con el tiempo; trate el código en este artículo como ilustrativo, no como código de producción para copiar y pegar, y confirme las formas actuales de solicitud y respuesta en docs.tokenlab.sh antes de realizar el despliegue. Este artículo no cubre precios, límites de tasa o garantías de rendimiento para ningún modelo específico.

Preguntas frecuentes

¿Debería usar siempre webhooks en lugar de polling? No. Los webhooks reducen la latencia y el volumen de solicitudes a un costo operativo mayor. Para casos de uso de bajo volumen o internos, el polling suele ser la opción más sencilla e igualmente fiable. Muchos sistemas de producción utilizan webhooks como ruta principal con un barrido de polling periódico como respaldo.

¿Cómo evito generaciones de imágenes duplicadas en los reintentos? Utilice una clave de idempotencia en la solicitud de envío del trabajo para que un POST reintentado después de un fallo de red devuelva el trabajo existente en lugar de crear uno nuevo. Confirme si el endpoint de creación de trabajos de su proveedor admite esto antes de confiar en ello.

¿Qué sucede si mi endpoint de webhook está caído cuando se completa el trabajo? El comportamiento depende del proveedor; algunos reintentan la entrega durante un período, otros no garantizan la reentrega. Un barrido de polling periódico para trabajos con más de unos minutos sin un estado terminal es una salvaguarda práctica independientemente de la política de reintento del proveedor.

Si está creando una función de generación de imágenes y desea comparar el acceso basado en trabajos entre múltiples modelos en una sola API, revise el directorio de modelos de imagen y la guía de tareas de generación de imágenes asíncronas, luego comience con la documentación de la API de TokenLab para confirmar los detalles actuales del endpoint y del webhook para su compilación.