Zum Hauptinhalt springen
Beim Einreichen asynchroner Generierungsaufgaben wie Video / Bild / Audio kannst du eine Rückruf-URL angeben. Sobald die Aufgabe abgeschlossen ist (erfolgreich oder fehlgeschlagen), senden wir das Ergebnis aktiv per POST an deine URL, sodass du nicht ständig abfragen musst.

​
Schnellstart

Füge beim Einreichen einer Aufgabe ein webhook-Feld zum Anfragetext hinzu: 
curl -X POST https://deine-zugangsdomain/v1/images/generations \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com"
  }'
Nach Abschluss der Aufgabe senden wir eine POST-Anfrage an deine URL + /callback.
Andere asynchrone Aufgaben-Endpunkte (Video, Audio usw.) funktionieren genauso – füge einfach das webhook-Feld zum Anfragetext hinzu.

​
URL-Regeln

Die von dir angegebene webhook ist die Basis-URL, an die wir automatisch /callback anhängen:
Deine webhookWohin wir tatsächlich POST senden
https://your-server.comhttps://your-server.com/callback
https://your-server.com/apihttps://your-server.com/api/callback
https://your-server.com/api/https://your-server.com/api/callback
Dein Server benötigt also einen Endpunkt, der POST .../callback akzeptiert.

​
Was du erhältst

Der gesendete Inhalt ist exakt derselbe wie die Antwort des Endpunkts „Aufgabenstatus abrufen” – du kannst ihn mit derselben Parsing-Logik verarbeiten. 
{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}
Bei Videoaufgaben liegt das Ergebnis in result.videos, bei Audio in result.audios.
Wir senden nur, wenn eine Aufgabe einen Endzustand erreicht (completed / failed); während der Verarbeitung senden wir nicht.

​
Wiederholungen und Deduplizierung (wichtig)

  • Wiederholungen: Wenn dein Server nicht innerhalb von etwa 10 Sekunden 2xx zurückgibt oder 5xx zurückgibt, wiederholen wir automatisch, bis zu 3 Mal, in Abständen von etwa 10 s, 30 s und 60 s. Schlagen alle 3 fehl, geben wir auf (innerhalb von etwa 2 Minuten).
  • Keine Wiederholung: Gibt dein Endpunkt 4xx zurück (als fehlerhafte URL / Anfrage gewertet), geben wir sofort ohne Wiederholung auf.
  • Deduplizierung: Normalerweise wird eine Aufgabe nur einmal gesendet. In Extremfällen (z. B. ein Neustart auf unserer Seite nach dem Senden, aber vor der Bestätigung) kannst du doppelte Sendungen erhalten. Stelle unbedingt sicher, dass du idempotent nach id (task_id) dedupliziert, um doppelte Verarbeitung zu vermeiden.
Empfehlungen für deinen Empfangs-Endpunkt:
1

So schnell wie möglich 2xx zurückgeben

Zuerst annehmen und in die Warteschlange stellen, dann asynchron verarbeiten – lass uns nicht auf den Abschluss deiner Verarbeitung warten.
2

Nach id deduplizieren

Verwende id (task_id) als Idempotenzschlüssel, um doppelte Verarbeitung zu vermeiden.
3

Signatur konfigurieren und prüfen

Überprüfe in der Produktion die Herkunft der Rückrufanfragen und weise gefälschte ab.

​
Anforderungen an die Rückruf-URL

Aus Sicherheitsgründen muss die Rückruf-URL Folgendes erfüllen:
AnforderungBeschreibung
Öffentlich erreichbarDarf keine interne / lokale Adresse sein (z. B. 127.0.0.1, 10.x, 192.168.x werden abgelehnt)
Protokollhttp oder https (https empfohlen)
PortStandardports verwenden (80 / 443); nicht standardmäßige Ports können blockiert werden
DomainDarf nicht auf unsere eigene Dienst-Domain zeigen
URLs, die diese Anforderungen nicht erfüllen, werden verworfen (kein Senden, keine Wiederholung).

​
Häufige Fragen

Prüfe Punkt für Punkt:
  1. Ist die Aufgabe tatsächlich abgeschlossen? Prüfe die Aufgabendetails – ist status completed / failed (während der Verarbeitung wird nicht gesendet)?
  2. Ist deine URL öffentlich erreichbar? Können wir deinen /callback erreichen?
  3. Ist der Port ein Standardport (80 / 443)? Nicht standardmäßige Ports können durch Sicherheitsrichtlinien blockiert werden.
  4. Hat dein /callback rechtzeitig 2xx zurückgegeben? Bei 4xx geben wir sofort auf.
  5. Verwendest du https? Ist das Zertifikat gültig?
Einige Modelle erzeugen mehrere Bilder auf einmal, daher kann images[].url ein Array sein – behandle es einfach als Array.
Nein. Wir senden nur einmal, wenn die Aufgabe endgültig erfolgreich ist oder fehlschlägt.

​
Minimales Empfänger-Beispiel

Python
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("Aufgaben-Rückruf erhalten:", data["id"], data["status"])
        # TODO: nach id deduplizieren, Signatur prüfen, dann verarbeiten
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()
Gib so schnell wie möglich 200 zurück und führe deine Verarbeitungslogik asynchron im Hintergrund aus.