Gemini 2.5 Flash Image 在社区里更常被叫作「Nano Banana」是 Google 推出的多模态生图模型文本生图、图片编辑、多图融合都能做。网上大部分教程停在通用的 API 调用很少讲清楚在具体开发环境里怎么落地。这篇文章换个视角以Code0 集成 Nano Banana为主线把选型、认证、调用一直到生产环境的错误处理走一遍帮你在真实项目里把 AI 生图 API 跑通。版本说明本文统一以稳定版模型 IDgemini-2.5-flash-image为准预览版gemini-2.5-flash-image-preview已不建议再用。文中涉及的价格、限额等信息官方随时可能调整请以 Google 最新文档为准。一、选型要不要用 Nano Banana写第一行代码之前先想清楚它值不值得用。下面把几种主流生图方案做个定性对比帮你有个初步判断。维度Gemini 2.5 Flash ImageDALL·E 3 APIMidjourney API核心优势生图编辑一体、多模态输入、响应较快提示词理解强、集成生态成熟美学质量高、风格化强图片编辑原生支持局部编辑/替换支持有限官方 API 支持有限多图融合支持不支持部分支持集成难度中等REST/SDK 均可低较高多依赖第三方封装适用场景判断如果你的应用需要「生成完还要反复改」的闭环比如电商产品图、内容创作辅助那 Nano Banana 在图片编辑和多图一致性上的优势会很明显。如果只想要单张美学拉满的插画可以再多看看其他方案。具体价格和速率限制建议直接查官方计费页面这里不给未核实的数字。二、5 分钟在 Code0 里生成第一张图2.1 获取 API Key先去 Google AI Studio 建一个 API Key。建议不同项目各自建独立 Key后面做权限隔离、追踪用量会方便很多。2.2 Code0 项目初始化在 Code0 里新建项目以 Node.js 为例打开内置终端执行npm init -y npm install google/genai dotenv在项目根目录建.env文件一定要加进.gitignoreGEMINI_API_KEY你的密钥2.3 最小可用示例import { GoogleGenAI } from google/genai; import * as fs from node:fs; import dotenv/config; const ai new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); async function generate() { const resp await ai.models.generateContent({ model: gemini-2.5-flash-image, contents: 一只戴宇航头盔的柴犬卡通风格纯色背景, }); for (const part of resp.candidates[0].content.parts) { if (part.inlineData) { const buffer Buffer.from(part.inlineData.data, base64); fs.writeFileSync(output.png, buffer); } } } generate();在 Code0 终端执行node index.js成功后项目目录里会生成一张output.png。2.4 第一次调用常见报错401/403多半是 Key 无效或对应 API 没启用先确认.env是否正确加载。网络超时国内环境常见问题解决办法见第八节「网络适配」。返回内容里没有图片要么请求被内容策略拦截要么提示词太抽象换个更具体的描述再试。三、Code0 环境配置与认证安全Code0 提供了环境变量和工作区配置能力认证这块做规范一点能省掉很多线上事故。密钥管理一律走环境变量注入不要硬编码。生产环境优先用 Code0 的加密环境变量别用明文.env。多环境隔离开发、测试、生产各准备一套 Key在配置里靠NODE_ENV切换避免测试流量吃掉生产额度。快速验证Code0 内置终端里直接用curl测接口通不通不用切外部工具curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent?key$GEMINI_API_KEY \ -H Content-Type: application/json \ -d {contents:[{parts:[{text:a cat}]}]}四、三种核心调用方式4.1 文本生图Text-to-Image就是第二节那个例子。提示词技巧Nano Banana 对结构化描述反应更好建议按「主体 风格 构图 背景 光照」的顺序组织。中文提示词整体能用但涉及专业美术术语时中英混写往往更稳比如「赛博朋克 cyberpunk 霓虹光」。4.2 图片编辑Image-to-Image把原图 Base64 编码传进去配上文本指令就能实现局部替换、风格转换const imageData fs.readFileSync(input.png).toString(base64); const resp await ai.models.generateContent({ model: gemini-2.5-flash-image, contents: [ { inlineData: { mimeType: image/png, data: imageData } }, { text: 把背景替换成雪山保持主体人物不变 }, ], });关键点编辑指令一定要说清楚「保持什么不变」否则模型很可能把整张图重画一遍一致性就毁了。4.3 多图融合与角色一致性传多张图进去可以做融合或跨图保持角色一致。做法是在contents数组里放多个inlineData然后在文本里交代清楚每张图各自的角色比如「用图一的人物配图二的服装风格来生成」。角色一致性是 Nano Banana 相比其他方案拉开差距的地方做系列内容时尤其值得利用。五、生产级代码把 happy path 变成可靠系统大多数教程给一段「能跑通」的代码就结束了可到了生产环境错误处理、重试、成本一个都躲不掉。下面是一个更完整的封装。async function generateWithRetry(prompt, maxRetries 3) { for (let attempt 0; attempt maxRetries; attempt) { try { const resp await ai.models.generateContent({ model: gemini-2.5-flash-image, contents: prompt, }); return extractImage(resp); } catch (err) { const status err?.status; // 401/403 属于配置问题重试无意义直接抛出 if (status 401 || status 403) { console.error(认证失败请检查 API Key, err); throw err; } // 429/500/503 可重试采用指数退避 if ([429, 500, 503].includes(status) attempt maxRetries) { const delay Math.min(1000 * 2 ** attempt, 8000); console.warn(第 ${attempt 1} 次失败(${status})${delay}ms 后重试); await new Promise((r) setTimeout(r, delay)); continue; } throw err; } } }错误分类原则401/403认证/权限配置问题别重试直接告警。429速率限制退避后重试同时在应用层加请求队列控制并发。500/503服务端一般是短暂故障指数退避重试。内容被拒属于业务错误应把被拒的提示词记下来方便优化而不是反复重试。速率限制和成本Gemini API 按 RPM/TPM 限流高并发场景建议引入队列比如p-queue压住并发数。图片生成按 token 计费建议每次调用完累计 token 用量设个日预算阈值超了就熔断。日志和监控用结构化日志把每次请求的耗时、状态、token 消耗都记下来方便在 Code0 里回溯问题、做成本分析。六、Code0 中的调试与测试Mock 离线测试调试逻辑时不想烧真实额度可用本地 mock 返回一张固定的 Base64 图片专门验证解析和落盘逻辑。断点调试Code0 支持在 Node.js 代码上打断点逐步查resp.candidates的结构「怎么没拿到图片」这类问题很快能定位。单元测试用 Jest 单独测错误处理通过 mock 抛出不同status看重试和退避行为是否符合预期全程不用真调 API。七、常见失败原因与排查清单现象可能原因排查方向返回无图片提示词被内容策略拦截检查是否含敏感、暴力、名人肖像等描述反复超时国内网络不稳定配置代理见第八节429 频繁并发过高引入队列限流图片错乱编辑时未约束「保持不变」补充锚定描述Base64 解码失败mimeType 与实际格式不符核对 PNG/JPEG 对应类型关于输出格式默认返回 Base64 内联数据落盘还是上传到对象存储看自己处理。前端展示可以直接拼data:image/png;base64,前缀或转存成 URL 再引用——后者更利于缓存和 CDN 分发。八、中文开发者专属建议提示词本地化纯中文提示词能用但碰到抽象概念比如某个特定艺术流派建议附上英文关键词命中率会明显高一些。另外别堆一堆互相打架的形容词。国内网络适配generativelanguage.googleapis.com在部分网络环境下访问不稳可以在 Code0 里通过环境变量配一个 HTTPS 代理同时把超时时间和重试次数适当调大。合规生成内容需遵守内容政策涉及人物肖像、品牌标识要格外小心用户上传图片做编辑时隐私和数据留存的合规问题也别忘。九、进阶多模型协作与工作流实际做产品时生图往往只是整条链路里的一环。很多时候你得先用语言模型把用户粗糙的需求「扩写」成像样的提示词再交给 Nano Banana 生成。这类文本编排完全可以在 Code0 里同时接入其他大模型 API 来完成。如果你打算用第三方兼容接入服务来做文本侧的编排可以在其平台模型列表里挑当前可见的模型比如日常那种要均衡效果的提示词优化可以用claude-sonnet-5如果对成本敏感、做轻量批处理那claude-haiku-4-5-20251001比较合适。需要说明的是这类平台是第三方兼容接入服务并非模型官方具体哪些模型可用、稳定性如何、怎么计费都以其官网最新说明为准。「文本编排 图像生成」的分工模式能让整条生图流水线在可控性和最终效果上都上一个台阶。十、小结这篇文章以 Code0 集成为主线把 Gemini 2.5 Flash Image 的选型、认证、三种调用方式、生产级错误处理一直到调试测试和中文适配串了一遍。跟只讲「怎么调通」的教程相比工程化真正的重点在于把那些不可控的外部依赖包进一个可重试、可监控、成本可控的可靠系统里。落地顺序建议这么走先拿最小示例跑通再补齐错误处理和重试然后加上日志和成本监控最后按业务场景优化提示词和并发策略。把这一整套流程沉淀成项目模板下次接新场景就能直接复用。