PiAPI 任務輪詢與 Webhook：可靠處理生成完成通知

圖片或影片請求被接受後，仍需要處理生成完成的流程。使用 PiAPI 統一 API 的任務，應保存任務 ID、確認最終狀態，再依模型處理輸出。初次串接可從輪詢開始；後端則可透過 Webhook 在任務結束時回應。

1. 保存任務 ID，並限制輪詢

建立任務後，將 data.task_id 與業務作業 ID 一起保存。使用伺服器端 API 金鑰查詢同一個任務。HTTP 請求成功不等於生成完成，還要檢查 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}"

狀態為 completed 時驗證模型對應的 data.output；為 failed 時記錄 data.error。等待期間限制重試次數，逐步增加間隔並加入隨機抖動。應用程式的等待期限由你設定：逾時不代表遠端任務失敗或取消。保留 ID，方便稍後核對。

2. 加入經過身分驗證的回呼

將下方設定片段合併至有效的建立任務請求主體，保留既有欄位。使用公開 HTTPS 端點，並從後端機密儲存區取得回呼密鑰。PiAPI 文件說明，密鑰透過 x-webhook-secret 標頭傳送；接受通知前先驗證。

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

Webhook JSON 包含 timestamp 和 data。確認任務屬於你的應用程式後，將事件持久保存或放入佇列，並及時回傳 2xx。下載等耗時工作移到 HTTP 處理器外執行。通知可能重複：文件說明未收到成功回應時會重試。

3. 讓輪詢與回呼進入同一流程

兩條路徑共用完成處理器。對任務 ID 和完成動作設定持久化唯一約束，可避免重複回呼發送兩次通知或啟動兩次下游作業。不同任務可能共用時間戳，因此時間戳不能單獨作為識別。最終狀態之後忽略過時更新，並讓工作程序在當機後能安全重試。

若回呼未送達或狀態不明，再次查詢已保存的任務 ID。查詢逾時不應導致盲目建立另一個付費任務。區分傳輸故障與已確認的任務失敗，核對後再決定是否重新提交。

4. 測試異常情況

上線前重播回呼、傳送錯誤密鑰、模擬延遲送達及工作程序重新啟動。確認每個完成任務只產生一份持久結果，失敗任務保留錯誤。接著依輸出儲存指南保存生成檔案。

參考：統一 API 結構、任務查詢範例與Webhook 文件。範例說明串接結構，不是實測生成效能。