企业官网建设流程全解析

banana-claude是一个面向 Claude Code 的AI 图像生成技能（AI image generation skill），由 Claude 担任"创意总监"，调用 Google Gemini Nano Banana 模型完成绘图。对新手而言，比"怎么画"更容易踩坑的其实是：提示词被安全过滤拦截了怎么办？为什么会收到 429 限流错误？免费层配额到底有多少？本文带你一次讲清 banana-claude 背后的双层安全过滤机制、429 限流的自动退避策略，以及免费层配额的真实额度与节省技巧。

图中"Generate"步骤之后就是安全过滤与限流检查发生的环节——每一张图生成都要经过 API 响应校验。

一、双层安全过滤架构：你的提示词和图片都会被检查

banana-claude 使用的 Gemini 图像生成采用双层安全过滤（two-layer safety architecture）设计，这一架构无法关闭，只能适配：

一个关键细节：输出过滤分析的是"生成的图"，而不仅是"提示词"。也就是说，即使你的 prompt 措辞很温和，只要模型"理解"出来的画面触发了过滤器，照样会被拦下。项目文档在 gemini-models.md 的 Safety Filters 一节明确标注了这一点。

另外，生成图像还自带身份凭证：

• SynthID 水印：所有生成图都嵌入不可见、机器可读的水印；
• C2PA 元数据：付费输出的图像附带可验证的来源链（provenance chain）。

二、finishReason 状态码速查表：被拦截时先看这里

每次 API 返回中都有finishReason字段，banana-claude 会依据它自动决定下一步。你可以直接对照下表理解报错含义：

⚠️已知特性：Gemini 的安全过滤器"过度谨慎"（overly cautious）——完全无害的提示词也可能被误拦。官方文档的建议就是"换个说法再试"（Iterate with rephrased wording）。

三、安全拦截后的改写策略：5 种改写套路 + 真实案例

banana-claude 的技能文件（SKILL.md 的 Error Handling 一节）规定：遇到IMAGE_SAFETY时，Claude不会自动重试，而是先分析触发点，给你 2-3 个改写方案，经你确认后再试（最多 3 次）。

改写套路沉淀在 prompt-engineering.md 的 "Safety Filter Rephrase Strategies" 章节，共 5 种：

1. 抽象化（Abstraction）——把具体敏感元素换成抽象概念
2. 艺术化包装（Artistic framing）——以艺术、杂志、纪录片形式呈现
3. 隐喻（Metaphor）——用象征性语言替代直白描述
4. 正向强调（Positive emphasis）——描述画面里"有什么"，而非"危险在哪"
5. 情境转移（Context shift）——从紧张语境转为教育/专业语境

被拦提示词 → 成功改写 真实对照表：

常见触发类别速查：

💡核心原则：当输出过滤拦截时，尝试把视觉概念整体移离触发点，而不仅仅是换同义词——因为过滤器看的是图，不是词。

四、429 限流：什么是 429，banana-claude 如何自动处理

什么是 HTTP 429？

429 Too Many Requests表示你请求太快了，超过了速率限制（Rate limit）。对免费层用户，这是最常见的报错，本质是"免费额度的油门"。

banana-claude 的自动退避策略

技能内置了完整的重试逻辑（见 SKILL.md Step 7 和 mcp-tools.md 的 Error Response Taxonomy）：

也就是说，限流基本不需要你手动干预——Claude 会自动等待并重试。你只需要知道：如果反复看到 429，说明你的节奏超过了免费层的 ~5-15 RPM，稍缓即可。

429 vs 400：别把限流当成账单问题

一个容易混淆的错误是 HTTP 400FAILED_PRECONDITION，它不是限流，而是"未启用计费"，处理方式完全不同：

五、免费层配额详解：RPM / RPD 到底是多少？

免费层真实额度

根据 gemini-models.md 的 "Rate Limits by Tier" 与 cost-tracking.md 的 "Free Tier Limits"：

📉重要提示：Google 在2025 年 12 月将免费层额度削减了约 92%（原为 ~10 RPM / ~500 RPD，见 CHANGELOG.md v1.2.0 的修正记录）。所以现在你看到的配额区间波动较大，这是正常现象，不是 banana-claude 的 bug。

各付费档位对比

六、免费层用户省配额 5 技巧 💡

1. 草稿用低分辨率：先用imageSize: "512"快速迭代构图，定稿再上2K——分辨率越高、token 消耗越多（每次生成约消耗 1,290 输出 tokens）。
2. 批量任务走 Batch API：异步批处理有5 折成本折扣，适合非紧急的批量生成（注意 Batch API 不占实时 RPM，但延迟更高）。
3. 切换 2.5 Flash 预算模型：gemini-2.5-flash-image是上一代模型，单张 1K 约 $0.039，比默认模型更省。项目通过set_model即可切换，适合预算敏感的高频工作流（见 mcp-tools.md）。
4. 用/banana cost提前估算：批量生成前先跑cost_tracker.py estimate预估花费，避免"画着画着把当天配额用光了"。
5. 利用午夜重置：把大批量任务安排在太平洋时间午夜（北京时间早上 8 点）之后执行，一天配额满血复活。

七、常见问题 FAQ ❓

Q1：我什么都没违规，为什么提示词总被拦？过滤器"过度谨慎"是已知问题。优先使用第三节的 5 种改写套路，把概念整体移离触发点，而不是只换同义词。

Q2：429 错误一直重试成功不了，怎么办？技能最多自动重试 3 次；仍失败说明你确实超了 ~5-15 RPM。等待 60 秒以上再试，或把大任务拆分到不同时段。

Q3：PROHIBITED_CONTENT和IMAGE_SAFETY有什么区别？前者是主题本身被禁（暴力、NSFW、真实公众人物等），改写也没用，只能换概念；后者通常改个措辞就能通过。

Q4：免费层额度会恢复吗？每日 RPD 在太平洋时间午夜自动重置；RPM 是滚动窗口，等一分钟即恢复。

Q5：生成的图有水印吗？会泄露身份吗？每张图都嵌入不可见的 SynthID 水印（机器可读，肉眼不可见），用于 AI 生成内容溯源；付费输出还带 C2PA 来源元数据。

小结

banana-claude 把"创意"交给 Claude，把"安全与配额"交给 Gemini 的体系化机制：

• 双层安全过滤：输入拦 prompt，输出拦成图，遇到IMAGE_SAFETY就按 5 种改写套路调整；
• 429 限流：自动指数退避重试（等 2 秒，最多 3 次），无需手动处理；
• 免费层配额：~5-15 RPM / ~20-500 RPD，太平洋时间午夜重置，善用 512 草稿、Batch API 折扣和 2.5 Flash 预算模型可以大幅省配额。

理解这些限制不是束缚，而是让你免费用得更快、更稳、更久的关键。