Polling et webhooks PiAPI : traiter la fin des tâches de façon fiable

L’acceptation d’une demande d’image ou de vidéo ne termine pas le travail d’intégration. Pour une tâche utilisant l’API unifiée de PiAPI, conservez son identifiant, observez son état final, puis traitez la sortie propre au modèle. Le polling convient à une première intégration ; les webhooks permettent au backend de réagir à la fin du travail.

1. Conserver l’identifiant et limiter le polling

Après la création, enregistrez data.task_id avec votre identifiant de traitement. Interrogez la même tâche avec la clé API côté serveur. Une réponse HTTP réussie ne prouve pas la fin de la génération : vérifiez 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}"

Pour completed, validez data.output selon le modèle ; pour failed, conservez data.error. Limitez les tentatives, augmentez les délais et ajoutez une variation aléatoire. La durée maximale d’attente est un choix de votre application : la dépasser ne prouve ni l’échec ni l’annulation de la tâche distante. Gardez l’identifiant pour une vérification ultérieure.

2. Ajouter un callback authentifié

Fusionnez le fragment ci-dessous avec un corps de création valide, en conservant les champs de configuration existants. Utilisez une adresse HTTPS publique et un secret issu du stockage sécurisé de votre backend. Selon la documentation PiAPI, ce secret est envoyé dans l’en-tête x-webhook-secret : vérifiez-le avant d’accepter la notification.

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

Le JSON contient timestamp et data. Vérifiez que la tâche appartient à votre application, puis enregistrez durablement l’événement ou placez-le dans une file persistante et répondez rapidement en 2xx. Effectuez les téléchargements hors du gestionnaire HTTP. Prévoyez les doublons : la documentation décrit des nouvelles tentatives en l’absence de réponse réussie.

3. Réunir polling et callbacks

Utilisez un gestionnaire de fin commun. Une contrainte d’unicité persistante sur l’identifiant de tâche et l’action finale évite les notifications doubles et le lancement de deux traitements suivants. Un horodatage seul n’identifie pas les événements de tâches différentes. Ignorez les mises à jour anciennes après l’état final et rendez le worker réexécutable après un arrêt brutal.

Si le callback manque ou reste ambigu, relisez la tâche enregistrée. Un délai dépassé lors de cette lecture ne justifie pas de créer aveuglément une autre tâche payante. Distinguez une erreur de transport d’un échec confirmé et vérifiez avant de soumettre à nouveau.

4. Vérifier les cas d’échec

Avant le déploiement, rejouez un callback, envoyez un mauvais secret, retardez la livraison et simulez un redémarrage du worker. Chaque tâche terminée doit produire un seul résultat durable ; chaque échec doit conserver son erreur. Suivez ensuite le guide de stockage des sorties.

Références : schéma de l’API unifiée, exemple de lecture d’une tâche et documentation des webhooks. Les exemples expliquent l’intégration ; ils ne constituent pas un benchmark de génération réelle.