跳到主要内容

MiniMax H3 客户回调

三个创建接口均支持可选 callback_url，用于接收平台发送的任务终态通知。只使用轮询时可不传。客户地址由平台保存并通知，不会直接交给 MiniMax；平台到 MiniMax 的回调配置由管理员维护。

第一步：实现地址校验​

创建任务时，平台会先向 callback_url 发送 POST：

{"challenge":"verification_value"}

你的服务应在 3 秒内返回 HTTP 2xx，并原样回显同一个 challenge。可返回 JSON：

{"challenge":"verification_value"}

也支持响应体直接返回 challenge 文本。不要跳转到登录页、返回 HTML 或更改值；平台不跟随重定向。回调地址必须是平台网络可访问、符合平台 URL 安全策略的 HTTP(S) 地址。

第二步：创建任务时填写地址​

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "ratio": "16:9",
  "content": [{"type": "text", "text": "一只小猫在阳光下伸懒腰"}],
  "callback_url": "https://example.com/webhooks/minimax-h3"
}

将地址换为你的真实回调服务。未通过校验时创建请求失败；轮询接入可直接省略 callback_url。

第三步：接收终态通知​

平台仅通知终态，不推送 queued/running。通知体与查询任务相同，task.id 为平台任务 ID；视频结果在 task.content.url，Context-IR 结果在 task.content.prompt，不包含上游 usage。

{
  "task": {
    "id": "task_platform_example",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "generation",
    "modality": "video",
    "content": {"url": "https://example.com/generated-video.mp4"},
    "created_at": 1792540800
  }
}

收到通知后，在 3 秒内响应 HTTP 2xx。建议先接收保存，再异步处理下载等耗时操作。不要等待耗时操作完成才应答。

投递与核验边界​

  • 当前终态通知按一次发送尝试处理，不保证失败自动重试或至少一次送达，必须使用查询接口兜底。
  • 接收端按 task.id 幂等处理；重复通知不得重复触发业务动作。
  • challenge 仅验证地址能响应，不等于通知签名。当前客户通知没有专用签名字段或模型密钥鉴权头；请使用自己的不可猜测回调地址，并通过带平台模型密钥的查询核验任务归属、状态和结果后执行关键业务。
  • 不要把模型密钥放进回调 URL、公开日志或浏览器端代码。平台内部的 /api/callback/minimax-h3/... 不是客户需要主动调用的业务接口。