API de génération d'images asynchrone : Jobs, polling, webhooks et tentatives de nouvelle exécution

Une API de génération d'images asynchrone vous permet de soumettre une demande de génération, de recevoir immédiatement un identifiant de job, et de récupérer l'image terminée plus tard, au lieu de maintenir une connexion HTTP ouverte. Ce tutoriel couvre le cycle de vie d'un job, quand utiliser le polling par rapport aux webhooks, et comment concevoir des mécanismes de nouvelle tentative (retries) afin qu'un job lent ou en échec ne corrompe pas l'expérience de votre produit.

Points clés à retenir

• La génération d'images est basée sur des jobs et non sur un modèle requête-réponse, car la latence de génération (de quelques secondes à plusieurs dizaines de secondes) est trop instable pour être maintenue sur une connexion synchrone.
• Le polling est plus simple à construire et à déboguer ; les webhooks réduisent la latence et le volume de requêtes, mais nécessitent un endpoint public, une vérification de signature et une gestion idempotente des livraisons en double.
• La logique de nouvelle tentative doit distinguer les échecs de soumission, les jobs bloqués et les livraisons de webhooks manquées ; chaque cas nécessite un chemin de récupération différent.
• Les noms exacts des endpoints, des champs et les formats de payload des webhooks diffèrent selon le fournisseur et selon la surface API de TokenLab. Confirmez toujours les spécificités actuelles sur docs.tokenlab.sh avant la mise en production.

Pourquoi les API de génération d'images sont asynchrones

Les API de complétion de texte peuvent souvent renvoyer une réponse sur la même connexion car la génération de tokens est suffisamment rapide pour être diffusée en flux (streaming). Les modèles de génération d'images, qu'ils soient basés sur la diffusion ou autorégressifs, prennent généralement plus de temps et présentent une latence plus variable en fonction de la résolution, du choix du modèle et de la profondeur de la file d'attente. Maintenir une requête HTTP synchrone ouverte pendant des dizaines de secondes est fragile : les timeouts côté client, les limites d'inactivité des équilibreurs de charge et les coupures de réseau mobile augmentent tous le risque de perdre un résultat terminé pour lequel vous avez déjà payé la génération.

Le modèle standard, utilisé par tous les fournisseurs de génération d'images, est celui du job : vous soumettez une requête et recevez un identifiant de job ainsi qu'un statut initial (généralement quelque chose comme « queued » ou « processing »). Vous interrogez ensuite un endpoint de statut (polling) ou recevez une notification par webhook lorsque le job atteint un état terminal, puis vous récupérez les URLs des images finales ou les données binaires via un appel séparé.

TokenLab expose l'accès à plusieurs modèles d'images, y compris la famille Nano Banana 2, Nano Banana Pro et Nano Banana 2 Lite, GPT Image 2, Reve 2.0 et MAI-Image-2.5, via une surface API unique. Consultez le répertoire des modèles d'images pour la liste actuelle et le guide des tâches de génération d'images asynchrones pour le comportement spécifique des endpoints de jobs de TokenLab. Le modèle général ci-dessous s'applique quel que soit le modèle sous-jacent que vous appelez, mais les noms exacts des champs et les valeurs de statut sont documentés sur docs.tokenlab.sh et doivent y être vérifiés plutôt que supposés à partir de cet article.

Le cycle de vie du job : Soumettre, Poller, Récupérer

Au niveau conceptuel, un job d'image asynchrone comporte trois étapes :

1. Soumettre : POSTez un prompt et des paramètres, recevez un ID de job et un statut initial.
2. Vérifier le statut : soit interrogez (poll) un endpoint GET en utilisant l'ID du job, soit attendez un événement webhook.
3. Récupérer la sortie : une fois que le statut est terminal (succeeded ou failed), récupérez l'URL(s) de l'image ou les détails de l'erreur.

Voici un modèle de polling illustratif en Python. Considérez les chemins d'endpoints et les noms de champs comme des espaces réservés ; confirmez la forme actuelle de l'endpoint de job de TokenLab dans la documentation de l'API avant de l'utiliser en production.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # vérifiez l'URL de base actuelle sur 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 clé idempotency_key dans l'appel de soumission est importante : si une erreur réseau survient après la création du job mais avant que votre client ne reçoive l'ID du job, réessayer l'appel de soumission avec la même clé devrait renvoyer le job existant plutôt que de créer une génération en double. Confirmez si et comment l'endpoint de job de TokenLab prend en charge les clés d'idempotence dans la documentation actuelle, car il s'agit d'un modèle courant mais pas universel parmi les fournisseurs.

Polling vs Webhooks : Compromis

Les deux approches sont valides ; le bon choix dépend de votre modèle de trafic et de votre infrastructure.

Le polling est plus simple à implémenter et à tester localement, ne nécessite aucun endpoint public et fonctionne bien pour les charges de travail à faible volume ou par lots où quelques secondes de latence supplémentaires n'ont pas d'importance. Ses inconvénients sont un seuil de latence égal à votre intervalle de polling, et un volume de requêtes inutile si vous pollez trop agressivement sur des jobs longs.

Les webhooks envoient une notification à votre serveur lorsqu'un job change d'état, ce qui réduit la latence et diminue le nombre d'appels de vérification de statut inutiles. Le coût est opérationnel : vous avez besoin d'un endpoint HTTPS accessible publiquement, d'une vérification de signature pour confirmer que la charge utile provient bien du fournisseur, et d'une gestion des livraisons en double ou dans le désordre.

La documentation des événements webhook d'OpenAI référence la forme générale de ce modèle pour les opérations asynchrones : votre endpoint reçoit un événement avec un type et un identifiant d'objet, et la pratique recommandée est de traiter la charge utile du webhook comme une notification pour aller récupérer l'état actuel de la ressource via l'API, plutôt que de faire confiance au corps du webhook comme source de vérité finale. Ce modèle « pull-after-push » mérite d'être adopté quel que soit le fournisseur d'images que vous intégrez, car il vous protège si une charge utile de webhook est tronquée, retardée ou livrée plus d'une fois.

Implémenter les webhooks en toute sécurité

Si vous choisissez les webhooks pour la fin d'un job d'image, les pratiques suivantes réduisent le risque d'échecs silencieux :

• Vérifiez la signature sur chaque requête webhook entrante avant de la traiter. Rejetez tout ce qui ne correspond pas, et enregistrez les rejets séparément du trafic normal afin de pouvoir repérer rapidement un secret mal configuré.
• Répondez rapidement, traitez plus tard. Accusez réception du webhook avec un statut 200 dès que vous l'avez validé, puis confiez le travail réel (récupérer l'image, écrire dans le stockage, notifier votre utilisateur) à un job ou une file d'attente en arrière-plan. Les fournisseurs réessaient généralement la livraison du webhook s'ils ne reçoivent pas une réponse 2xx rapide, ce qui peut provoquer un traitement en double si votre gestionnaire est lent et synchrone.
• Dédoublonnez par ID de job. Stockez les IDs de jobs traités (ou un hash de l'événement) afin qu'une livraison réessayée ne régénère pas une notification ou ne retraite pas une écriture de fichier.
• Ré-interrogez la ressource en utilisant l'ID de job de la charge utile du webhook plutôt que de faire confiance aux URLs de sortie intégrées comme étant nécessairement finales, conformément au modèle « pull-after-push » décrit ci-dessus.

Un schéma de gestionnaire minimal :

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # utilisez un vrai stockage en 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  # déjà traité, accuser réception et ignorer

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

Vérifiez les noms exacts des événements webhook, la structure de la charge utile et l'en-tête de signature utilisés pour la fin d'un job d'image par rapport à la documentation actuelle du fournisseur et, séparément, par rapport au support webhook de TokenLab tel que décrit sur docs.tokenlab.sh, car ces détails sont spécifiques au fournisseur et peuvent changer.

Conception des tentatives de nouvelle tentative : Trois classes d'échec

Les jobs d'images asynchrones échouent de trois manières distinctes, et chacune nécessite sa propre gestion :

1. Échecs de soumission : le POST pour créer un job renvoie une erreur 4xx ou 5xx. Pour les erreurs 5xx et les erreurs réseau, réessayez avec un backoff exponentiel et du jitter, en réutilisant la même clé d'idempotence pour ne pas créer de jobs en double. Pour les erreurs 4xx (mauvais prompt, modèle invalide, quota dépassé), réessayer sans modifier la requête échouera à nouveau ; affichez l'erreur à l'appelant à la place.
2. Jobs bloqués : un job reste dans un statut non terminal bien après le temps de génération attendu. Définissez un seuil d'attente maximum par modèle (le temps de génération varie selon le modèle et la résolution) et traitez les jobs qui le dépassent comme échoués pour les besoins de votre application, même si le fournisseur ne les a pas encore formellement marqués comme échoués. Enregistrez-les séparément, car un taux croissant de jobs bloqués signale souvent un incident côté fournisseur.
3. Livraisons de webhooks manquées : votre endpoint était hors ligne, ou la livraison a été abandonnée, et aucun événement n'arrive jamais. C'est pourquoi un repli sur le polling vaut la peine d'être conservé même dans une conception axée sur les webhooks : un balayage périodique qui vérifie le statut de tout job vieux de quelques minutes sans état terminal attrape les jobs dont le webhook a échoué silencieusement à arriver.

Checklist de décision

Utilisez cette checklist pour décider comment configurer la fin des jobs pour une fonctionnalité de génération d'images.

Scénario	Approche recommandée	Pourquoi
Volume faible, outil interne ou script par lots	Polling	Le plus simple à construire ; aucun endpoint public nécessaire
Fonctionnalité orientée utilisateur où la latence compte	Webhooks, avec balayage de polling en repli	Latence plus faible ; le repli attrape les livraisons manquées
Volume de jobs élevé (milliers/jour)	Webhooks	Évite un volume excessif de requêtes de vérification de statut
Impossibilité d'exposer un endpoint HTTPS public	Polling	Les webhooks nécessitent un récepteur accessible
Besoin d'une prévention stricte des doublons	Clés d'idempotence à la soumission, dédoublonnage par ID de job à la réception	Protège contre les soumissions réessayées et les livraisons de webhooks en double
Plusieurs modèles d'images dans un pipeline	Normalisez le statut du job et la gestion des erreurs dans votre propre couche	Les fournisseurs sous-jacents (voir le comparatif des modèles d'images) ne partagent pas des taxonomies de statut identiques

Limitations

Cet article décrit un modèle général pour les API de jobs d'images asynchrones et n'affirme pas les chemins d'endpoints exacts, les noms de champs, les valeurs de timeout ou les noms d'événements webhook pour TokenLab ou pour tout fournisseur de modèle sous-jacent spécifique au-delà de ce qui est cité ci-dessus. Les vocabulaires de statut de job, les en-têtes retry-after et les schémas de signature de webhook varient entre les fournisseurs et peuvent changer au fil du temps ; traitez le code de cet article comme illustratif, et non comme du code de production à copier-coller, et confirmez les formes actuelles de requête et de réponse sur docs.tokenlab.sh avant la mise en production. Cet article ne couvre pas la tarification, les limites de débit ou les garanties de débit pour un modèle spécifique.

FAQ

Dois-je toujours utiliser des webhooks plutôt que le polling ? Non. Les webhooks réduisent la latence et le volume de requêtes à un coût opérationnel plus élevé. Pour les cas d'utilisation à faible volume ou internes, le polling est souvent le choix le plus simple et tout aussi fiable. De nombreux systèmes de production utilisent les webhooks comme chemin principal avec un balayage de polling périodique comme repli.

Comment éviter les générations d'images en double lors d'une nouvelle tentative ? Utilisez une clé d'idempotence sur la requête de soumission du job afin qu'un POST réessayé après une erreur réseau renvoie le job existant au lieu d'en créer un nouveau. Confirmez si l'endpoint de création de job de votre fournisseur prend en charge cela avant de vous y fier.

Que se passe-t-il si mon endpoint webhook est hors ligne lorsque le job se termine ? Le comportement dépend du fournisseur ; certains réessaient la livraison pendant une période, d'autres ne garantissent pas la relivraison. Un balayage de polling périodique pour les jobs vieux de quelques minutes sans statut terminal est une sauvegarde pratique quel que soit la politique de nouvelle tentative du fournisseur.

Si vous construisez une fonctionnalité de génération d'images et que vous souhaitez comparer l'accès basé sur les jobs à travers plusieurs modèles dans une seule API, consultez le répertoire des modèles d'images et le guide des tâches de génération d'images asynchrones, puis Commencez avec la documentation de l'API de TokenLab pour confirmer les détails actuels des endpoints et des webhooks pour votre build.