PiAPI sorgulama ve webhook: görev tamamlanmasını güvenilir işleme

Bir görüntü veya video isteğinin kabul edilmesi, tamamlanma akışını bitirmez. PiAPI birleşik API görevlerinde kimliği kaydedin, son durumu izleyin ve çıktıyı modele göre işleyin. İlk entegrasyonda düzenli sorgulama uygundur; webhook ise iş bittiğinde arka ucun tepki vermesini sağlar.

1. Görev kimliğini kaydedin ve sorgulamayı sınırlayın

Oluşturduktan sonra data.task_id değerini kendi iş kimliğinizle saklayın. Sunucu tarafındaki API anahtarıyla aynı görevi sorgulayın. Başarılı HTTP yanıtı üretimin bittiğini kanıtlamaz: data.status alanını inceleyin.

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

completed için modele özgü data.output alanını doğrulayın; failed için data.error alanını kaydedin. Denemeleri sınırlayın, aralıkları artırın ve rastgele gecikme ekleyin. Uygulamanın bekleme süresi yerel bir tercihtir; dolması uzaktaki görevin başarısız veya iptal olduğunu göstermez. Sonradan uzlaştırmak için kimliği saklayın.

2. Doğrulanan bir geri çağrı ekleyin

Aşağıdaki yapılandırmayı geçerli görev oluşturma gövdesine eklerken mevcut alanları koruyun. Herkese açık HTTPS uç noktası ve arka ucun güvenli deposundaki gizli değeri kullanın. PiAPI belgelerine göre bu değer x-webhook-secret başlığında gönderilir; bildirimi kabul etmeden doğrulayın.

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

Webhook JSON verisi timestamp ve data içerir. Görevin uygulamanıza ait olduğunu kontrol edin, olayı kalıcı olarak kaydedin veya kalıcı kuyruğa alın ve hızla 2xx yanıtı verin. İndirme ve uzun işleri HTTP işleyicisinin dışında yapın. Tekrarlı teslimatı bekleyin: belgeler başarılı yanıt alınmadığında yeniden denemeleri açıklar.

3. Sorgulama ve geri çağrıları birleştirin

İki yol için aynı tamamlanma işleyicisini kullanın. Görev kimliği ve son işlem üzerinde kalıcı benzersizlik kısıtı, çift bildirim veya çift sonraki işi önler. Tek başına zaman damgası farklı görevlerin olaylarını ayırt etmeye yetmez. Son durumdan sonraki eski güncellemeleri yok sayın; işçiyi çökmeden sonra güvenle yeniden çalıştırılabilir yapın.

Geri çağrı eksikse veya durum belirsizse kaydedilen kimliği yeniden sorgulayın. Sorgu zaman aşımı, körlemesine başka ücretli görev oluşturmaya gerekçe değildir. İletim hatasını doğrulanmış görev hatasından ayırın ve yeniden göndermeden önce durumu uzlaştırın.

4. Hata durumlarını sınayın

Yayımlamadan önce geri çağrıyı tekrarlayın, yanlış gizli değer gönderin, teslimatı geciktirin ve işçi yeniden başlatmasını taklit edin. Tamamlanan her görevin tek kalıcı sonuç ürettiğini ve başarısız görevlerin hatayı koruduğunu doğrulayın. Ardından çıktı saklama kılavuzunu izleyin.

Kaynaklar: birleşik API şeması, görev sorgulama örneği ve webhook belgeleri. Örnekler entegrasyon yapısını gösterir; canlı üretim performans testi değildir.