Async Image Generation API: Jobs, Polling, Webhooks und Retries

Eine asynchrone Image Generation API ermöglicht es Ihnen, eine Generierungsanfrage zu übermitteln, sofort eine Job-ID zu erhalten und das fertige Bild zu einem späteren Zeitpunkt abzurufen, anstatt eine HTTP-Verbindung offen zu halten. Dieses Tutorial behandelt den Job-Lebenszyklus, wann Polling gegenüber Webhooks zu bevorzugen ist und wie man Retries so gestaltet, dass ein langsamer oder fehlgeschlagener Job nicht das Nutzererlebnis Ihres Produkts beeinträchtigt.

Wichtige Erkenntnisse

• Die Bildgenerierung ist jobbasiert und nicht request-response-basiert, da die Generierungslatenz (Sekunden bis zu mehreren zehn Sekunden) zu unzuverlässig ist, um sie über eine synchrone Verbindung aufrechtzuerhalten.
• Polling ist einfacher zu implementieren und zu debuggen; Webhooks reduzieren Latenz und Request-Volumen, erfordern jedoch einen öffentlichen Endpunkt, Signaturprüfung und eine idempotente Verarbeitung bei doppelten Zustellungen.
• Die Retry-Logik muss zwischen Übermittlungsfehlern, hängenden Jobs und verpassten Webhook-Zustellungen unterscheiden; jeder Fall erfordert einen anderen Wiederherstellungspfad.
• Genaue Endpunktnamen, Feldnamen und Webhook-Payload-Strukturen unterscheiden sich je nach Anbieter und der eigenen API-Oberfläche von TokenLab. Bestätigen Sie immer die aktuellen Spezifikationen unter docs.tokenlab.sh, bevor Sie live gehen.

Warum Image Generation APIs asynchron sind

Text-Completion-APIs können oft eine Antwort über dieselbe Verbindung zurückgeben, da die Token-Generierung schnell genug für Streaming ist. Bildgenerierungsmodelle, ob diffusionsbasiert oder autoregressiv, benötigen in der Regel länger und weisen eine variablere Latenz auf, die von der Auflösung, der Modellwahl und der Warteschlangentiefe abhängt. Eine synchrone HTTP-Anfrage über mehrere zehn Sekunden offen zu halten, ist fehleranfällig: Client-Timeouts, Idle-Limits von Load Balancern und Verbindungsabbrüche in Mobilfunknetzen erhöhen das Risiko, ein fertiges Ergebnis zu verlieren, für dessen Generierung Sie bereits bezahlt haben.

Das Standardmuster, das bei Anbietern von Bildgenerierung verwendet wird, ist ein Job-Modell: Sie senden eine Anfrage und erhalten eine Job-ID sowie einen anfänglichen Status (üblicherweise etwas wie queued oder processing). Sie pollen dann entweder einen Status-Endpunkt oder erhalten eine Webhook-Benachrichtigung, wenn der Job einen terminalen Zustand erreicht, und rufen die finalen Bild-URLs oder Binärdaten in einem separaten Aufruf ab.

TokenLab bietet über eine einzige API-Oberfläche Zugriff auf mehrere Bildmodelle, einschließlich der Nano Banana 2, Nano Banana Pro und Nano Banana 2 Lite-Familie, GPT Image 2, Reve 2.0 und MAI-Image-2.5. Siehe das Verzeichnis der Bildmodelle für die aktuelle Liste und den Leitfaden für asynchrone Bildgenerierungsaufgaben für das Verhalten der TokenLab-spezifischen Job-Endpunkte. Das allgemeine Muster unten gilt unabhängig davon, welches zugrunde liegende Modell Sie aufrufen, aber die genauen Feldnamen und Statuswerte sind unter docs.tokenlab.sh dokumentiert und sollten dort verifiziert werden, anstatt sie aus diesem Artikel anzunehmen.

Der Job-Lebenszyklus: Submit, Poll, Retrieve

Auf konzeptioneller Ebene durchläuft ein asynchroner Bild-Job drei Phasen:

1. Submit: Senden Sie einen Prompt und Parameter per POST, erhalten Sie eine Job-ID und einen anfänglichen Status.
2. Check status: Pollen Sie entweder einen GET-Endpunkt unter Verwendung der Job-ID oder warten Sie auf ein Webhook-Ereignis.
3. Retrieve output: Sobald der Status terminal ist (erfolgreich oder fehlgeschlagen), rufen Sie die Bild-URL(s) oder Fehlerdetails ab.

Hier ist ein illustratives Polling-Muster in Python. Betrachten Sie die Endpunktpfade und Feldnamen als Platzhalter; bestätigen Sie die aktuelle Struktur des TokenLab-Job-Endpunkts in der API-Dokumentation, bevor Sie dies in der Produktion verwenden.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # Überprüfen Sie die aktuelle Basis-URL in 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"))

Der idempotency_key im Submit-Aufruf ist wichtig: Wenn ein Netzwerkfehler auftritt, nachdem der Job erstellt wurde, aber bevor Ihr Client die Job-ID erhalten hat, sollte ein erneuter Versuch des Submit-Aufrufs mit demselben Schlüssel den bestehenden Job zurückgeben, anstatt eine doppelte Generierung zu erstellen. Bestätigen Sie in der aktuellen Dokumentation, ob und wie der Job-Endpunkt von TokenLab Idempotency-Keys unterstützt, da dies ein verbreitetes, aber nicht universelles Muster bei Anbietern ist.

Polling vs. Webhooks: Abwägungen

Beide Ansätze sind valide; die richtige Wahl hängt von Ihrem Traffic-Muster und Ihrer Infrastruktur ab.

Polling ist einfacher zu implementieren und lokal zu testen, erfordert keinen öffentlichen Endpunkt und funktioniert gut für Workloads mit geringem Volumen oder Batch-Verarbeitung, bei denen ein paar zusätzliche Sekunden Latenz keine Rolle spielen. Die Nachteile sind eine Latenzuntergrenze, die Ihrem Polling-Intervall entspricht, sowie ein unnötiges Request-Volumen, wenn Sie bei lang laufenden Jobs zu aggressiv pollen.

Webhooks senden eine Benachrichtigung an Ihren Server, wenn ein Job seinen Status ändert, was die Latenz senkt und unnötige Statusabfragen reduziert. Der Preis dafür ist operativer Aufwand: Sie benötigen einen öffentlich erreichbaren HTTPS-Endpunkt, eine Signaturprüfung, um zu bestätigen, dass die Payload tatsächlich vom Anbieter stammt, sowie eine Handhabung für doppelte oder in falscher Reihenfolge eintreffende Zustellungen.

Die Dokumentation zu Webhook-Ereignissen von OpenAI beschreibt die allgemeine Form dieses Musters für asynchrone Operationen: Ihr Endpunkt empfängt ein Ereignis mit einem Typ und einer Objekt-ID. Die empfohlene Praxis ist es, die Webhook-Payload als Benachrichtigung zu behandeln, um den aktuellen Status der Ressource über die API abzurufen, anstatt der Webhook-Body als finale Quelle der Wahrheit zu vertrauen. Dieses "Pull-after-Push"-Muster ist unabhängig vom Bildanbieter empfehlenswert, da es Sie schützt, falls eine Webhook-Payload abgeschnitten, verzögert oder mehrfach zugestellt wird.

Sichere Implementierung von Webhooks

Wenn Sie sich für Webhooks zur Fertigstellung von Bild-Jobs entscheiden, reduzieren die folgenden Praktiken das Risiko stiller Fehler:

• Überprüfen Sie die Signatur bei jeder eingehenden Webhook-Anfrage, bevor Sie sie verarbeiten. Lehnen Sie alles ab, was nicht übereinstimmt, und protokollieren Sie Ablehnungen separat vom normalen Traffic, damit Sie ein falsch konfiguriertes Secret schnell erkennen können.
• Antworten Sie schnell, verarbeiten Sie später. Bestätigen Sie den Webhook mit einem 200-Status, sobald Sie ihn validiert haben, und übergeben Sie die eigentliche Arbeit (Abrufen des Bildes, Schreiben in den Speicher, Benachrichtigung Ihres Benutzers) an einen Hintergrund-Job oder eine Warteschlange. Anbieter wiederholen die Webhook-Zustellung in der Regel, wenn sie keine zeitnahe 2xx-Antwort erhalten, was zu doppelter Verarbeitung führen kann, wenn Ihr Handler langsam und synchron ist.
• Deduplizieren Sie nach Job-ID. Speichern Sie verarbeitete Job-IDs (oder einen Hash des Ereignisses), damit eine wiederholte Zustellung keine Benachrichtigung erneut auslöst oder ein Dateischreiben erneut verarbeitet.
• Rufen Sie die Ressource erneut ab unter Verwendung der Job-ID aus der Webhook-Payload, anstatt den eingebetteten Ausgabe-URLs als zwingend final zu vertrauen, im Einklang mit dem oben beschriebenen Pull-after-Push-Muster.

Ein minimaler Handler-Entwurf:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # Verwenden Sie in der Produktion einen echten Speicher

@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  # bereits verarbeitet, bestätigen und überspringen

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

Überprüfen Sie die genauen Webhook-Ereignisnamen, die Payload-Struktur und den Signatur-Header, die für die Fertigstellung von Bild-Jobs verwendet werden, anhand der aktuellen Anbieterdokumentation und separat anhand der eigenen Webhook-Unterstützung von TokenLab, wie unter docs.tokenlab.sh beschrieben, da diese Details anbieterspezifisch sind und sich ändern können.

Retry-Design: Drei Fehlerklassen

Asynchrone Bild-Jobs schlagen auf drei verschiedene Arten fehl, und jede benötigt ihre eigene Handhabung:

1. Übermittlungsfehler: Der POST zum Erstellen eines Jobs gibt einen 4xx- oder 5xx-Fehler zurück. Bei 5xx- und Netzwerkfehlern sollten Sie es mit exponentiellem Backoff und Jitter erneut versuchen und denselben Idempotency-Key wiederverwenden, damit Sie keine doppelten Jobs erstellen. Bei 4xx-Fehlern (falscher Prompt, ungültiges Modell, Kontingent überschritten) führt ein erneuter Versuch ohne Änderung der Anfrage nur erneut zum Fehler; geben Sie den Fehler stattdessen an den Aufrufer weiter.
2. Hängende Jobs: Ein Job verbleibt weit über die erwartete Generierungszeit hinaus in einem nicht-terminalen Status. Legen Sie pro Modell eine maximale Wartezeit fest (die Generierungszeit variiert je nach Modell und Auflösung) und behandeln Sie Jobs, die diese überschreiten, für die Zwecke Ihrer Anwendung als fehlgeschlagen, auch wenn der Anbieter sie noch nicht offiziell als fehlgeschlagen markiert hat. Protokollieren Sie diese separat, da eine steigende Rate hängender Jobs oft auf einen Vorfall auf Anbieterseite hinweist.
3. Verpasste Webhook-Zustellungen: Ihr Endpunkt war ausgefallen oder die Zustellung wurde verworfen, und es kommt nie ein Ereignis an. Deshalb lohnt es sich, auch bei einem Webhook-First-Design ein Polling-Fallback beizubehalten: Ein periodischer Sweep, der den Status jedes Jobs prüft, der älter als ein paar Minuten ist und keinen terminalen Status hat, fängt Jobs ab, deren Webhook stillschweigend nicht angekommen ist.

Entscheidungs-Checkliste

Verwenden Sie diese Checkliste, wenn Sie entscheiden, wie Sie die Job-Fertigstellung für eine Bildgenerierungsfunktion anbinden.

Szenario	Empfohlener Ansatz	Warum
Geringes Volumen, internes Tool oder Batch-Skript	Polling	Am einfachsten zu bauen; kein öffentlicher Endpunkt erforderlich
Benutzerorientierte Funktion, bei der Latenz wichtig ist	Webhooks, mit Polling-Fallback-Sweep	Geringere Latenz; Fallback fängt verpasste Zustellungen ab
Hohes Job-Volumen (Tausende/Tag)	Webhooks	Vermeidet übermäßiges Volumen an Statusabfragen
Keine Möglichkeit, einen öffentlichen HTTPS-Endpunkt bereitzustellen	Polling	Webhooks erfordern einen erreichbaren Empfänger
Notwendigkeit strenger Duplikatvermeidung	Idempotency-Keys beim Submit, Deduplizierung nach Job-ID beim Empfang	Schützt vor wiederholten Übermittlungen und doppelten Webhook-Zustellungen
Mehrere Bildmodelle in einer Pipeline	Normalisierung von Job-Status und Fehlerbehandlung in Ihrer eigenen Schicht	Die zugrunde liegenden Anbieter (siehe den Bildmodell-Vergleich) teilen keine identischen Status-Taxonomien

Einschränkungen

Dieser Artikel beschreibt ein allgemeines Muster für asynchrone Bild-Job-APIs und erhebt keinen Anspruch auf exakte Endpunktpfade, Feldnamen, Timeout-Werte oder Webhook-Ereignisnamen für TokenLab oder für einen bestimmten zugrunde liegenden Modellanbieter, die über das oben Zitierte hinausgehen. Job-Status-Vokabulare, Retry-After-Header und Webhook-Signatur-Schemata variieren zwischen den Anbietern und können sich im Laufe der Zeit ändern; betrachten Sie den Code in diesem Artikel als illustrativ, nicht als Copy-Paste-Produktionscode, und bestätigen Sie die aktuellen Request- und Response-Strukturen unter docs.tokenlab.sh, bevor Sie live gehen. Dieser Artikel behandelt keine Preise, Ratenbegrenzungen oder Durchsatzgarantien für ein bestimmtes Modell.

FAQ

Sollte ich immer Webhooks anstelle von Polling verwenden? Nein. Webhooks reduzieren Latenz und Request-Volumen bei höheren operativen Kosten. Für Anwendungsfälle mit geringem Volumen oder interne Zwecke ist Polling oft die einfachere und ebenso zuverlässige Wahl. Viele Produktionssysteme verwenden Webhooks als primären Pfad mit einem periodischen Polling-Sweep als Fallback.

Wie vermeide ich doppelte Bildgenerierungen bei einem Retry? Verwenden Sie einen Idempotency-Key bei der Job-Übermittlungsanfrage, damit ein wiederholter POST nach einem Netzwerkfehler den bestehenden Job zurückgibt, anstatt einen neuen zu erstellen. Bestätigen Sie, ob der Job-Erstellungs-Endpunkt Ihres Anbieters dies unterstützt, bevor Sie sich darauf verlassen.

Was passiert, wenn mein Webhook-Endpunkt ausgefallen ist, wenn der Job fertig ist? Das Verhalten hängt vom Anbieter ab; einige wiederholen die Zustellung für einen Zeitraum, andere garantieren keine erneute Zustellung. Ein periodischer Polling-Sweep für Jobs, die älter als ein paar Minuten sind und keinen terminalen Status haben, ist eine praktische Sicherheitsmaßnahme, unabhängig von der Retry-Richtlinie des Anbieters.

Wenn Sie eine Bildgenerierungsfunktion aufbauen und jobbasierten Zugriff über mehrere Modelle hinweg in einer API vergleichen möchten, überprüfen Sie das Verzeichnis der Bildmodelle und den Leitfaden für asynchrone Bildgenerierungsaufgaben und starten Sie dann mit der TokenLab API-Dokumentation, um die aktuellen Endpunkt- und Webhook-Details für Ihren Build zu bestätigen.