AIRI 配置 Nano Banana(Google Gemini 图像生成)完整指南:API Key、模型与分辨率设置
AIRI 配置 Nano Banana(Google Gemini 图像生成)完整指南:API Key、模型与分辨率设置
本篇技术指南讲解如何在 AIRI 中启用并配置 Nano Banana(Google AI Studio 原生 Gemini 图像生成能力):从获取 API Key、在 Settings → Providers → Artistry → Nano Banana 中填入凭据并选择默认模型与分辨率,到在 Settings → Modules → Artistry 中激活「Nano Banana (Preview)」提供方,再到结合聊天工具调用验证整条链路是否可用。读完本文,你将掌握 Nano Banana 提供方的完整配置流程、底层 API 调用原理(含源码级证据)以及常见故障的排查思路。
Nano Banana 是什么,为什么选择它
Nano Banana 是 AIRI 内置的 Artistry(图像生成)提供方之一,底层使用 Google AI Studio 的 Gemini 图像模型。如果用户已经持有 Google AI Studio 的 API Key,就可以直接复用 AIRI 内置的 Gemini 图像模型与分辨率选项(1K / 2K / 4K),无需额外搭建本地推理环境,也无需申请其他图像服务账号——这是它相比 ComfyUI、Replicate 等其他 Artistry 提供方最直接的优势。
从仓库结构看,AIRI 的 Artistry 模块是一套多提供方抽象架构:抽象接口定义在 providers/base.ts,其中 ArtistryProvider 接口统一了 generate、getStatus、cancel、initialize、setJobCallback 等方法;各提供方(ComfyUI、Replicate、Nano Banana)实现同一接口后注册到主进程的提供方注册表(见 artistry-bridge.ts):
export const artistryProviders = new Map<string, ArtistryProvider>()
artistryProviders.set('comfyui', new ComfyUIProvider())
artistryProviders.set('replicate', new ReplicateProvider())
artistryProviders.set('nanobanana', new NanoBananaProvider())
Nano Banana 提供方在仓库中的显示名称为 Nano Banana (Google AI Studio),对应实现类为 NanoBananaProvider(见 providers/nanobanana.ts)。
第一步:获取 Google AI Studio API Key
- 登录 Google AI Studio 的 API Keys 管理页面,点击创建(Create)生成一个新的 API Key。
- 确认所选图像模型(如 Gemini 3.1 Flash Image 等)在当前账号与所属地区可用——Google 的预览模型通常存在区域与配额限制,这一步骤决定了后续调用是否会返回 403/429 类错误。
- 复制 Key 并妥善保存在安全的位置,配置完成后即可粘贴到 AIRI 中。
::: warning API Key 安全须知 切勿将 API Key 提交到版本库、包含在截图里或分享给任何人。一旦 Key 疑似泄露,应立即在 Google AI Studio 中吊销并重新创建。Key 是你图像生成费用的凭据,泄露即意味着被他人冒用消耗配额。 :::
第二步:在 AIRI 中配置 Nano Banana
配置入口为 Settings → Providers → Artistry → Nano Banana,对应仓库中的设置页源码 nanobanana.vue。该页面提供三个配置项:
| 配置项 | 说明 | 可选值 / 默认值 |
|---|---|---|
| API Key | 你的 Google AI Studio API Key,输入框为密码类型(type="password"),占位符形如 AIpk... |
必填,默认空 |
| Preferred Model(默认模型) | 使用的 Gemini 图像预览模型 | gemini-3.1-flash-image-preview(默认)、gemini-3-pro-image-preview、gemini-2.5-flash-image |
| Default Resolution(默认分辨率) | 生成图像的默认目标分辨率 | 1K(默认)、2K、4K |
三个模型选项在设置页中以 modelOptions 计算属性硬编码(见 nanobanana.vue),在 i18n 文案中分别对应 "Nano Banana 2 (Gemini 3.1 Flash Image)"、"Nano Banana Pro (Gemini 3 Pro Image)"、"Nano Banana (Gemini 2.5 Flash Image)"(见 en/settings.yaml)。
配置的持久化与默认值
这些配置项通过 Pinia store(useArtistryStore)持久化,存储键与默认值定义在 stores/modules/artistry.ts:
const nanobananaApiKey = useLocalStorageManualReset<string>('artistry-nanobanana-api-key', '', persistenceOptions)
const nanobananaModel = useLocalStorageManualReset<string>(
'artistry-nanobanana-model',
'gemini-3.1-flash-image-preview',
persistenceOptions,
)
const nanobananaResolution = useLocalStorageManualReset<string>(
'artistry-nanobanana-resolution',
'1K',
persistenceOptions,
)
对应地,Electron 主进程侧以 valibot schema 定义了同名的持久化配置结构(configs/artistry.ts),默认模型同样是 gemini-3.1-flash-image-preview、默认分辨率 1K。也就是说,即使你不手动选择模型与分辨率,AIRI 也会自动使用这两个默认值发起请求。
另外注意:store 中 configured 计算属性规定,当 activeProvider 为 nanobanana 时,只有 API Key 非空才算配置完成(见 artistry.ts);若 Key 为空,界面会判定提供方未配置。
第三步:验证配置并触发图像生成
配置好提供方后,按以下步骤验证整条链路:
- 打开 Settings → Modules → Artistry,在提供方卡片中选择 Nano Banana (Preview)。该卡片仅在自定义提供方未被禁用时显示(
isCustomProvidersDisabled()为假,见 modules/artistry.vue),在 i18n 中其显示名为 "Nano Banana (Preview)"(见 en/settings.yaml)。 - 在 Settings → Modules → Consciousness 中选择一个**支持工具/函数调用(tool/function calling)**的对话模型。这是关键前提:AIRI 需要借助对话模型解析用户意图并触发 Artistry 工具调用,最终把生成请求派发给 Nano Banana 提供方。
- 回到聊天界面,让 AIRI 生成一张非敏感图片。
- 如果聊天中返回了图片,即证明 API Key → 模型 → 分辨率 → 工具调用 整条链路全部打通。
底层发生了什么:一次 Nano Banana 生成请求的完整调用链
从源码可以完整还原这次「验证」背后的执行路径:
- 触发拦截:主进程通过 artistry-bridge.ts 中的
handleArtistryTrigger拦截组件更新,检测到componentName为comfy/artistry且状态为generating时,开始派发生成任务。 - 防重复保护:bridge 用「mode + remixId + prompt」生成指纹
triggerFingerprint,同一组件实例的完全相同请求不会重复发起,避免响应式 UI 循环导致意外扣费(源码注释明确此为计费保护设计)。 - 初始化提供方:
provider.initialize(activeGlobals)被调用,NanoBananaProvider.initialize从配置中读取nanobananaApiKey(兼容config.apiKey字段)、nanobananaModel、nanobananaResolution,并记录日志[Nano Banana] Initialized. API Key present: ...(见 providers/nanobanana.ts)。 - 发起 HTTP 请求:
generate方法拼装 REST 请求并调用 Google Generative Language API 的generateContent端点:
const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${this.apiKey}`
// ...
body: JSON.stringify({
contents: [{ parts: generationParts }],
generationConfig: { imageConfig: { aspectRatio: '1:1', imageSize: resolution } },
})
model取自请求参数或初始化时的默认模型;resolution(1K/2K/4K)映射到imageConfig.imageSize;aspectRatio固定为1:1;- 若请求携带源图像(
request.extra.image或providerOptions.image,且已剥离base64,前缀),会以inline_data形式追加到 parts 中,支持图生图/编辑场景(providers/nanobanana.ts)。
- 结果解析与状态上报:从响应
candidates[0].content.parts中查找第一个带inlineData.data的图像部分,将其封装为data:${mimeType};base64,${data}的 data URL,并把任务状态更新为succeeded且progress: 100(providers/nanobanana.ts)。任务失败时状态置为failed并附带错误信息;任务完成后 10 秒会自动清理 callback 与结果缓存,防止内存泄漏(providers/nanobanana.ts)。 - 等待结果:
NanoBananaProvider实现了setJobCallback,bridge 走「callback-based wait」分支,在 5 分钟超时时间内等待succeeded/failed回调(artistry-bridge.ts)。
这套调用链意味着:只要 API Key 有效、模型可用,即使不通过聊天,任何内部组件(如 Character Card 的 Artistry 卡片)也能通过 headless 接口 artistryGenerateHeadless 复用同一生成管线(该 IPC 地址定义在 stage-shared/artistry.ts)。
常见故障排查
原文档给出的排查要点如下,结合源码可进一步定位:
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 认证失败(HTTP 401/403 类错误) | API Key 无效、过期或已被吊销 | 核对 Key 是否完整正确;必要时在 Google AI Studio 重新生成 |
| 图像生成失败 | Google AI Studio 账号/地区不支持所选模型、模型当前状态异常、配额耗尽 | 检查账号与地区可用性,查看模型当前状态,可先切换到 1K 分辨率降低配额消耗,或换用其他可用模型(如从 gemini-3-pro-image-preview 切到 gemini-2.5-flash-image) |
| 提示 "Nano Banana API Key not configured" | 提供方已选择但 API Key 为空 | 回到 Settings → Providers → Artistry → Nano Banana 填入 Key;generate 方法在 Key 缺失时会直接抛错(providers/nanobanana.ts) |
| 响应中没有图片数据 | API 返回异常或模型输出被过滤 | 错误信息 "No image data returned from Nano Banana" 会以 failed 状态回传(providers/nanobanana.ts),建议换提示词或换模型重试 |
排查时可留意主进程日志:NanoBananaProvider 使用 useLogg('providers-nanobanana') 输出 [Nano Banana] 前缀日志,bridge 侧则输出 [Artistry Bridge]、[Headless] 前缀日志,包含初始化是否成功、API Key 是否存在、作业状态轮询与失败原因,是定位问题的最直接线索。
小结
Nano Banana 为已持有 Google AI Studio API Key 的 AIRI 用户提供了一条零额外部署成本的图像生成路径。整个配置只需三步:获取 API Key → 在 Providers 页填入并选择模型/分辨率 → 在 Modules 页激活 Nano Banana (Preview)。其底层由 NanoBananaProvider 直连 Google Generative Language API 的 generateContent 端点,以 1:1 宽高比和所选分辨率(1K/2K/4K)生成图像,并通过统一的 ArtistryProvider 接口无缝接入 AIRI 的聊天工具调用与卡片生成管线。相关设置持久化于 artistry-nanobanana-* 存储键与 configs/artistry.ts 配置文件中,全部配置均可通过 Settings → Providers → Artistry → Nano Banana 界面完成,无需修改任何代码。