Webhook 完成通知
Gemini 图片任务使用统一的账号级 Webhook。创建任务时不要传 webhook_url；在控制台“资源管理中心 → Webhook”配置接收地址与 wk-... 验证 Key。
事件
| 事件 | 触发条件 |
|---|---|
image.task.succeeded | Gemini 生成或编辑成功 |
image.task.failed | Gemini 生成或编辑失败 |
webhook.test | 控制台发送连接测试 |
Gemini 不增加专属事件类型。接收端可通过 data.object.model 区分模型，通过 data.object.operation 区分生成与编辑。
成功事件
json
{
"id": "evt_gemini_example123",
"object": "event",
"api_version": "2026-07-17",
"type": "image.task.succeeded",
"created_at": 1784682038,
"data": {
"object": {
"id": "task_gemini_example123",
"object": "image.task",
"model": "gemini-3.1-flash-image",
"operation": "generation",
"status": "succeeded",
"progress": 100,
"result": {
"images": [
{
"asset_id": "asset_example123",
"url": "https://img.example.com/images/result.png",
"mime_type": "image/png",
"format": "png",
"width": 1024,
"height": 1024
}
]
},
"usage": {
"prompt_tokens": 25,
"completion_tokens": 1680,
"total_tokens": 1705,
"input_tokens": 25,
"output_tokens": 1680,
"completion_tokens_details": {
"reasoning_tokens": 0
}
},
"error": null,
"created_at": 1784682000,
"started_at": 1784682001,
"completed_at": 1784682038,
"updated_at": 1784682038
}
}
}失败事件
json
{
"id": "evt_gemini_example456",
"object": "event",
"api_version": "2026-07-17",
"type": "image.task.failed",
"created_at": 1784682038,
"data": {
"object": {
"id": "task_gemini_example456",
"object": "image.task",
"model": "gemini-3-pro-image-count",
"operation": "generation",
"status": "failed",
"progress": 100,
"result": null,
"usage": {},
"error": {
"code": "524",
"message": "Image generation service is temporarily unavailable. Please try again later.",
"retryable": true
},
"created_at": 1784682000,
"started_at": 1784682001,
"completed_at": 1784682038,
"updated_at": 1784682038
}
}
}"524" 是统一图片任务协议的业务错误码，不是 HTTP 状态码。它表示内部图片服务暂时不可用；公开 Webhook 不会包含内部渠道、子分组、余额或上游 Request ID。若要重试终态失败任务，请使用新的 Idempotency-Key 创建新任务。
data.object 与任务查询接口返回的对象一致。按顶层 id 去重，因为网络错误或非 2xx 响应可能导致同一事件重复投递。
校验与重试
回调使用以下请求头：
http
Authorization: Bearer wk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json- 使用常量时间比较完整的 Authorization 值。
- 校验、去重并落入自己的任务队列后尽快返回 HTTP 2xx。
- 网络错误、超时或非 2xx 会按管理员配置重试。
- 未收到通知时使用资源 API Key 查询
/v1/image/tasks/{task_id}兜底。 - 不要在日志中记录完整 Webhook Key、提示词或图片 Base64。
完整接收端代码可复用 GPT-Image Webhook Demo，无需 Gemini 专属处理器。