Skip to main content
当您向 NanoBanana Pro API 提交图像生成任务时,可以通过 callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。

回调机制概述

回调机制避免了您需要轮询 API 查询任务状态,系统会主动推送任务完成结果到您的服务器。

回调时机

系统会在以下情况发送回调通知:
  • NanoBanana Pro 图像生成任务成功完成
  • NanoBanana Pro 图像生成任务失败
  • 任务处理过程中发生错误

回调方式

  • HTTP 方法: POST
  • 内容类型: application/json
  • 超时设置: 15 秒

回调请求格式

任务完成后,系统会向您的 callBackUrl 发送 POST 请求,格式如下:

状态码说明

integer
必填
回调状态码,表示任务处理结果:
string
必填
状态消息,提供详细的状态描述
string
必填
任务 ID,与您提交任务时返回的 taskId 一致
string
生成图像在我们服务器上的 URL。仅在成功时存在。

回调接收示例

以下是用流行编程语言接收 NanoBanana Pro 回调的示例代码:

最佳实践

回调 URL 配置建议

  1. 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一个 taskId 可能收到多次回调,确保处理逻辑是幂等的
  4. 快速响应: 回调处理应尽快返回 200 状态码,避免超时
  5. 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
  6. 及时下载: 收到成功回调后建议及时下载图像文件

重要提醒

  • 回调 URL 必须是公网可访问的地址
  • 服务器必须在 15 秒内响应,否则会被认为是超时
  • 连续 3 次重试失败后,系统将停止发送回调
  • 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
  • 正确解析 data.info.resultImageUrl 字段以获取生成的图像 URL
  • 需要处理多种错误状态码(400, 500, 501),实现完整的错误处理
  • 适当处理成功和失败场景

故障排查

如果没有收到回调通知,请检查以下几点:
  • 确认回调 URL 可以从公网访问
  • 检查防火墙设置,确保入站请求没有被阻止
  • 验证域名解析是否正确
  • 确保服务器在 15 秒内返回 HTTP 200 状态码
  • 检查服务器日志中的错误信息
  • 验证接口路径和 HTTP 方法是否正确
  • 确认接收到的 POST 请求体是 JSON 格式
  • 检查 Content-Type 是否为 application/json
  • 验证 JSON 解析是否正确,特别是嵌套的 JSON 字符串
  • 确认 data.info.resultImageUrl 中的图像 URL 可以正常访问
  • 检查图像下载权限和网络连接
  • 验证图像保存路径和权限
  • 实现合理的图像下载和存储逻辑
  • 查看错误消息中的内容政策违规提示
  • 调整被标记的提示词内容
  • 确保提示词符合平台内容准则
  • 检查是否包含敏感或不当内容
  • 检查生成参数是否合理
  • 验证输入图像格式和质量(用于 auto 宽高比)
  • 确认提示词长度和格式
  • 考虑调整生成参数后重试

替代方案

如果无法使用回调机制,您也可以使用轮询方式:

轮询查询结果

使用获取任务详情接口定期查询任务状态,建议每 30 秒查询一次。