PiAPI-polling en webhooks: taakafronding betrouwbaar verwerken

Na het accepteren van een beeld- of videoaanvraag is nog een afrondingsproces nodig. Bewaar bij taken van de uniforme PiAPI-API het taak-ID, controleer de eindstatus en verwerk de modelspecifieke uitvoer. Polling is handig voor een eerste integratie; webhooks laten de backend reageren wanneer het werk klaar is.

1. Bewaar het taak-ID en begrens polling

Sla na het aanmaken data.task_id op naast uw eigen job-ID. Vraag dezelfde taak op met de API-sleutel van de server. Een geslaagde HTTP-respons bewijst niet dat de generatie klaar is: controleer 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}"

Valideer bij completed de modelspecifieke data.output; leg bij failed data.error vast. Beperk herhaalpogingen en vergroot wachttijden met willekeurige spreiding. De wachttijdlimiet van uw toepassing is een lokale keuze: overschrijding bewijst geen mislukking of annulering van de externe taak. Bewaar het ID voor latere controle.

2. Voeg een geauthenticeerde callback toe

Voeg het onderstaande fragment samen met een geldige aanvraag om een taak aan te maken en behoud bestaande configuratievelden. Gebruik een openbaar HTTPS-endpoint en een geheim uit de beveiligde opslag van uw backend. Volgens de PiAPI-documentatie wordt dit verstuurd in de header x-webhook-secret; controleer die vóór acceptatie.

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

De webhook-JSON bevat timestamp en data. Controleer of de taak bij uw toepassing hoort, sla het event duurzaam op of plaats het in een persistente wachtrij en antwoord snel met 2xx. Voer downloads en traag werk buiten de HTTP-handler uit. Houd rekening met herhaling: de documentatie beschrijft nieuwe pogingen zonder succesvolle respons.

3. Breng polling en callbacks samen

Gebruik één afrondingshandler. Een blijvende uniciteitsregel voor taak-ID en afrondingsactie voorkomt dubbele meldingen of vervolgjobs. Alleen een tijdstempel onderscheidt events van verschillende taken onvoldoende. Negeer verouderde updates na een eindstatus en maak de worker veilig opnieuw uitvoerbaar na een crash.

Ontbreekt de callback of is de status onduidelijk, vraag dan het opgeslagen taak-ID opnieuw op. Een timeout bij opvragen rechtvaardigt niet blind een tweede betaalde taak. Onderscheid transportfouten van een bevestigde taakfout en controleer voordat u opnieuw indient.

4. Controleer foutscenario’s

Herhaal vóór uitrol een callback, stuur een verkeerd geheim, vertraag de bezorging en simuleer een workerherstart. Elke voltooide taak moet één duurzaam resultaat opleveren; bij mislukking moet de fout bewaard blijven. Volg daarna de gids voor uitvoeropslag.

Bronnen: uniform API-schema, voorbeeld van taakopvraag en webhookdocumentatie. De voorbeelden tonen integratiestructuur, geen benchmark van echte generaties.