MoonApiX Docs

Appearance

Webhook 和回调 ​

部分异步任务可以通过 callback_url 在任务完成后回调用户服务。Webhook 适合视频生成、数字人合成、音乐生成等耗时任务。

请求方式 ​

MoonApiX 会向用户提供的 callback_url 发送 POST 请求。

json
{
  "id": "task_01HX...",
  "object": "task",
  "status": "succeeded",
  "model": "seedance-2.0-kz-fast",
  "created_at": 1710000000,
  "output": [
    {
      "type": "video",
      "url": "https://example.com/result.mp4"
    }
  ],
  "error": null
}

失败任务会包含标准错误对象：

json
{
  "id": "task_01HX...",
  "object": "task",
  "status": "failed",
  "error": {
    "message": "Task failed.",
    "type": "task_error",
    "code": "task_failed"
  }
}

接收建议 ​

  • 回调接口应在 10 秒内返回 2xx。
  • 不要依赖回调只发送一次，接收端应按 task_id 做幂等处理。
  • 如果回调丢失，仍可通过任务查询接口主动查询。
  • 回调地址必须是公网可访问的 HTTPS URL。
  • 回调 payload 以本文档展示的 MoonApiX 字段为准。

安全建议 ​

  • 为回调地址设置随机路径或服务端鉴权。
  • 校验 task_id 是否属于当前用户或当前业务订单。
  • 不要在回调 URL query 中放置 API Key、用户 token 或订单敏感信息。
  • 回调日志只记录必要字段，避免保存完整用户素材或生成结果。