Zum Hauptinhalt springen

Überblick

Anstatt GET /jobs/{id} zu pollen, gib Krea eine Webhook-URL. Krea sendet den Job an diese URL, sobald er abgeschlossen ist.

Webhooks verwenden

Füge den X-Webhook-URL-Header zu einer beliebigen Generierungsanfrage hinzu. Wenn der Job abgeschlossen wird, fehlschlägt oder abgebrochen wird, sendet Krea eine POST-Anfrage an diese URL.

Webhook-Payload

Der Request-Body hat dieselbe Struktur wie die Antwort von GET /jobs/{id}:

Signaturen verifizieren

Krea signiert jeden Webhook mit Ed25519. Verifiziere die Signatur, bevor du einem Payload vertraust, und lehne Anfragen ohne Signatur ab. Krea signiert den SHA-256-Hash in Hex-Kleinbuchstaben aus Timestamp, URL, Metadaten und rohem Request-Body, verbunden durch Zeilenumbrüche:
So verifizierst du eine Anfrage:
  1. Prüfe, ob X-Krea-Webhook-Url exakt mit der X-Webhook-URL übereinstimmt, die du mit dem Job gesendet hast.
  2. Prüfe, ob der Timestamp höchstens 5 Minuten von der aktuellen Uhrzeit deines Servers abweicht.
  3. Akzeptiere die Anfrage, wenn die Signatur mit einem beliebigen Schlüssel aus https://api.krea.ai/.well-known/jwks.json erfolgreich verifiziert wird. Cache die Schlüssel höchstens 24 Stunden lang. Krea veröffentlicht einen neuen Schlüssel 24 Stunden, bevor damit signiert wird.
Hashe die rohen Bytes des Bodys, nicht neu serialisiertes JSON. Verwende zum Beispiel express.raw() in Express, await request.arrayBuffer() in Frameworks mit Fetch API oder request.get_data() in Flask. Behandle einen fehlenden X-Krea-Webhook-Metadata-Header als leeren String.

Zustellung und Wiederholungsversuche

Gib innerhalb von 15 Sekunden einen 2xx zurück. Wenn bei der Anfrage ein Timeout auftritt, keine Verbindung hergestellt werden kann oder sie einen 5xx, 408, 423, 425 oder 429 erhält, versucht Krea es etwa 10 Minuten lang erneut, jedes Mal mit neuem Timestamp und neuer Signatur. Bei allen anderen 4xx wiederholt Krea die Zustellung nicht. Derselbe Job kann mehr als einmal ankommen. Dedupliziere daher anhand von job_id und status.

Webhooks vs. Polling

Verwende Webhooks, wenn du einen Server hast, der HTTP-Anfragen empfangen kann. Verwende Polling für clientseitige Anwendungen oder wenn du keinen öffentlichen Endpoint bereitstellen kannst.

Nächste Schritte

Job-Lebenszyklus

Erfahre mehr über Job-Status und Status-Polling

Codebeispiele

Generiere ein Bild mit der API, von Anfang bis Ende