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 文書。例は連携構造を示すもので、実際の生成ベンチマークではありません。
