网页钩子 Webhooks

Webhook 与上面解释的队列系统协同工作，这是与队列交互的另一种方式。通过向我们提供 webhook 端点，您会在请求完成时收到通知，而不是轮询它。

这是实际工作方式，它与向队列提交某些内容非常相似，但我们要求您传递额外的 fal_webhook 查询参数。

要使用 webhook，您的请求应定向到 queue.fal.run 端点，而不是标准的 fal.run。这种区别对于启用 webhook 功能至关重要，因为它确保您的请求由旨在支持异步操作和通知的队列系统处理。

bash

curl --request POST \
  --url https://queue.fal.run/fal-ai/fast-svd\?fal_webhook\=https://url.to.your.app/api/fal/webhook \
  --header "Authorization: Key $FAL_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model_name": "stabilityai/stable-diffusion-xl-base-1.0",
  "prompt": "Photo of a cute dog"
}'

请求将排队，您将收到带有 request_id 的响应：

json

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d"
}

一旦请求在队列中处理完毕，就会向 webhook URL 发出 POST 请求，传递请求信息和生成的 payload。status 表示请求是否成功。

何时使用？

Webhook 对于需要一段时间才能处理和/或不需要立即获得结果的请求特别有用。例如，如果您正在训练一个模型，这个过程可能需要几分钟甚至几个小时，那么 Webhook 可能是完成这项工作的完美工具。

成功请求结果

以下是成功请求的示例：

json

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d",
  "status": "OK",
  "payload": {
    "images": [
      {
        "url": "https://url.to/image.png",
        "content_type": "image/png",
        "file_name": "image.png",
        "file_size": 1824075,
        "width": 1024,
        "height": 1024
      }
    ],
    "seed": 196619188014358660
  },
  "error": null
}

错误

发生错误时，status 将为 ERROR。error 属性将包含一条消息，payload 将提供错误详细信息。例如，如果您忘记传递必需的 model_name 参数，您将收到以下响应：

json

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d",
  "status": "ERROR",
  "payload": {
    "detail": [
      {
        "loc": ["body", "model_name"],
        "msg": "field required",
        "type": "value_error.missing"
      }
    ]
  },
  "error": "Invalid status code: 422"
}

最后更新于 2024 年 6 月 21 日