Webhook 回调

概述

任务式接口默认通过轮询 GET /api/generate/status/{task_id} 获取结果。如果上游模型支持 Webhook 回调，你可以在提交时通过 input.metadata.callback_url 透传一个公网可访问的 HTTPS 地址，任务终态时由上游直接 POST 到你的服务，省去轮询。

平台并不重写回调

平台只是把 callback_url 原样透传给上游。回调请求由 上游服务商直接发起，请求体 schema、签名机制、重试策略均与该上游官方定义一致。请按对应上游文档实现接收端。

支持的上游

上游 / 模型族	透传字段	文档
可灵 Kling	`metadata.callback_url`	Kling 官方文档
字节豆包 Doubao	`metadata.callback_url`	字节火山方舟（Volcengine Ark）控制台
MiniMax Hailuo	`metadata.callback_url`	MiniMax 开放平台
Vidu	`metadata.callback_url`	Vidu 开放平台

其余上游（OpenAI Sora / Google Veo / Gemini Nano-Banana / OpenAI GPT Image 等）当前仅支持轮询，请使用查询任务状态。

提交时启用回调

callback_url 永远放在 input.metadata 下，不会被允许出现在 input 顶层：

POST /api/generate/submit
Authorization: Bearer sk-xxxxxx
Content-Type: application/json

{
  "model": "kling-v1",
  "input": {
    "prompt": "A cat playing piano in the garden",
    "metadata": {
      "callback_url": "https://your.domain/hooks/kling"
    }
  }
}

返回与不带 callback_url 时一致：

{
  "code": 200,
  "data": {
    "task_id": "task_01HF8Z3KQX2A6Y4N3R8M5W7V9P",
    "status": "not_started",
    "created_time": "2026-06-14T10:30:00"
  }
}

接收端实现要点

HTTPS 端点：上游通常拒绝 HTTP 明文。
快速 200：先返回 200，再异步处理业务逻辑，避免上游超时重试。
幂等：以 task_id 为唯一键去重，回调可能因网络重试而到达多次。
签名校验：如上游下发签名（如 Kling 使用 JWT / 时间戳），按上游文档校验后再信任 payload。
回退轮询：仍然建议为关键任务保留状态查询兜底，防止回调丢失。

与状态查询的关系

回调到达后，你拿到的是 上游原始 payload；如果想统一格式，可以收到回调时再调一次查询任务状态，拿到平台归一化后的 files[] / status / progress。

Webhook 回调

概述

支持的上游

提交时启用回调

接收端实现要点

与状态查询的关系

目录