Webhook 和回调

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

请求方式

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

对于视频任务（包括 seedance-2.0-sz、seedance-2.0-sz-fast、 seedance-2.0-sz-mini 和 seedance-2.5-sz），回调使用与官方任务接口一致的字段形状。 任务状态变化时可能收到多次回调，常见顺序为 queued -> running -> succeeded 或 queued -> running -> failed。回调中的 id 是 MoonApiX 公共任务 ID；请以 status 和 error 判断任务结果，不要仅凭是否存在 URL 判断成功。

{
  "id": "task_01HX...",
  "object": "task",
  "status": "succeeded",
  "model": "seedance-2.0-kz-fast",
  "created_at": 1710000000,
  "content": {
    "video_url": "https://example.com/result.mp4"
  },
  "error": null
}

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

{
  "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 字段为准。
• 终态成功回调可能返回一个临时签名媒体 URL；应在有效期内下载或转存，并保留完整 URL（包括 query 参数）。
• 如果终态回调没有可用结果 URL，使用任务查询接口或视频内容接口作为兜底。
• 回调接收成功不代表任务成功；failed、cancelled 或 expired 状态必须先处理 error。

安全建议

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