# 任务回调

## 配置签名密钥

在[开发者设置](/settings/developer)创建并保存回调签名密钥。用 `POST /api/v1/jobs/createTask` 创建任意公开图像或视频模型的任务时，在请求顶层传入 `callBackUrl`。也可以使用 `callbackUrl`，同时填写时两个值须一致。推荐使用公共 HTTPS 和 443 端口。REST 兼容入口也接受其他公网 HTTP(S) 端口。投递会重新校验目标地址，拒绝私有网络且不会跟随重定向。

```json
{
  "model": "gpt-image-2.6",
  "inputs": { "prompt": "木桌上的陶瓷杯" },
  "callBackUrl": "https://hooks.example.com/i2v/completed"
}
```

## 处理终态结果

成功、失败和派发前取消都会发送 `task.completed`。用 `data.taskId` 关联原任务，用 `data.status` 和 `data.lifecycle.phase` 判断结果。事件外层的 `code: 200` 表示事件格式，生成也可能失败。

| 结果 | 读取字段 |
| --- | --- |
| `success` | 从 `data.output[].url` 下载结果。 |
| `fail` | 查看 `data.error` 和 `data.billing`。若阶段为 `cancelled`，表示任务已取消。 |

等待或待核对的任务请继续通过 `recordInfo` 查询。任务进入终态后才发送回调。

创建任务时收到 HTTP `503` 和 `reason: "callback_dns_unavailable"`，可等回调域名恢复解析后，使用原请求体和原 `Idempotency-Key` 重试。

## 验证事件

解析请求体前，读取以下请求头。

| 请求头 | 用途 |
| --- | --- |
| `X-I2V-Signature` | 带版本的签名，使用 `v1` |
| `X-I2V-Timestamp` | 参与签名的时间戳 |
| `X-I2V-Key-ID` | 签名密钥版本 |
| `X-I2V-Event-ID` | 用于去重的事件 ID |

使用签名密钥，对 `timestamp + '.' + 原始请求体` 计算十六进制 HMAC-SHA256。采用恒定时间比较校验签名。拒绝超出应用有效时间窗口的事件。保存已处理事件 ID，保证重复投递时幂等。

## 确认接收

成功接收后返回 HTTP `2xx`。即使事件已被处理，响应超时仍可能引发重复投递。系统最多自动尝试投递八次，并采用有上限的指数退避。自动重试耗尽后，可在开发者控制台查看并手动重新投递。

回调投递与任务结算独立执行。排查投递异常时，通过 [recordInfo](/docs/api)核对最终任务状态。轮换密钥时，保留旧密钥，直到待投递事件完成。