跳转到主要内容
当您向 NanoBanana Generate-2 接口(/api/v1/nanobanana/generate-2)提交图像生成任务时,可以通过 callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。

回调机制概述

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

回调时机

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

回调方式

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

回调请求格式

任务完成后,系统会向您的 callBackUrl 发送 POST 请求。当前线上实际返回结构示例如下:
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "31ce2c17b257492959d62279e6d01a54",
    "paramJson": "{...}",
    "completeTime": "2026-02-27 24:00:00",
    "response": {
      "originImageUrl": null,
      "resultImageUrl": "https://tempfile.aiquickdraw.com/gemini-preview/xxxxxx.jpeg"
    },
    "successFlag": 1,
    "errorCode": null,
    "errorMessage": null,
    "operationType": "nano-banana-2_1k",
    "createTime": "2026-02-27 24:00:00"
  }
}

字段与状态说明

code
integer
必填
顶层 code 字段,表示回调请求本身是否成功。
当前实现中正常回调时一般为 200,具体生成是否成功请结合 data.successFlagdata.errorCode 判断。
msg
string
必填
状态消息,一般为 "success",详细错误原因请查看 data.errorMessage
data.taskId
string
必填
任务 ID,与您提交任务时返回的 taskId 一致。
data.successFlag
integer
必填
生成状态标志,含义与「获取任务详情」接口一致:
含义
0生成中 - 任务正在处理中
1成功 - 图像生成成功,可从 response.resultImageUrl 获取结果图像
2创建任务失败
3生成失败(例如被判定为敏感内容等)
data.errorCode
integer
错误码,当 successFlag ≠ 1 时用于指示失败原因,例如:
  • 422: 输入或输出被判定为敏感内容(见示例中的敏感内容失败回调)
data.errorMessage
string
错误信息字符串,通常包含更详细的失败原因描述。
data.response.resultImageUrl
string
生成图像在我们服务器上的 URL,仅在 successFlag = 1 且生成成功时存在。
data.paramJson
string
本次调用使用的参数 JSON 字符串快照,便于排查问题和审计。
data.operationType
string
内部使用的模型/配置标识,例如 "nano-banana-2_1k"
data.createTime
string
任务创建时间。
data.completeTime
string
任务完成时间。

回调接收示例

以下是用流行编程语言接收 NanoBanana Generate-2 回调的示例代码:
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/nanobanana-generate-2-callback', (req, res) => {
  const { code, msg, data } = req.body;
  const {
    taskId,
    successFlag,
    errorCode,
    errorMessage,
    response
  } = data || {};
  const resultImageUrl = response?.resultImageUrl || '';
  
  console.log('收到 NanoBanana Generate-2 回调:', {
    taskId,
    httpCode: code,
    successFlag,
    errorCode,
    message: msg,
    errorMessage
  });
  
  if (successFlag === 1) {
    // 任务成功完成
    console.log('NanoBanana Generate-2 任务成功完成');
    console.log(`生成图像 URL: ${resultImageUrl}`);
    
    // 下载生成的图像
    if (resultImageUrl) {
      downloadFile(resultImageUrl, `nanobanana_generate2_result_${taskId}.jpg`)
        .then(() => console.log('生成图像下载成功'))
        .catch(err => console.error('生成图像下载失败:', err));
    }
  } else {
    // 任务失败
    console.log('NanoBanana Generate-2 任务失败:', errorMessage || msg || '未知错误');
    
    if (errorCode === 422) {
      console.log('内容/安全策略校验未通过 - 请调整提示词或输入内容');
    }
  }
  
  // 返回 200 状态码确认收到回调
  res.status(200).json({ status: 'received' });
});

// 辅助函数:下载文件
function downloadFile(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    
    https.get(url, (response) => {
      if (response.statusCode === 200) {
        response.pipe(file);
        file.on('finish', () => {
          file.close();
          resolve();
        });
      } else {
        reject(new Error(`HTTP ${response.statusCode}`));
      }
    }).on('error', reject);
  });
}

app.listen(3000, () => {
  console.log('NanoBanana Generate-2 回调服务器运行在端口 3000');
});

最佳实践

回调 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 解析是否正确
  • 确认图像 URL 可以正常访问
  • 检查图像下载权限和网络连接
  • 验证图像保存路径和权限
  • 实现合理的图像下载和存储逻辑
  • 查看错误消息中的内容政策违规提示
  • 调整被标记的提示词内容
  • 确保提示词符合平台内容准则
  • 检查是否包含敏感或不当内容
  • 检查生成参数是否合理
  • 验证输入图像格式和质量(用于 auto 宽高比)
  • 确认提示词长度和格式
  • 考虑调整生成参数后重试

替代方案

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

轮询查询结果

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