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

i2v.ai接收并验证带签名的生成完成事件。
在创建并保存回调签名密钥。用 POST /api/v1/jobs/createTask 创建任意公开图像或视频模型的任务时,在请求顶层传入 callBackUrl。也可以使用 callbackUrl,同时填写时两个值须一致。推荐使用公共 HTTPS 和 443 端口。REST 兼容入口也接受其他公网 HTTP(S) 端口。投递会重新校验目标地址,拒绝私有网络且不会跟随重定向。
{
"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。即使事件已被处理,响应超时仍可能引发重复投递。系统最多自动尝试投递八次,并采用有上限的指数退避。自动重试耗尽后,可在开发者控制台查看并手动重新投递。
回调投递与任务结算独立执行。排查投递异常时,通过 核对最终任务状态。轮换密钥时,保留旧密钥,直到待投递事件完成。