Rückruf bei Aufgabenabschluss (Webhook)

​

Schnellstart

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",
    "language": "de"
  }'

​

Sprache der Fehlermeldung auswählen

• Bei den Werten wird nicht zwischen Groß- und Kleinschreibung unterschieden; führende und nachfolgende Leerzeichen werden automatisch entfernt. "DE" und " de " werden beispielsweise beide als de behandelt.
• Verwende die zweistelligen Codes aus der Tabelle. Regionale Tags wie zh-CN, en-US und pt-BR werden nicht erkannt.
• Ein nicht unterstützter Wert führt nicht dazu, dass die Aufgabeneinreichung fehlschlägt; der Rückruf enthält die ursprüngliche Fehlermeldung.
• Ist die ursprüngliche Meldung bereits in der Zielsprache, wird sie unverändert und ohne erneute Übersetzung zurückgegeben.
• Schlägt die Übersetzung fehl, wird die ursprüngliche Meldung zurückgegeben, ohne den Rückruf zu verzögern oder zu verwerfen.

​

URL-Regeln

​

Was du erhältst

{
  "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 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "Auf das Eingabebild kann nicht zugegriffen werden. Stelle sicher, dass die URL öffentlich erreichbar ist",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

​

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.

​

Anforderungen an die Rückruf-URL

​

Häufige Fragen

​

Minimales Empfänger-Beispiel

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()