banana-claude AI绘图免费入门教程:Gemini API Key申请与MCP配置避坑指南
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 是什么?为什么值得装
它不是简单的 API 包装器。你只需说一句"给我的咖啡店网站做一张头图",Claude 会完整走一遍创意总监流水线:
- 意图分析——判断你要的是博客头图、App 图标还是产品照
- 领域模式选择——Cinema、Product、Portrait、Logo 等 9 大专业视角
- 5 组件提示词公式——主体 → 动作 → 场景 → 构图 → 风格(含灯光),把口语化的想法改写成专业级提示词
- 比例与分辨率选择——14 种宽高比,最高 4K
- 调用 Gemini 生成 + 自动后期
九大领域模式覆盖了绝大多数创作场景:电影感大片、电商产品图、人像、时尚编辑、UI 插画、Logo、风景壁纸、信息图和抽象纹理。
核心差异在于"会思考":Claude 不会把你的原话直接丢给模型,而是用官方推荐的 5 组件公式重构提示词(具体规则见 prompt-engineering.md)。
二、安装前准备: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
- 用 Google 账号登录 Google AI Studio 官网
- 打开 API Key 页面,点击创建即可拿到 Key(无需信用卡)
- 妥善保存,下一步 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 |
查看用量与费用统计 |
八、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 里挑个灵感,开始你的第一次创作吧 🍌




