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 被多次発送時重复处理。

错误处理

  • 如果你的エンドポイント无法访問或返回错误，我たち会使用指数退避最多重试三次発送。请确保エンドポイント具备足够的稳定性，能够处理预期的请求量。