docs.nanobananaapi.ai
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
Support
NanoBanana API
通用API
NanoBanana API
通用API
  1. NanoBanana API
  • 欢迎使用 NanoBanana API
  • NanoBanana API 快速入门
  • 图像生成或编辑回调
  • 生成图像回调 (Nanobanana 2)
  • 生成图像 (Pro) 回调
  • 生成或编辑图像
    POST
  • 生成图像 (Nanobanana 2)
    POST
  • 生成图像 (Pro)
    POST
  • 获取任务详情
    GET
  1. NanoBanana API

生成图像 (Pro) 回调

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

回调机制概述#

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

回调时机#

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

回调方式#

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

回调请求格式#

任务完成后,系统会向您的 callBackUrl 发送 POST 请求,格式如下:
成功回调
内容违规失败回调
生成失败回调
内部错误回调
{
  "msg": "Image generated successfully.",
  "code": 200,
  "data": {
    "taskId": "9e4286b7b27960dfeb8e1d279b50b28d",
    "info": {
      "resultImageUrl": "https://tempfile.aiquickdraw.com/r/9e4286b7b27960dfeb8e1d279b50b28d_1756467493.jpg"
    }
  }
}

状态码说明#

code · integer · required
回调状态码,表示任务处理结果:
状态码说明
200成功 - 图像生成成功
400失败 - 您的提示词被网站标记为违反内容政策
500失败 - 内部错误,请稍后重试
501失败 - 图像生成任务失败
msg · string · required
状态消息,提供详细的状态描述
data.taskId · string · required
任务 ID,与您提交任务时返回的 taskId 一致
data.info.resultImageUrl · string
生成图像在我们服务器上的 URL。仅在成功时存在。

回调接收示例#

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

最佳实践#

回调 URL 配置建议#

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

重要提醒#

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

故障排查#

如果没有收到回调通知,请检查以下几点:
网络连接问题
服务器响应问题
内容格式问题
图像处理问题
内容政策问题
任务失败问题

替代方案#

如果无法使用回调机制,您也可以使用轮询方式:
轮询查询结果
使用获取任务详情接口定期查询任务状态,建议每 30 秒查询一次。
Modified at 2026-11-11 03:43:10
Previous
生成图像回调 (Nanobanana 2)
Next
生成或编辑图像
Built with