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 文档。示例用于说明接入结构，不是实测生成性能。