一、教程前置说明：核心技术背景与对接前提

1.1 模型核心信息

本次对接的谷歌Nano-Banana系列模型，是专注于图像一致性生成的轻量化高性能模型，核心支持的2个生产级模型版本及技术参数如下：

模型标识	技术代号	输入格式	输出分辨率	核心优势	延迟范围
Nano-Banana基础版	gemini-2.0-flash-preview-image-generation	参考图（JPG/PNG，≤10MB）+ JSON格式提示词	最高1024×1024	高细节还原，支持复杂场景构建	500ms-1.2s
Nano-Banana进阶版	gemini-2.5-flash-image-preview	参考图（JPG/PNG，≤15MB）+ 结构化提示词（含风格/比例参数）	最高2048×2048	实时预览，人物/物体一致性误差≤3%	300ms-800ms

基于阿波罗 AI 平台（api.ablai.top）的高一致性图像生成集成指南

1.2 对接环境要求

• 开发语言：Python 3.8+（推荐3.10）、JavaScript（Node.js 16+）
• 依赖库：Python需安装requests==2.31.0（接口请求）、Pillow==10.1.0（图像预处理）；JavaScript需安装axios==1.6.2、form-data==4.0.0
• 网络环境：需支持HTTPS协议，确保能访问api.ablai.top域名（建议配置超时重试机制，超时时间设为5s）
• 权限准备：注册阿波罗AI平台账号（https://api.ablai.top），在「工作台-API密钥」中生成专属Access Token（权限需勾选「Nano-Banana模型调用」）

二、核心对接流程：从接口认证到图像生成

2.1 接口基础信息

接口项	技术参数
接口地址	https://api.ablai.top/v1/models/nano-banana/generate
请求方法	POST
认证方式	Bearer Token（在请求头中携带Authorization: Bearer {your_access_token}）
内容类型	multipart/form-data（用于上传参考图）+ application/json（用于传递文本参数）
响应格式	JSON（含生成图像的base64编码或临时URL）

2.2 关键参数详解（请求体）

2.2.1 必选参数

参数名	类型	说明	示例值
model_code	String	模型选择，二选一： - 基础版：gemini-2.0-flash-preview-image-generation - 进阶版：gemini-2.5-flash-image-preview	"gemini-2.5-flash-image-preview"
reference_image	File	参考图文件流，需满足： - 格式：JPG/PNG - 尺寸：最小256×256，最大4096×4096 - 大小：≤对应模型的输入限制	（Python：open(“reference.jpg”, “rb”)；JS：new File([blob], “ref.png”)）
prompt	String	结构化提示词，需包含「主体特征+风格要求+输出规格」，推荐使用Markdown列表格式增强解析精度	"1. 主体：基于参考图的1/7 scale手办，保留人物服饰纹理；2. 风格：写实风，环境为电脑桌（含透明亚克力底座）；3. 输出：分辨率2048×2048，无文字水印"

2.2.2 可选参数（优化生成效果）

参数名	类型	说明	示例值
aspect_ratio	String	输出比例，仅进阶版支持，可选：1:1/3:4/4:3/16:9	"3:4"
consistency_level	Integer	一致性等级（1-5），5级最高（特征还原度≥95%），1级最低（保留基础轮廓）	5
style_preset	String	预设风格，可选：photorealistic（写实）/minimalist（极简）/vibrant（活力）/anime（动漫）	"photorealistic"
preview_enable	Boolean	是否开启实时预览（仅进阶版支持），开启后会先返回低清预览图（256×256），确认后生成高清图	true

2.3 完整代码示例（Python/JavaScript）

2.3.1 Python示例（进阶版模型，带预览功能）

import requests
from PIL import Image
from io import BytesIO
import base64

# 1. 基础配置
ACCESS_TOKEN = "your_access_token_here"
API_URL = "https://api.ablai.top/v1/models/nano-banana/generate"
HEADERS = {
    "Authorization": f"Bearer {ACCESS_TOKEN}"
}

# 2. 图像预处理（确保尺寸符合要求）
def preprocess_image(image_path, max_size=4096):
    img = Image.open(image_path)
    if max(img.size) > max_size:
        img.thumbnail((max_size, max_size))  # 按比例缩放
    img_byte_arr = BytesIO()
    img.save(img_byte_arr, format='PNG')
    img_byte_arr = img_byte_arr.getvalue()
    return img_byte_arr

# 3. 构造请求数据
reference_img = preprocess_image("sand_gold_figure.jpg")  # 参考图路径
payload = {
    "model_code": "gemini-2.5-flash-image-preview",
    "prompt": "1. 主体：基于参考图的崩铁砂金手办，1/7 scale，保留金属质感与服饰褶皱；2. 风格：写实风，环境为电脑桌（含Zbrush建模界面屏幕、BANDAI风格玩具盒）；3. 输出：分辨率2048×2048，底座无文字",
    "aspect_ratio": "3:4",
    "consistency_level": 5,
    "style_preset": "photorealistic",
    "preview_enable": True
}

# 4. 发送请求（multipart/form-data格式）
files = {
    "reference_image": ("reference.png", reference_img, "image/png")
}
response = requests.post(API_URL, headers=HEADERS, data=payload, files=files, timeout=10)

# 5. 处理响应
if response.status_code == 200:
    result = response.json()
    # 5.1 处理预览图
    if result["preview_enable"] and "preview_image" in result:
        preview_base64 = result["preview_image"]
        preview_img = Image.open(BytesIO(base64.b64decode(preview_base64)))
        preview_img.save("preview_figure.png")
        print("预览图已保存：preview_figure.png")
        # 确认生成高清图（若预览符合要求）
        confirm_payload = {
            "task_id": result["task_id"],
            "confirm": True
        }
        confirm_response = requests.post(
            f"{API_URL}/confirm",
            headers=HEADERS,
            json=confirm_payload
        )
        if confirm_response.status_code == 200:
            highres_base64 = confirm_response.json()["highres_image"]
            highres_img = Image.open(BytesIO(base64.b64decode(highres_base64)))
            highres_img.save("highres_figure.png")
            print("高清图已保存：highres_figure.png")
    else:
        # 直接生成高清图（未开启预览）
        highres_base64 = result["highres_image"]
        highres_img = Image.open(BytesIO(base64.b64decode(highres_base64)))
        highres_img.save("highres_figure.png")
else:
    print(f"请求失败：{response.status_code} - {response.text}")

2.3.2 JavaScript示例（基础版模型，生成品牌海报）

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const path = require('path');

// 1. 基础配置
const ACCESS_TOKEN = "your_access_token_here";
const API_URL = "https://api.ablai.top/v1/models/nano-banana/generate";
const HEADERS = {
    "Authorization": `Bearer ${ACCESS_TOKEN}`,
    ...FormData.getHeaders()  // 自动添加multipart/form-data头
};

// 2. 构造请求数据
const formData = new FormData();
// 2.1 添加模型参数
formData.append("model_code", "gemini-2.0-flash-preview-image-generation");
formData.append("prompt", "1. 主体：基于参考图的雪服模特，保留服装版型与Logo位置；2. 风格：极简风，背景为浅灰渐变；3. 输出：分辨率1920×1080，Logo置于顶部居中");
formData.append("style_preset", "minimalist");
// 2.2 添加参考图（读取本地文件）
const imgPath = path.join(__dirname, "snowboard_model.jpg");
const imgFile = fs.createReadStream(imgPath);
formData.append("reference_image", imgFile, {
    filename: "reference.jpg",
    contentType: "image/jpeg"
});

// 3. 发送请求
axios.post(API_URL, formData, {
    headers: HEADERS,
    timeout: 10000,
    responseType: "json"
})
.then(response => {
    const result = response.data;
    // 4. 保存生成的图像（base64转文件）
    const highresBase64 = result["highres_image"];
    const imgBuffer = Buffer.from(highresBase64, 'base64');
    fs.writeFileSync("brand_poster.jpg", imgBuffer);
    console.log("品牌海报已保存：brand_poster.jpg");
})
.catch(error => {
    console.error("请求失败：", error.response?.status, error.response?.data);
});

三、技术优化与问题排查

3.1 提升一致性的3个关键技巧

1. 提示词结构化：使用「主体特征+局部细节+环境约束」的三层结构，例如在生成手办时明确“服饰纹理：金属拉丝质感；底座细节：直径10cm透明亚克力；环境光：冷白光（4500K）”，减少模型歧义。
2. 参考图预处理：若参考图存在模糊或噪声，可先用Pillow（Python）或Sharp（JS）进行锐化处理（如高斯锐化，半径1.5， sigma 0.8），提升模型特征提取精度。
3. 一致性等级动态调整：生成人物图像时建议设consistency_level=5（避免“换头”），生成场景化图像时设3-4级（平衡一致性与创作灵活性）。

3.2 常见错误码与解决方案

错误码	错误信息	解决方案
401	“Invalid Access Token”	1. 检查Access Token是否过期（有效期7天，需在平台重新生成）；2. 确认Token权限是否包含「Nano-Banana调用」
400	“Reference image size exceeds limit”	1. 检查图像大小（基础版≤10MB，进阶版≤15MB）；2. 按preprocess_image函数逻辑缩放图像，确保尺寸≤4096×4096
429	“Rate limit exceeded”	1. 查看平台「模型价格-调用限制」（免费用户通常10次/分钟）；2. 实现请求队列，添加100ms间隔重试机制
500	“Model generation failed”	1. 简化提示词（避免同时包含复杂场景+多物体）；2. 关闭preview_enable，直接生成高清图；3. 10秒后重试（可能为临时服务波动）

四、生产级应用扩展建议

4.1 批量生成优化

• 采用「异步任务队列」模式：通过/v1/models/nano-banana/async-generate接口提交批量任务，获取task_id后，通过/v1/models/nano-banana/task-result?task_id={id}轮询结果（轮询间隔建议3s），避免同步请求阻塞。
• 图像存储：生成的base64编码图像建议转存至OSS（如阿里云OSS、AWS S3），并记录image_url与task_id关联，便于后续溯源。

4.2 一致性校验工具

• 集成「结构相似性指数（SSIM）」计算：使用skimage.metrics.structural_similarity（Python）对比参考图与生成图的SSIM值，当值≥0.85时判定为“高一致性”，可自动通过；＜0.85时触发人工审核。
• 关键特征校验：针对手办/海报的核心元素（如Logo、人物五官），使用目标检测模型（如YOLOv8）定位特征区域，确认生成图中特征位置偏差≤5%。

4.3 成本控制

• 按模型选择场景：快速预览、低精度需求（如社交媒体配图）使用gemini-2.0-flash（单价更低）；高清商业化素材（如电商海报、手办渲染图）使用gemini-2.5-flash（细节更优）。
• 流量节省：通过aspect_ratio参数固定输出比例，避免生成后二次裁剪（减少无效像素生成，降低存储成本）。