APIMaster asynchrone Task-Webhooks

Nutzen Sie Webhooks als primären Benachrichtigungsmechanismus für asynchrone Generierung und behalten Sie Polling als Fallback bei. APIMaster sendet eine signierte HTTPS-POST, wenn ein verfolgter Task abgeschlossen ist oder fehlschlägt. Die Benachrichtigungen sind unabhängig vom Generierungsanbieter und verwenden Ihre APIMaster-Task-ID.

Unterstützte Modelle und Endpunkte

Seedance umfasst alle vier Modelle: seedance-2.0, seedance-2.5, seedance-2.0-fast und seedance-2.0-mini. Verwenden Sie POST /v1/videos/generations oder den kompatiblen POST /v1/video/generations.

Video-Task-Benachrichtigungen unterstützen auch MiniMax-H3, Kling Omni / Motion Control, Grok Imagine Video und Sora. Unterstützte GPT Image 2 / 2.5- und Gemini-Bild-Workflows verwenden /v1/images/generations/async oder unterstützte /v1/images/edits/async; Midjourney v8.2 / Niji 7 verwenden /v1/midjourney/generations. Die Verfügbarkeit von Routen und Generierungsparameter folgen weiterhin dem Leitfaden jedes Modells. Synchrone Seedream- und Grok-Bildgenerierung, Chat-Streaming und Seedance-Asset-Review sind nicht Teil dieses Generierungs-Webhook-Vertrags.

Prüfen Sie GET /v1/webhook-capabilities?model=seedance-2.0-fast auf Modellberechtigung. Verwenden Sie einen unterstützten asynchronen Übermittlungsendpunkt; Berechtigung bedeutet nicht, dass jeder Bildvorgang oder jeder Model-Alias asynchrone Generierung unterstützt.

Endpunkt registrieren und verifizieren

Verwenden Sie Ihren API-Schlüssel in Authorization: Bearer YOUR_API_KEY. Ein API-Schlüssel kann Endpunkte und Ereignisse verwalten, die zu seinem Konto gehören. Bewahren Sie ihn auf Ihrem Server auf.

curl --fail-with-body "https://apimaster.ai/v1/webhook-endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example/webhooks/apimaster"}'

Die Antwort enthält endpoint.id, endpoint.key_id und signing_secret. Speichern Sie das Signiergeheimnis sicher: Es wird nur einmal zurückgegeben. Es ist getrennt von Ihrem API-Schlüssel und kann keine Generierung oder Downloads autorisieren. Die URL muss ein öffentlich erreichbarer HTTPS-Endpunkt auf Port 443 sein. Private Adressen und Weiterleitungen werden abgelehnt. Bis zu 20 Endpunkte sind pro Konto erlaubt; URLs sind unveränderlich, daher erstellen und verifizieren Sie einen neuen Endpunkt, wenn sich das Ziel ändert.

Nachdem Sie Ihren Empfänger konfiguriert haben, verifizieren Sie das Eigentum:

curl --fail-with-body -X POST "https://apimaster.ai/v1/webhook-endpoints/whep_example/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

APIMaster sendet ein signiertes webhook.endpoint_verification-Ereignis, das data.challenge enthält. Geben Sie innerhalb von 10 Sekunden HTTP 200 mit {"challenge":"THE_RECEIVED_CHALLENGE"} zurück. Eine Generierungsanfrage, die auf einen nicht verifizierten, pausierten oder einem anderen Konto gehörenden Endpunkt verweist, wird vor der Übermittlung abgelehnt.

Das gesamte HTTP-Zeitlimit beträgt 10 Sekunden einschließlich DNS, Verbindung und TLS. Antwortheader müssen innerhalb von 8 Sekunden nach dem Senden eintreffen. Speichern Sie das Ereignis dauerhaft und bestätigen Sie es umgehend.

Task mit Benachrichtigungen übermitteln

curl --fail-with-body "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.5",
    "prompt":"A paper boat floating on a calm pond, slow camera movement.",
    "duration":4,
    "resolution":"480p",
    "aspect_ratio":"16:9",
    "notifications":{
      "webhook":{
        "endpoint_id":"whep_example",
        "events":["task.completed","task.failed"]
      }
    },
    "client_reference_id":"order_123"
  }'

Ersetzen Sie die Modell-ID durch eine der vier Seedance-IDs, während Sie deren eigene unterstützte Parameter beibehalten. Speichern Sie die Task-ID aus der normalen Erstellungsantwort. client_reference_id ist eine optionale Geschäftsreferenz von maximal 128 Bytes; es ist kein Idempotenzschlüssel für die Übermittlung. Kombinieren Sie notifications nicht mit Legacy-webhook oder callback_url-Anbieterparametern.

Für unterstützte Multipart-Bildbearbeitungen senden Sie notifications als JSON-String-Formularfeld und client_reference_id als separates Formularfeld:

curl --fail-with-body "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Turn the reference into a watercolor illustration" \
  -F "image=@reference.png" \
  -F 'notifications={"webhook":{"endpoint_id":"whep_example","events":["task.completed","task.failed"]}}' \
  -F "client_reference_id=image_order_123"

In dieser Version gibt es keinen kontoweiten Standardendpunkt: Referenzieren Sie einen Endpunkt in jeder Task-Anfrage. Webhooks können vor Ihrer Übermittlungsantwort eintreffen. Speichern Sie sie auch dann, wenn Ihre Anwendung die zurückgegebene Task-ID noch nicht gespeichert hat. Einige asynchrone Bild-Workflows umschließen synchrone Upstream-Generierung, daher kann die Übermittlung selbst noch Zeit in Anspruch nehmen.

Erfolgs- und Fehler-Payloads

Eine Erfolgsbenachrichtigung enthält die öffentliche Task-ID und einen authentifizierten Video-Link:

{
  "id":"evt_example",
  "type":"task.completed",
  "api_version":"2026-10-03",
  "created_at":1791014400,
  "data":{
    "task_id":"task_example",
    "model":"seedance-2.5",
    "kind":"video",
    "status":"completed",
    "client_reference_id":"order_123",
    "completed_at":1791014400,
    "task_url":"https://apimaster.ai/v1/videos/task_example",
    "result":{
      "outputs":[{
        "output_id":"0",
        "type":"video",
        "url":"https://apimaster.ai/v1/videos/task_example/content",
        "authentication":"bearer",
        "expires_at":null
      }]
    },
    "error":null
  }
}

Bei Fehlern wird derselbe Umschlag mit type: "task.failed", data.status: "failed", data.result: null und einem Fehlerobjekt verwendet:

{
  "code":"generation_failed",
  "message":"The generation task failed. Query the task for details."
}

Sowohl vom Anbieter bestätigte Fehler als auch Gateway-Task-Timeouts können Fehlerereignisse generieren. Eine Erstellungsanfrage, die abgelehnt wird, bevor ein Task akzeptiert wird, generiert kein Task-Ereignis. Zustellungsfehler bei Benachrichtigungen ändern nicht den Generierungsstatus oder führen die Generierung erneut aus. Ereignisse bestätigen nicht, dass die Abrechnungsabstimmung abgeschlossen ist.

Für Bilder ist kind image und outputs enthält alle verfügbaren Bildausgaben. Midjourney-Child-Task-Ereignisse enthalten batch_id; Sie können zusätzlich batch.completed abonnieren, um eine Batch-Zusammenfassung zu erhalten, nachdem alle Child-Tasks abgeschlossen sind. Dessen Status ist completed, partial_failure oder failed, mit Zählungen in data.summary. Batch-Abschluss bedeutet nicht immer, dass jedes Child erfolgreich war.

Laden Sie Ausgabe-URLs mit einem API-Schlüssel herunter, der zum Konto des Tasks gehört. Speichern Sie generierte Medien umgehend. expires_at: null bedeutet, dass keine garantierte Ablaufzeit bereitgestellt wird, nicht permanente Speicherung; ein späterer Download kann HTTP 410 zurückgeben. Das erneute Abspielen eines Ereignisses verlängert nicht die Medienverfügbarkeit.

Authentifizieren Sie Callbacks und bestätigen Sie umgehend

Jeder POST-Transport enthält:

X-APIMaster-Event-ID: evt_example
X-APIMaster-Delivery-ID: dlv_example
X-APIMaster-Timestamp: 1791014400
X-APIMaster-Signature: v1=<hex-hmac>,kid=<key-id>

Verifizieren Sie HMAC-SHA256 über den Zeitstempel, einen wörtlichen Punkt und die Roh-Request-Body-Bytes unter Verwendung des Signierschlüssels des Endpunkts. Verwenden Sie einen zeitkonstanten Vergleich, erlauben Sie maximal fünf Minuten Taktabweichung und prüfen Sie, dass der Event-ID-Header mit der ID im Body übereinstimmt. Wiederholungsversuche behalten dieselbe Event-ID und denselben Body, erhalten aber eine neue Zustellungs-ID, einen neuen Zeitstempel und eine neue Signatur.

Der folgende Python-Empfänger verwendet Flask und SQLite. Er speichert ein Event atomar, bevor er es bestätigt. Ihr Anwendungs-Worker sollte die gespeicherten Zeilen separat konsumieren, Dateien herunterladen und Geschäftslogik ausführen.

import hashlib, hmac, json, os, sqlite3, time
from flask import Flask, request, jsonify, abort

app = Flask(__name__)
# During key rotation, configure both active and previous kid/secret pairs.
SECRETS = json.loads(os.environ["APIMASTER_WEBHOOK_SECRETS_JSON"])
DB_PATH = os.environ.get("WEBHOOK_DB_PATH", "webhook-events.sqlite3")
with sqlite3.connect(DB_PATH) as db:
    db.execute("CREATE TABLE IF NOT EXISTS events (id TEXT PRIMARY KEY, body BLOB NOT NULL)")

@app.post("/webhooks/apimaster")
def receive():
    raw = request.get_data()
    try:
        timestamp = request.headers["X-APIMaster-Timestamp"]
        if abs(time.time() - int(timestamp)) > 300:
            abort(401)
        fields = dict(part.split("=", 1) for part in
                      request.headers["X-APIMaster-Signature"].split(","))
        secret = SECRETS[fields["kid"]]
        expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw,
                            hashlib.sha256).hexdigest()
        if not hmac.compare_digest(expected, fields["v1"]):
            abort(401)
        event = json.loads(raw)
        if event["id"] != request.headers["X-APIMaster-Event-ID"]:
            abort(401)
    except (KeyError, ValueError, TypeError):
        abort(401)
    if event["type"] == "webhook.endpoint_verification":
        return jsonify(challenge=event["data"]["challenge"])
    with sqlite3.connect(DB_PATH) as db:
        db.execute("INSERT OR IGNORE INTO events(id, body) VALUES (?, ?)",
                   (event["id"], raw))
    return "", 204

Geben Sie innerhalb von 10 Sekunden für Generierungs-Events einen beliebigen 2xx-Status zurück. Bestätigen Sie nach dauerhafter Speicherung, ohne auf Medien-Downloads zu warten. Die Zustellung erfolgt mindestens einmal: Doppelte Events sind möglich, insbesondere wenn eine Bestätigung verloren geht, daher deduplizieren Sie anhand von id. Es gibt keine Reihenfolgegarantie über Tasks hinweg.

Wiederholungsversuche, Zustellungsverlauf und Wiederholung

APIMaster wiederholt Netzwerkfehler, Bestätigungs-Timeouts und Nicht-2xx-Antworten für bis zu 72 Stunden ab Event-Erstellung. Die anfänglichen Verzögerungen betragen 1, 2, 5, 15 und 30 Minuten, dann 1, 2, 4 und 8 Stunden, gefolgt von 12-Stunden-Intervallen, mit bis zu 20 % Jitter. Ein gültiger Retry-After bei 429/503 wird innerhalb des Wiederholungsfensters respektiert. Weiterleitungen werden nicht befolgt. HTTP 410 pausiert den Endpunkt; andere 4xx-Antworten werden wiederholt, um Konfigurationskorrekturen zu ermöglichen.

curl --fail-with-body "https://apimaster.ai/v1/webhook-events?task_id=task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body "https://apimaster.ai/v1/webhook-events/evt_example/deliveries" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -X POST "https://apimaster.ai/v1/webhook-events/evt_example/redeliver" \
  -H "Authorization: Bearer YOUR_API_KEY"

Statusangaben umfassen pending, in_flight, retrying, delivered, paused und exhausted. Event- und Versuchsdatensätze werden 30 Tage lang aufbewahrt. Eine Wiederholung bewahrt die ursprüngliche Event-ID und Payload und öffnet ein neues 72-Stunden-Zustellungsfenster; sie generiert Medien nicht neu und berechnet nicht erneut. Bis zu fünf manuelle Wiederholungen pro Event pro UTC-Tag sind erlaubt. Ein Event, das derzeit für die Zustellung geleast ist, kann erst wiederholt werden, wenn dieser Versuch endet oder sein Lease abläuft.

Pausieren oder setzen Sie einen Endpunkt mit PATCH /v1/webhook-endpoints/{id} und {"enabled":false} oder {"enabled":true} fort. Fortsetzung setzt pausierte Events fort, deren ursprüngliche Frist noch nicht verstrichen ist. Rotieren Sie Schlüssel mit POST /v1/webhook-endpoints/{id}/rotate-secret; speichern Sie den neuen Schlüssel und die kid, und behalten Sie das vorherige Paar für die zurückgegebene 24-stündige Übergangszeit.

Polling-Fallback

Für Tasks ohne erhaltenes terminales Event fragen Sie /v1/videos/{task_id} oder die dokumentierte Image-Task-Abfrage des Modells alle 60–120 Sekunden ab. Verwenden Sie die Task-API als Quelle der Wahrheit und prüfen Sie den Zustellungsverlauf, wenn die Generierung abgeschlossen ist, die Benachrichtigung jedoch fehlt. Ein fehlender Webhook ist kein Grund, eine abrechenbare Generierungsanfrage erneut einzureichen. Anhaltende Endpunkt-Ausfallzeit kann automatische Wiederholungsversuche erschöpfen; stellen Sie den Empfänger wieder her und wiederholen Sie gespeicherte Events.