PiAPI-Polling und Webhooks: Aufgabenabschlüsse zuverlässig verarbeiten

Eine angenommene Bild- oder Videoanfrage braucht weiterhin einen Abschlussablauf. Speichern Sie bei Aufgaben der vereinheitlichten PiAPI-API die Aufgaben-ID, prüfen Sie den Endstatus und verarbeiten Sie dann die modellspezifische Ausgabe. Polling eignet sich für den Einstieg; Webhooks lassen das Backend auf den Abschluss reagieren.

1. Aufgaben-ID speichern und Polling begrenzen

Speichern Sie nach dem Erstellen data.task_id zusammen mit Ihrer eigenen Job-ID. Rufen Sie dieselbe Aufgabe mit dem serverseitigen API-Schlüssel ab. Eine erfolgreiche HTTP-Antwort belegt noch keinen Generierungsabschluss: Prüfen Sie data.status.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

Bei completed validieren Sie die modellspezifischen data.output-Daten; bei failed protokollieren Sie data.error. Begrenzen Sie Wiederholungen und erhöhen Sie die Warteabstände mit zufälliger Streuung. Die Wartefrist Ihrer Anwendung ist eine lokale Entscheidung: Ihr Ablauf beweist weder einen Fehler noch einen Abbruch der entfernten Aufgabe. Bewahren Sie die ID für einen späteren Abgleich auf.

2. Einen authentifizierten Callback ergänzen

Fügen Sie den folgenden Konfigurationsausschnitt in einen gültigen Erstellungsaufruf ein und behalten Sie vorhandene Konfigurationsfelder bei. Verwenden Sie einen öffentlichen HTTPS-Endpunkt und ein Geheimnis aus dem sicheren Speicher Ihres Backends. Laut PiAPI-Dokumentation wird es im Header x-webhook-secret gesendet; prüfen Sie es vor Annahme einer Benachrichtigung.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

Das Webhook-JSON enthält timestamp und data. Prüfen Sie die Zugehörigkeit zur Anwendung, speichern Sie das Ereignis dauerhaft oder in einer persistenten Warteschlange und antworten Sie zügig mit 2xx. Downloads und längere Arbeit gehören außerhalb des HTTP-Handlers. Rechnen Sie mit Wiederholungen: Die Dokumentation beschreibt erneute Zustellungen ohne erfolgreiche Antwort.

3. Polling und Callbacks zusammenführen

Verwenden Sie einen gemeinsamen Abschlusshandler. Eine dauerhafte Eindeutigkeitsbedingung für Aufgaben-ID und Abschlussaktion verhindert doppelte Nachrichten oder Folgejobs. Ein Zeitstempel allein identifiziert Ereignisse verschiedener Aufgaben nicht eindeutig. Ignorieren Sie veraltete Updates nach einem Endstatus und gestalten Sie den Worker nach einem Absturz sicher wiederholbar.

Fehlt der Callback oder ist der Zustand unklar, fragen Sie die gespeicherte Aufgaben-ID erneut ab. Ein Abruf-Timeout ist kein Grund, blind eine weitere kostenpflichtige Aufgabe anzulegen. Unterscheiden Sie Transportfehler von einem bestätigten Aufgabenfehler und gleichen Sie den Zustand vor einer erneuten Einreichung ab.

4. Fehlerfälle prüfen

Spielen Sie vor der Bereitstellung einen Callback erneut ab, senden Sie ein falsches Geheimnis und simulieren Sie Verzögerungen sowie einen Worker-Neustart. Jede fertige Aufgabe soll genau ein dauerhaftes Ergebnis liefern; Fehler sollen erhalten bleiben. Sichern Sie anschließend Dateien mit dem Leitfaden zur Ausgabespeicherung.

Quellen: vereinheitlichtes API-Schema, Beispiel zum Aufgabenabruf und Webhook-Dokumentation. Die Beispiele erklären die Integration und sind kein Benchmark realer Generierungen.