Polling i webhooki PiAPI: niezawodna obsługa zakończenia zadania

Przyjęcie żądania obrazu lub filmu nie kończy integracji. Dla zadań ujednoliconego API PiAPI zapisz identyfikator, sprawdź stan końcowy i obsłuż wynik właściwy dla modelu. Polling jest wygodny na początek; webhook pozwala backendowi reagować na zakończenie pracy.

1. Zapisz identyfikator i ogranicz polling

Po utworzeniu zapisz data.task_id obok identyfikatora własnego zlecenia. Odpytuj to samo zadanie kluczem API po stronie serwera. Poprawna odpowiedź HTTP nie dowodzi zakończenia generowania: sprawdź 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}"

Przy completed zweryfikuj data.output zgodnie z modelem; przy failed zapisz data.error. Ogranicz liczbę prób, zwiększaj odstępy i dodawaj losowe opóźnienie. Limit oczekiwania aplikacji jest lokalną decyzją: jego przekroczenie nie dowodzi błędu ani anulowania zdalnego zadania. Zachowaj ID do późniejszego uzgodnienia stanu.

2. Dodaj uwierzytelniony callback

Połącz poniższy fragment z poprawną treścią żądania tworzącego zadanie, zachowując istniejące pola konfiguracji. Użyj publicznego endpointu HTTPS i sekretu z bezpiecznego magazynu backendu. Według dokumentacji PiAPI sekret trafia do nagłówka x-webhook-secret; sprawdź go przed przyjęciem powiadomienia.

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

JSON webhooka zawiera timestamp i data. Sprawdź, czy zadanie należy do aplikacji, trwale zapisz zdarzenie lub umieść je w trwałej kolejce i szybko zwróć 2xx. Pobieranie plików i długie operacje wykonuj poza handlerem HTTP. Uwzględnij duplikaty: dokumentacja opisuje ponowienia przy braku poprawnej odpowiedzi.

3. Połącz polling i callbacki

Używaj wspólnego handlera zakończenia. Trwałe ograniczenie unikalności dla ID zadania i czynności końcowej zapobiega podwójnym powiadomieniom lub kolejnym zadaniom. Sam znacznik czasu nie identyfikuje zdarzeń różnych zadań. Ignoruj nieaktualne zmiany po stanie końcowym i umożliwiaj bezpieczne wznowienie workera po awarii.

Jeśli callback nie dotrze lub stan jest niejasny, ponownie odczytaj zapisane ID. Timeout odczytu nie uzasadnia tworzenia w ciemno kolejnego płatnego zadania. Odróżniaj błędy transportu od potwierdzonego niepowodzenia zadania i uzgodnij stan przed ponownym wysłaniem.

4. Sprawdź scenariusze awarii

Przed wdrożeniem odtwórz callback, prześlij błędny sekret, opóźnij dostarczenie i zasymuluj restart workera. Każde zakończone zadanie powinno dawać jeden trwały wynik, a nieudane zachować błąd. Następnie skorzystaj z poradnika zapisu wyników.

Źródła: schemat ujednoliconego API, przykład odczytu zadania i dokumentacja webhooków. Przykłady pokazują integrację, a nie benchmark rzeczywistego generowania.