任务回调

在 POST /v1/tasks 的顶层请求体传入 callback_url，LLMAPI 会在任务进入 succeeded、failed、timeout 或 canceled 终态后发送一次 HTTP POST 通知。

json

{
  "model": "seedance-2-0-fast",
  "modality": "video",
  "callback_url": "https://client.example.com/webhooks/llmapi",
  "params": {
    "prompt": "海边日出，镜头缓慢推进",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

callback_url 必须是绝对 HTTP(S) URL，最长 2048 字节，不能包含用户名、密码或 URL fragment。目标必须能被 LLMAPI 服务端公网访问；出于 SSRF 防护，内网、回环和其他受限地址会被拒绝，重定向也不会被跟随。

请求载荷

json

{
  "id": "75d9fb6592f64a75a4bd8f868db31752.1785987723000000000",
  "type": "task.succeeded",
  "created_at": 1785987723,
  "data": {
    "task": {
      "id": "75d9fb6592f64a75a4bd8f868db31752",
      "status": "succeeded",
      "modality": "video",
      "model": "seedance-2-0-fast",
      "created_at": "2026-08-06T00:01:03Z",
      "finished_at": "2026-08-06T00:02:03Z",
      "estimated_cost": 0.75,
      "actual_cost": 0.75,
      "result": {
        "duration": 5,
        "data": [{ "index": 0, "kind": "video", "url": "https://..." }]
      },
      "assets": [{ "index": 0, "kind": "video", "url": "https://..." }]
    }
  }
}

data.task 与 GET /v1/tasks/{id} 的公共任务响应一致。资产 URL 带有有效期，应及时下载；长期保存请使用任务 API Key 调用下载资产接口。

签名验证

每次请求包含以下 Header：

text

X-LLMAPI-Delivery: 75d9fb6592f64a75a4bd8f868db31752.1785987723000000000
X-LLMAPI-Timestamp: 1785987723
X-LLMAPI-Signature: v1=<hex-encoded-hmac>

签名密钥是提交任务时使用的任务 API Key。签名内容按原始字节拼接：

text

X-LLMAPI-Delivery + "." + X-LLMAPI-Timestamp + "." + raw_request_body

使用 HMAC-SHA256 计算后，与 X-LLMAPI-Signature 中 v1= 后的十六进制值做常量时间比较。还应检查时间戳是否在可接受窗口内。

重试与幂等

接收端返回任意 2xx 即视为成功；网络错误、超时或非 2xx 响应会进行有限次数的指数退避重试。
投递语义是至少一次。相同任务终态的重试使用相同 X-LLMAPI-Delivery，接收端应按此字段去重，并在完成自己的持久化后再返回 2xx。
callback 失败不会改变任务状态、结果、资产或扣费。停止自动重试后，任务仍可通过查询接口获取。
callback 只通知终态；如果未传 callback_url，请轮询 GET /v1/tasks/{id}。

任务回调 ​

请求载荷 ​

签名验证 ​

重试与幂等 ​

任务回调

请求载荷

签名验证

重试与幂等