当您向 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 字段,表示回调请求本身是否成功。
当前实现中正常回调时一般为 200,具体生成是否成功请结合 data.successFlag 和 data.errorCode 判断。
状态消息,一般为 "success",详细错误原因请查看 data.errorMessage。
任务 ID,与您提交任务时返回的 taskId 一致。
生成状态标志,含义与「获取任务详情」接口一致:| 值 | 含义 |
|---|
| 0 | 生成中 - 任务正在处理中 |
| 1 | 成功 - 图像生成成功,可从 response.resultImageUrl 获取结果图像 |
| 2 | 创建任务失败 |
| 3 | 生成失败(例如被判定为敏感内容等) |
错误码,当 successFlag ≠ 1 时用于指示失败原因,例如:
422: 输入或输出被判定为敏感内容(见示例中的敏感内容失败回调)
data.response.resultImageUrl
生成图像在我们服务器上的 URL,仅在 successFlag = 1 且生成成功时存在。
本次调用使用的参数 JSON 字符串快照,便于排查问题和审计。
内部使用的模型/配置标识,例如 "nano-banana-2_1k"。
回调接收示例
以下是用流行编程语言接收 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');
});
from flask import Flask, request, jsonify
import requests
import os
app = Flask(__name__)
@app.route('/nanobanana-generate-2-callback', methods=['POST'])
def handle_callback():
data = request.json
code = data.get('code')
msg = data.get('msg')
callback_data = data.get('data', {})
task_id = callback_data.get('taskId')
success_flag = callback_data.get('successFlag')
error_code = callback_data.get('errorCode')
error_message = callback_data.get('errorMessage')
response_data = callback_data.get('response') or {}
result_image_url = response_data.get('resultImageUrl')
print("收到 NanoBanana Generate-2 回调:")
print(f"任务 ID: {task_id}")
print(f"HTTP code: {code}, successFlag: {success_flag}, errorCode: {error_code}")
print(f"msg: {msg}, errorMessage: {error_message}")
if success_flag == 1:
# 任务成功完成
print("NanoBanana Generate-2 任务成功完成")
print(f"生成图像 URL: {result_image_url}")
# 下载生成的图像
if result_image_url:
try:
result_filename = f"nanobanana_generate2_result_{task_id}.jpg"
download_file(result_image_url, result_filename)
print(f"生成图像已下载为 {result_filename}")
except Exception as e:
print(f"生成图像下载失败: {e}")
else:
# 任务失败
print(f"NanoBanana Generate-2 任务失败: {error_message or msg}")
if error_code == 422:
print("内容/安全策略校验未通过 - 请调整提示词或输入内容")
# 返回 200 状态码确认收到回调
return jsonify({'status': 'received'}), 200
def download_file(url, filename):
"""从 URL 下载文件并保存到本地"""
response = requests.get(url, stream=True)
response.raise_for_status()
os.makedirs('downloads', exist_ok=True)
filepath = os.path.join('downloads', filename)
with open(filepath, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000)
<?php
header('Content-Type: application/json');
// 获取 POST 数据
$input = file_get_contents('php://input');
$data = json_decode($input, true);
$code = $data['code'] ?? null;
$msg = $data['msg'] ?? '';
$callbackData = $data['data'] ?? [];
$taskId = $callbackData['taskId'] ?? '';
$successFlag = $callbackData['successFlag'] ?? null;
$errorCode = $callbackData['errorCode'] ?? null;
$errorMessage = $callbackData['errorMessage'] ?? '';
$response = $callbackData['response'] ?? [];
$resultImageUrl = $response['resultImageUrl'] ?? '';
error_log("收到 NanoBanana Generate-2 回调:");
error_log("任务 ID: $taskId");
error_log("HTTP code: $code, successFlag: $successFlag, errorCode: $errorCode");
error_log("msg: $msg, errorMessage: $errorMessage");
if ($successFlag === 1) {
// 任务成功完成
error_log("NanoBanana Generate-2 任务成功完成");
error_log("生成图像 URL: $resultImageUrl");
// 下载生成的图像
if (!empty($resultImageUrl)) {
try {
$resultFilename = "nanobanana_generate2_result_{$taskId}.jpg";
downloadFile($resultImageUrl, $resultFilename);
error_log("生成图像已下载为 $resultFilename");
} catch (Exception $e) {
error_log("生成图像下载失败: " . $e->getMessage());
}
}
} else {
// 任务失败
error_log("NanoBanana Generate-2 任务失败: " . ($errorMessage ?: $msg));
if ($errorCode === 422) {
error_log("内容/安全策略校验未通过 - 请调整提示词或输入内容");
}
}
// 返回 200 状态码确认收到回调
http_response_code(200);
echo json_encode(['status' => 'received']);
function downloadFile($url, $filename) {
$downloadDir = 'downloads';
if (!is_dir($downloadDir)) {
mkdir($downloadDir, 0755, true);
}
$filepath = $downloadDir . '/' . $filename;
$fileContent = file_get_contents($url);
if ($fileContent === false) {
throw new Exception("从 URL 下载文件失败");
}
$result = file_put_contents($filepath, $fileContent);
if ($result === false) {
throw new Exception("保存文件到本地失败");
}
}
?>
最佳实践
回调 URL 配置建议
- 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个 taskId 可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应尽快返回 200 状态码,避免超时
- 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
- 及时下载: 收到成功回调后建议及时下载图像文件
重要提醒
- 回调 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 秒查询一次。