Webhook

Webhook

  • Webhook 可以在 AI 生成任务完成后向你发送实时通知。你无需持续轮询 API，只需提供一个 Webhook URL，MuAPI 就会自动发送包含任务结果的 POST 请求。

使用 Webhook

  • 在 API 请求中加入 webhook 参数即可接入 Webhook。提供的 URL 必须是可访问的 HTTPS 端点，并且能够处理 POST 请求。

请求格式

  • API 请求的结构保持不变，只需将 Webhook URL 作为查询参数加入即可。

1. cURL

curl --location --request POST 'https://muapi.ai/api/v1/endpoint/generate_wan_ai_effects?webhook=https://your.app.user/endpoints' \
--header "Content-Type: application/json" \
--header "x-api-key: {MUAPIAPP_API_KEY}" \
--data-raw '{"param1": "value1", "param2": "value2"}

2. Python

import requests
import json

url = "https://muapi.ai/api/v1/endpoint/generate_wan_ai_effects"

params = {
  "webhook": "https://your.app.user/endpoints"
}

headers = {
  "x-api-key": f"{MUAPIAPP_API_KEY}",
  "Content-Type": "application/json"
}

payload = {
  "param1": "value1",
  "param2": "value2"
}

response = requests.post(url, headers=headers, params=params, json=payload)
print(response.json())

Webhook 负载

  • Webhook 触发后，会收到一个包含任务结果的 POST 请求。响应格式包括状态信息和相关元数据：

    • completed：任务成功完成，可以获取结果。
    • failed：任务遇到错误，具体信息位于 error 字段。

  • Webhook 端点被调用时，会收到以下结构的 POST 请求：

    {
  "id": "<task_id>",
  "outputs": [
    "<output_url>" // 仅在任务成功时存在
  ],
  "urls": {
    "get": "https://api.muapi.ai/api/v1/predictions/<task_id>/result"
  },
  "has_nsfw_contents": [
    false
  ],
  "status": "completed", // 或 "failed"
  "created_at": "<created_at>",
  "error": "<error>", // 当 status 为 "failed" 时存在
  "executionTime": "<time>",
  "timings": {
    "inference": "<time>"
  }
}

最佳实践

  1. 使用 HTTPS： 始终保护你的 Webhook 端点。
  2. 实现重试逻辑： 确保端点能够优雅地处理临时问题。
  3. 验证请求： 增加校验机制，确认 Webhook 请求确实来自可信来源。
  4. 快速响应： 端点应尽快返回 2xx HTTP 状态码。
  5. 确保幂等性： 防止同一个 Webhook 被多次发送时重复处理。

错误处理

  • 如果你的端点无法访问或返回错误，我们会使用指数退避最多重试三次发送。请确保端点具备足够的稳定性，能够处理预期的请求量。
Webhook — Muapi Docs