Webhook

配置 LEAPERone Webhook，在异步图像生成及其他耗时 API 任务完成时接收回调通知。

你无需持续轮询结果。异步任务（例如图像生成）完成后，可以让 LEAPERone 主动向你的服务器推送通知。

工作方式

在请求中加入 callbackUrl。任务完成或失败后，LEAPERone 会向该 URL 发送 JSON 格式的 POST 请求。

包含 callbackUrl 的请求

{
  "model": "gpt-4o-image",
  "prompt": "A neon-lit cyberpunk cityscape",
  "callbackUrl": "https://your-server.com/webhook/image"
}

callbackUrl 必须使用 HTTPS，且不能指向私有或内部网络地址。

Webhook 负载

任务结束后，LEAPERone 会发送一个带 JSON 请求体的 POST 请求：

成功负载

{
  "id": "img-abc123",
  "status": "completed",
  "images": [
    {
      "id": "img-file-1",
      "url": "https://cdn.leaper.one/images/abc123.png"
    }
  ]
}

失败负载

{
  "id": "img-abc123",
  "status": "failed",
  "error": "Content policy violation"
}

负载字段

字段	类型	说明
`id`	string	生成任务 ID。
`status`	string	可取 `completed`、`uploading` 或 `failed`。
`images`	array	成功时出现，每项包含 `id` 和 `url`。
`error`	string	失败时出现，用于说明错误原因。

自动重试

如果你的端点返回非 2xx 状态码，或请求超过 10 秒后超时，LEAPERone 会使用指数退避重试，最多重试 5 次（从 2 秒开始，最长等待 30 秒）。

所有重试都失败后，回调会被标记为失败。你仍可以轮询 GET /v1/images/generations/:id 端点来获取结果。

验证 Webhook 来源

Webhook 当前没有用于验证签名的请求头。你可以通过以下方式保护端点：

使用难以猜测的秘密路径，例如 https://your-server.com/webhook/a8f3b2c1。
调用 GET /v1/images/generations/:id 验证负载中的 id，确认任务存在且信息匹配。
如果基础设施支持，可以只允许已知 IP 范围访问。

最佳实践

快速响应。 收到负载后立即返回 200 状态码，并在服务端异步处理数据，避免请求超时。
处理重复通知。 少数情况下，前一次请求成功后，重试请求仍可能到达。请使用 id 字段去重。
及时下载图像。 图像 URL 是临时地址，会在 1 小时后过期。