Polling dan Webhook PiAPI: Menangani Penyelesaian dengan Andal

Permintaan gambar atau video yang diterima masih membutuhkan alur penyelesaian. Untuk tugas API Terpadu PiAPI, simpan ID, periksa status akhir, lalu tangani output sesuai model. Polling cocok untuk integrasi pertama; webhook memungkinkan backend bereaksi saat pekerjaan selesai.

1. Simpan ID tugas dan batasi polling

Setelah membuat tugas, simpan data.task_id bersama ID pekerjaan Anda. Ambil tugas yang sama dengan kunci API sisi server. Respons HTTP berhasil tidak membuktikan generasi selesai: periksa 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}"

Untuk completed, validasi data.output sesuai model; untuk failed, catat data.error. Batasi percobaan, tingkatkan jeda, dan tambahkan variasi acak. Batas tunggu aplikasi merupakan pilihan lokal: melewatinya tidak membuktikan tugas jarak jauh gagal atau dibatalkan. Simpan ID untuk rekonsiliasi berikutnya.

2. Tambahkan callback terautentikasi

Gabungkan potongan berikut ke badan permintaan pembuatan tugas yang valid dengan mempertahankan konfigurasi yang ada. Gunakan endpoint HTTPS publik dan rahasia dari penyimpanan aman backend. Dokumentasi PiAPI menyatakan rahasia dikirim melalui header x-webhook-secret; verifikasi sebelum menerima notifikasi.

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

JSON webhook berisi timestamp dan data. Pastikan tugas milik aplikasi Anda, simpan peristiwa secara persisten atau masukkan ke antrean persisten, lalu segera balas 2xx. Jalankan unduhan dan pekerjaan lambat di luar handler HTTP. Antisipasi pengiriman berulang: dokumentasi menjelaskan percobaan ulang saat respons berhasil tidak diterima.

3. Satukan polling dan callback

Gunakan handler penyelesaian yang sama untuk kedua jalur. Batasan unik persisten pada ID tugas dan tindakan akhir mencegah notifikasi ganda atau pekerjaan lanjutan ganda. Timestamp saja tidak cukup untuk membedakan peristiwa antar-tugas. Abaikan pembaruan lama setelah status akhir dan buat worker aman dicoba ulang setelah mogok.

Jika callback hilang atau status tidak jelas, ambil lagi ID tugas tersimpan. Timeout pengambilan bukan alasan membuat tugas berbayar lain secara membabi buta. Bedakan gangguan transportasi dari kegagalan tugas yang terkonfirmasi dan rekonsiliasi sebelum mengirim ulang.

4. Periksa skenario kegagalan

Sebelum rilis, ulangi callback, kirim rahasia yang salah, tunda pengiriman, dan simulasikan restart worker. Pastikan setiap tugas selesai menghasilkan satu hasil persisten dan setiap kegagalan menyimpan galatnya. Lanjutkan dengan panduan penyimpanan output.

Referensi: Skema API Terpadu, contoh pengambilan tugas, dan dokumentasi webhook. Contoh menjelaskan struktur integrasi, bukan tolok ukur generasi langsung.