/api/v1/nanobanana/generate-2)提交图像生成任务时,可以通过 callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制避免了您需要轮询 API 查询任务状态,系统会主动推送任务完成结果到您的服务器。
回调时机
系统会在以下情况发送回调通知:- Generate-2 图像生成任务成功完成
- Generate-2 图像生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP 方法: POST
- 内容类型: application/json
- 超时设置: 15 秒
回调请求格式
任务完成后,系统会向您的callBackUrl 发送 POST 请求。当前线上实际返回结构示例如下:
字段与状态说明
integer
必填
顶层
当前实现中正常回调时一般为 200,具体生成是否成功请结合
code 字段,表示回调请求本身是否成功。当前实现中正常回调时一般为 200,具体生成是否成功请结合
data.successFlag 和 data.errorCode 判断。string
必填
状态消息,一般为
"success",详细错误原因请查看 data.errorMessage。string
必填
任务 ID,与您提交任务时返回的
taskId 一致。integer
必填
生成状态标志,含义与「获取任务详情」接口一致:
integer
错误码,当
successFlag ≠ 1 时用于指示失败原因,例如:422: 输入或输出被判定为敏感内容(见示例中的敏感内容失败回调)
string
错误信息字符串,通常包含更详细的失败原因描述。
string
生成图像在我们服务器上的 URL,仅在
successFlag = 1 且生成成功时存在。string
本次调用使用的参数 JSON 字符串快照,便于排查问题和审计。
string
内部使用的模型/配置标识,例如
"nano-banana-2_1k"。string
任务创建时间。
string
任务完成时间。
回调接收示例
以下是用流行编程语言接收 NanoBanana Generate-2 回调的示例代码:- Node.js
- Python
- PHP
最佳实践
故障排查
如果没有收到回调通知,请检查以下几点:网络连接问题
网络连接问题
- 确认回调 URL 可以从公网访问
- 检查防火墙设置,确保入站请求没有被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志中的错误信息
- 验证接口路径和 HTTP 方法是否正确
内容格式问题
内容格式问题
- 确认接收到的 POST 请求体是 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析是否正确
图像处理问题
图像处理问题
- 确认图像 URL 可以正常访问
- 检查图像下载权限和网络连接
- 验证图像保存路径和权限
- 实现合理的图像下载和存储逻辑
内容政策问题
内容政策问题
- 查看错误消息中的内容政策违规提示
- 调整被标记的提示词内容
- 确保提示词符合平台内容准则
- 检查是否包含敏感或不当内容
任务失败问题
任务失败问题
- 检查生成参数是否合理
- 验证输入图像格式和质量(用于 auto 宽高比)
- 确认提示词长度和格式
- 考虑调整生成参数后重试
替代方案
如果无法使用回调机制,您也可以使用轮询方式:轮询查询结果
使用获取任务详情接口定期查询任务状态,建议每 30 秒查询一次。