banana-claude AI绘图免费入门教程:Gemini API Key申请与MCP配置避坑指南

原创2026-10-14 23:57:441,915 阅读

banana-claude AI绘图免费入门教程:Gemini API Key申请与MCP配置避坑指南

banana-claude 是一款面向 Claude Code 的 AI 绘图技能(AI image generation skill),让 Claude 担任"创意总监",调度 Google Gemini(Nano Banana)模型完成图片生成与编辑。本文带你零成本完成 Gemini API Key 申请与 MCP 配置,并一次性避开新手最常踩的 8 个坑,几分钟即可画出第一张图 🎨

banana-claude AI绘图技能项目封面

一、banana-claude 是什么?为什么值得装

它不是简单的 API 包装器。你只需说一句"给我的咖啡店网站做一张头图",Claude 会完整走一遍创意总监流水线:

  1. 意图分析——判断你要的是博客头图、App 图标还是产品照
  2. 领域模式选择——Cinema、Product、Portrait、Logo 等 9 大专业视角
  3. 5 组件提示词公式——主体 → 动作 → 场景 → 构图 → 风格(含灯光),把口语化的想法改写成专业级提示词
  4. 比例与分辨率选择——14 种宽高比,最高 4K
  5. 调用 Gemini 生成 + 自动后期

banana-claude AI绘图创意总监流水线流程图

九大领域模式覆盖了绝大多数创作场景:电影感大片、电商产品图、人像、时尚编辑、UI 插画、Logo、风景壁纸、信息图和抽象纹理。

banana-claude AI绘图九大领域模式展示

核心差异在于"会思考":Claude 不会把你的原话直接丢给模型,而是用官方推荐的 5 组件公式重构提示词(具体规则见 prompt-engineering.md)。

banana-claude AI绘图5组件提示词公式图解

二、安装前准备:3 项环境要求

依赖 版本要求 说明
Claude Code 最新版 运行 /banana 命令的宿主
Node.js 18+ MCP 依赖 npx,低于 18 会静默失败
Google AI API Key 免费即可 免费额度约 5–15 RPM / 20–500 RPD
ImageMagick 可选 仅抠图、裁剪等后期功能需要

三、安装 banana-claude:两种方法任选

方法 1:插件市场安装(推荐)

在 Claude Code 中直接执行:

/plugin marketplace add AgriciDaniel/banana-claude
/plugin install banana-claude@banana-claude-marketplace

方法 2:脚本独立安装

git clone --depth 1 https://gitcode.com/gh_mirrors/ba/banana-claude
bash banana-claude/install.sh

想一步到位配置 MCP,可以把 API Key 直接传给安装脚本(详见 install.sh):

cd banana-claude
./install.sh --with-mcp YOUR_API_KEY

安装完成后,技能会位于 ~/.claude/skills/banana/,并自动创建 ~/.banana/ 目录用于成本记录和风格预设。

四、申请免费的 Gemini API Key

  1. 用 Google 账号登录 Google AI Studio 官网
  2. 打开 API Key 页面,点击创建即可拿到 Key(无需信用卡)
  3. 妥善保存,下一步 MCP 配置会用到 🔑

⚠️ 免费额度注意:每项目约 5–15 次/分钟、20–500 次/天(太平洋时间午夜重置)。对新手来说完全够用,但批量出图时请留意限流。模型与额度的完整规格见 gemini-models.md。

五、MCP 配置:最快一步到位

banana-claude 通过 MCP 包 @ycse/nanobanana-mcp 调用 Gemini。配置有两种方式:

方式 A:交互式(推荐)——启动 Claude Code 后直接输入:

/banana setup

方式 B:命令行——运行配置脚本(支持 --key 非交互传入、--check 检查、--remove 卸载):

python3 skills/banana/scripts/setup_mcp.py --key YOUR_API_KEY

脚本 setup_mcp.py 会自动向 ~/.claude/settings.json 写入如下结构:

  • command: npx,参数 -y @ycse/nanobanana-mcp
  • 环境变量 GOOGLE_AI_API_KEY(必填)与 NANOBANANA_MODEL(默认 gemini-3.1-flash-image-preview)

配置完成后必须重启 Claude Code 才生效。生成的图片统一保存在 ~/Documents/nanobanana_generated/,按时间戳命名。工具参数细节可查 mcp-tools.md。

六、验证安装:一键体检

python3 skills/banana/scripts/validate_setup.py

validate_setup.py 会依次检查 9 项:settings.json 是否存在、MCP 条目是否写入、npx 是否在 PATH 中、GOOGLE_AI_API_KEY 是否设置、模型是否配置、输出目录是否可写。全部显示 PASS 即为 Ready ✅

七、快速上手:发出第一条 /banana 命令

重启后输入 /banana generate "a hero image for a coffee shop website",Claude 会先询问品牌细节,再按流水线生成。常用命令一览(完整说明见 SKILL.md):

命令 作用
/banana generate <想法> 完整创意总监流水线生成
/banana edit <路径> <指令> 智能修图(如去背景)
/banana chat 多轮创作,保持角色/风格一致
/banana batch <想法> [N] 批量生成 N 个变体(默认 3)
/banana inspire [分类] 浏览 2,500+ 提示词灵感库
/banana cost 查看用量与费用统计

banana-claude AI绘图命令/banana generate实际运行效果演示

八、MCP 配置避坑指南:8 个高频问题

坑 1:Key 无效或为空。 报错 API key invalid 时,去官网重新创建一个 Key 再跑一遍 /banana setup。注意粘贴时不要带多余空格。

坑 2:HTTP 429 限流。 免费额度仅 5–15 RPM,连续发图极易触发。正确姿势:等待 60 秒,用指数退避重试;批量任务优先错峰。

坑 3:HTTP 400 FAILED_PRECONDITION。 这是"未启用账单"的专属错误,说明你当前项目走的是付费层。免费用户检查 Key 是否选对了免费层项目,不要盲目重试(banana-claude 遇到此错误会直接提示而非自动重试)。

坑 4:imageSize 必须大写。 "2k" 会被静默忽略(不报错但降级为默认值),只有 512/1K/2K/4K 才有效。

坑 5:旧模型 ID 已下线。 gemini-3-pro-image-preview 已于 2026 年 3 月被 Google 关停,调用直接报错。旧教程里的引用一律换成 gemini-3.1-flash-image-preview。

坑 6:配置后忘了重启 Claude Code。 MCP 配置在启动时加载,不重启等于没配——这是新手最高频的"假故障"。

坑 7:npx 找不到。 MCP 依赖 npx -y 拉取包,先确认 node -v ≥ 18;Linux 用户可运行 sudo apt install imagemagick 顺带补齐后期工具。

坑 8:IMAGE_SAFETY 内容拦截。 Gemini 的安全过滤偏保守,正常的提示词也可能被拦。解法不是换词硬试,而是改用抽象化、艺术化表达重写场景;PROHIBITED_CONTENT(暴力、真人公众人物等)则无法绕过,直接换概念即可。

九、免费额度与成本速览

模型 分辨率 单张价格(付费)
Nano Banana 2(gemini-3.1-flash-image-preview,默认) 1K / 2K / 4K ~$0.067 / $0.134 / $0.268
Nano Banana(gemini-2.5-flash-image,稳定后备) 1K ~$0.039

免费额度内出图零费用;超出后每次生成都会被 cost_tracker.py 自动记账,随时用 /banana cost summary 查看总账。

十、常见问题 FAQ

Q:图片生成后去哪儿找? A:~/Documents/nanobanana_generated/,每次回复也会给出具体文件路径。

Q:/banana 命令没有反应? A:按顺序检查——技能是否安装(ls ~/.claude/skills/banana/)→ MCP 是否配置(/banana setup)→ 是否重启过 Claude Code。

Q:能一次出 4 张图吗? A:Gemini 每次 API 调用只出 1 张图,不存在批量参数;需要变体请用 /banana batch,由技能自动轮换提示词组件生成 N 张。

写在最后

回到核心:申请一个免费 Gemini API Key → /banana setup 写入 MCP → 重启 → /banana generate 出图,四步即可跑通 banana-claude 的完整 AI 绘图工作流。把上面的 8 个坑过一遍,基本不会再被配置问题卡住。接下来,去 /banana inspire 里挑个灵感,开始你的第一次创作吧 🍌

登录后查看全文
banana-claude