claude-seo 图像生成模型选型指南：Gemini 图像模型规格、API 配置与 SEO 资产生产实战

claude-seo 图像生成模型选型指南：Gemini 图像模型规格、API 配置与 SEO 资产生产实战

【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-seo

导读：本文基于 claude-seo 仓库的skills/seo-image-gen/references/gemini-models.md文档，系统梳理 Gemini 图像生成模型（Nano Banana 系列）的完整规格、API 参数、配额与定价，并结合仓库中 banana 扩展的源码实现（extensions/banana/scripts/）与 seo-image-gen 技能的调用管线，为在 Claude Code 中为 SEO 场景（OG 图、博客头图、产品图、信息图等）批量生产图片提供模型选型、参数调优与成本控制的实战方案。读完本文，你将掌握如何按分辨率档位、宽高比与用例正确调用 Gemini 图像 API，并能在 MCP 不可用时直接用官方 REST 接口完成生成与编辑。

一、模型全景：Nano Banana 两代对比

文档（gemini-models.md）明确划分了当前可用模型与已弃用模型。当前推荐与回退两个模型：

1.1 gemini-3.1-flash-image-preview（推荐）

这一模型同时是仓库各脚本的默认值。在 generate.py 中，DEFAULT_MODEL = "gemini-3.1-flash-image-preview"，cost_tracker.py 与 batch.py 的定价表也以该模型为核心，说明它是整个图像生成管线的默认主力。

1.2 gemini-2.5-flash-image（稳定回退）

注意该模型只支持 5 种宽高比且最高仅 1K，在 batch.py 的定价表中也只有 512 与 1K 两档，说明它是一个保守型备选，不适合高规格生产。

1.3 已弃用模型（不要使用）

需要特别强调的是，文档对gemini-3-pro-image-preview的表述是"使用风险自负"（Use at your own discretion viaset_model），它曾经是 Nano Banana Pro 档（专业资产生产、4K 输出、14 张参考图），但既然基础模型已弃用，任何新项目都不应再依赖它。

二、宽高比完整矩阵（14 种比例）

文档给出了全部 14 种受支持比例及其可用性差异，这是 SEO 资产选型的关键参照：

从源码结构看，这 14 种比例在 generate.py 中被硬编码为VALID_RATIOS集合并在入口校验，传入非法比例会直接报错退出。也就是说，无论通过 MCP 的set_aspect_ratio还是直接 REST 调用，可用比例集合都以此表为准。2.5 Flash 仅支持前 5 种比例，需要 Pinterest Pin（2:3）或站点横幅（4:1、8:1）时必须使用 3.1 Flash。

在 seo-image-gen 技能中，各 SEO 用例与比例已预映射（见 SKILL.md）：

• OG/Social 预览：16:9
• Schema Image：4:3
• Social Square：1:1
• Pinterest Pin：2:3
• 信息图：2:3

三、分辨率档位：imageSize 参数详解

文档强调一个容易踩坑的细节：分辨率档位必须使用大写 K（1K、2K、4K），小写1k不会生效。

关键说明：

• 实际像素尺寸取决于宽高比，例如 4K + 16:9 = 4096×2304；
• 分辨率越高消耗 token 越多、成本越高；
• 未指定imageSize时默认1K。

在 generate.py 中，VALID_RESOLUTIONS = {"512", "1K", "2K", "4K"}同样在入口做严格校验。仓库脚本中DEFAULT_RESOLUTION = "1K"（generate.py、batch.py），与文档默认值一致。

结合 seo-image-gen 的用例映射（SKILL.md）：

• OG 图 / Schema 图 / 方形社交图：1K
• 博客 Hero / 产品图：2K
• 信息图：4K
• Favicon/Icon：512

分辨率选择直接决定成本与质量：信息图这类数据密集、纵向排版的内容需要 4K 才能保证文字与图表的可读性，而 OG 图 1K 已足够。

四、API 配置：端点、参数与三种输出模式

4.1 端点

https://generativelanguage.googleapis.com/v1beta/models/{model-id}:generateContent

generate.py 中API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"，实际请求拼接为{API_BASE}/{model}:generateContent，与文档完全一致。

4.2 必填参数

{ "contents": [{"parts": [{"text": "your prompt here"}]}], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "1K" } } }

对照源码 generate.py，请求体结构完全对应：responseModalities默认["TEXT", "IMAGE"]，imageConfig中写入aspectRatio与imageSize。认证通过请求头X-Goog-Api-Key传递（generate.py）。

4.3 纯图像输出模式

强制模型只返回图片、不返回文本响应：

{ "generationConfig": { "responseModalities": ["IMAGE"] } }

generate.py 通过--image-only参数触发此模式：modalities = ["IMAGE"] if image_only else ["TEXT", "IMAGE"]（generate.py）。

4.4 Thinking 等级

控制模型在生成前的"思考"程度。等级越高，复杂构图效果越好，但延迟越高：

{ "generationConfig": { "thinkingConfig": { "thinkingLevel": "medium" } } }

可选等级：minimal、low、medium、high。generate.py 的--thinking参数将这四种等级作为 choices 校验（generate.py），并在存在时写入thinkingConfig。seo-image-gen 技能中，带文字的信息图建议thinking: high以提升文字渲染质量（见 SKILL.md 的模型路由表）。

4.5 Google Search Grounding

将生成过程锚定到真实世界的视觉参考，3.1 Flash 支持网页与图片搜索：

{ "tools": [{"googleSearch": {}}] }

提示词范式：[搜索/来源请求] + [分析任务] + [视觉转译]

示例："Search for the latest SpaceX Starship design, analyze its proportions and markings, then generate a photorealistic image of it at sunset on the launch pad."

这一范式在 prompt-engineering.md 中被拆解为三段式公式（[Source/Search request]→[Analytical task]→[Visual translation]），对依赖实时数据的 SEO 信息图（如"2026 年最热门编程语言统计图表"）尤为实用。

4.6 多图输入

最多可提供 14 张参考图：

• 10 张物体参考图：用于风格、构图或视觉匹配；
• 4 张角色参考图：为每个角色分配独立名字，以跨代保持特征。

适用于角色一致性、风格迁移与品牌一致性生成。在 MCP 环境下通过gemini_chat传入图片路径实现（见 mcp-tools.md 的特性可用性表）。

五、额度与定价：按档位选型的经济账

5.1 额度（Rate Limits）

免费档 10 RPM 意味着批量生成时需在请求间加延时，BANANA-SETUP.md 明确建议"For batch operations, add delays between requests"。

5.2 定价

注意两点：

• 定价基于每张约 1,290 输出 token 估算；
• 文档明确提示：有研究显示 NB2 实际定价可能约为 $0.067/张（高于官方文档的 $0.039），上线前务必到官方定价页核实当前价格（文档原文给出的验证地址为https://ai.google.dev/gemini-api/docs/pricing，仓库内相关定价表如 cost-tracking.md 也做了同样声明）。

仓库的 cost_tracker.py 与 batch.py 使用了同一套定价常量（512=$0.020、1K=$0.039、2K=$0.078、4K=$0.156），并且 cost_tracker.py 支持--batch标志应用 50% 折扣（BATCH_DISCOUNT = 0.5，cost_tracker.py）。这意味着仓库内所有成本预估均以文档定价表为唯一数据源，若真实价格有变动，需同步更新这两处常量。

5.3 成本追踪实操

seo-image-gen 技能要求每次生成前展示预估成本、生成后记录日志（SKILL.md）。对应命令：

# 记录一次生成 python3 extensions/banana/scripts/cost_tracker.py log --model gemini-3.1-flash-image-preview --resolution 1K --prompt "coffee shop hero" # 查看汇总（总量 + 最近 7 天） python3 extensions/banana/scripts/cost_tracker.py summary # 今日用量 python3 extensions/banana/scripts/cost_tracker.py today # 批量前预估（支持 --batch 看 5 折价） python3 extensions/banana/scripts/cost_tracker.py estimate --model gemini-3.1-flash-image-preview --resolution 2K --count 10 # 重置账本（需 --confirm） python3 extensions/banana/scripts/cost_tracker.py reset --confirm

账本存储在~/.banana/costs.json，首次使用时自动创建。每次log会记录时间戳、模型、分辨率、成本与提示词摘要（前 100 字符），并按 UTC 日期聚合到daily字段（cost_tracker.py）。

5.4 批量规划：CSV 驱动

batch.py 提供 CSV 批量规划：读取 CSV（必填prompt列，可选ratio、resolution、model、preset），输出结构化 JSON 计划并给出总成本预估。示例 CSV：

prompt,ratio,resolution "coffee shop hero image",16:9,2K "team photo placeholder",1:1,1K "product shot on marble",4:3,2K

python3 extensions/banana/scripts/batch.py --csv requests.csv

从源码看，batch.py 会按行累计estimate_cost()并输出estimated_cost字段，行内缺 prompt 会进入errors列表但仍继续处理有效行，方便 Claude 在执行前向用户确认总预算。

六、图像输出规格与安全机制

6.1 输出规格

输出均为 PNG（generate.py 保存为banana_{timestamp}.png，generate.py），因此 WebP 转换等后处理是 SEO 流程的必要环节（详见下文第七节）。

6.2 双层安全架构

Gemini 采用两层安全架构：

1. 输入过滤器：在生成前拦截含违禁内容的提示词；
2. 输出过滤器：分析生成的图片，拦截不安全结果。

finishReason含义与重试建议：

已知问题：过滤器以过度谨慎著称，良性提示也可能被拦截。遇到这种情况应不断改写措辞迭代。

源码层面，generate.py 在响应无图时会输出finishReason供排查，prompt-engineering.md 则给出了系统的改写策略（抽象化、艺术化框定、隐喻、正向强调、语境转移）以及常见触发类别表（暴力/武器、医疗血腥、真实公众人物、儿童风险场景、NSFW/暗示性内容）和逐条改写示例。

6.3 内容凭证（Content Credentials）

• SynthID 水印：始终内嵌于生成图片（不可见、机器可读）；
• C2PA 元数据：Pro/付费输出中包含（可验证的来源链）。

这保证了 AI 生成内容的可溯源性与真实性，对重视内容诚信（content integrity）的站点尤其重要。

七、从生成到上线：SEO 资产后处理流水线

7.1 关键局限（决定后处理方案）

• 不支持视频生成（仅图像）；
• 不支持透明背景（虽为 PNG 但总有背景）；
• 文字渲染质量不稳，最佳效果需将文字控制在 25 字符以内；
• 安全过滤器可能拦截部分提示（暴力、NSFW、公众人物），且以过度谨慎著称；
• Claude Code 会话之间的上下文会重置；
• imageSize与 thinking 等级取决于 MCP 包版本支持。

"无透明背景"这一点直接催生了 post-processing.md 中的绿幕（chroma key）流水线：先以提示词要求"solid bright green (#00FF00) chroma key background with a thin white outline"，再用 ImageMagick/FFmpeg 抠除并清理边缘：

# 生成阶段提示词追加 on a solid bright green (#00FF00) chroma key background with a thin white outline separating the subject from the background # 抠绿幕 magick input.png -fuzz 20% -transparent "#00FF00" output.png # 清理边缘 + 裁剪 magick output.png -channel A -blur 0x1 -level 50%,100% -trim +repage final.png # FFmpeg 批量方案（自带 despill） ffmpeg -i input.png -vf "colorkey=0x00FF00:0.3:0.1,despill=type=green" -pix_fmt rgba output.png

7.2 seo-image-gen 的生成后检查清单

SKILL.md 定义了每次成功生成后必须指导用户完成的 6 步 SEO 清单：

1. Alt 文本：为生成的图片编写描述性、含关键词的 alt 文本；
2. 文件命名：改为 SEO 友好格式keyword-description-widthxheight.webp；
3. WebP 转换：

magick output.png -quality 85 output.webp

4. 文件大小：Hero 图控制在 200KB 以内、缩略图 100KB 以内；
5. Schema 标记：为生成图片建议ImageObjectschema：

{ "@type": "ImageObject", "url": "https://example.com/images/keyword-description.webp", "width": 1200, "height": 630, "caption": "Descriptive caption with target keyword" }

6. OG meta 标签（社交预览图）：

<meta property="og:image" content="https://example.com/images/og-image.webp" /> <meta property="og:image:width" content="1200" /> <meta property="og:image:height" content="630" /> <meta property="og:image:alt" content="Descriptive alt text" />

后处理工具箱（post-processing.md）还包含按平台裁剪（Instagram 1080×1080、YouTube 缩略图 1280×720、LinkedIn 横幅 1584×396 等）、水印叠加、批量转 WebP/AVIF、对比图拼接等 ImageMagick/FFmpeg 配方。文档特别提示：既然 3.1 Flash 支持原生 4K 输出，优先直接生成 4K 而非 1K 后放大，可避免放大伪影。

八、模型路由与错误处理：生产环境的实践决策

8.1 按场景路由（seo-image-gen 技能内置）

8.2 常见错误处理

8.3 MCP 不可用时的直接 API 回退

generate.py 与 edit.py 是纯 Python 标准库实现的 REST 回退通道，无需任何 pip 依赖：

# 生成（环境变量提供 key，或 --api-key 显式传入） GOOGLE_AI_API_KEY=xxx python3 extensions/banana/scripts/generate.py \ --prompt "a cat in space" --aspect-ratio "16:9" --resolution "1K" \ --model gemini-3.1-flash-image-preview --thinking medium --image-only # 编辑（输入图片 + 编辑指令） GOOGLE_AI_API_KEY=xxx python3 extensions/banana/scripts/edit.py \ --image path/to/photo.png --prompt "remove the background"

值得注意的安全细节：这两个脚本都内置了 Google API key 脱敏逻辑（_redact_google_api_key，generate.py），会在错误输出中把 key 替换为GOOGLE_API_KEY_REDACTED，防止凭据泄露到日志；仓库也为此编写了专门的测试（test_banana_api_key_safety.py、test_google_api_key_safety.py）。生成的图片默认保存到~/Documents/nanobanana_generated/。

8.4 MCP 工具面（nanobanana-mcp）

当 MCP 正常可用时，Claude Code 通过 mcp-tools.md 记录的以下工具驱动生成：

环境变量方面，GOOGLE_AI_API_KEY必填，NANOBANANA_MODEL可选用于覆盖默认模型。文档还提示：imageSize、thinking 等级、search grounding、纯图像输出、多图输入等新特性是否可用，取决于@ycse/nanobanana-mcp的包版本；若 MCP 不支持，可改用直接 REST 调用（如上述回退脚本）绕过。

九、与 claude-seo 生态的协作

图像生成在 claude-seo 中并非孤立模块，SKILL.md 明确其跨技能协作关系：

• seo-images（分析）→ seo-image-gen（生成）：/seo images审计识别缺失或低质图片，结果驱动/seo image-gen生成命令；
• seo-audit → seo-image-gen agent：站点级审计会派生出分析师 agent 评估全站 OG/社交图并产出优先级生成计划（该 agent 只分析、不自动生成）；
• seo-schema → 生成图片：生成后建议指向新资产的ImageObjectschema 标记。

因此本文的模型选型决策直接影响整条 SEO 图片工作流：OG 图用 16:9@1K 快速迭代，Hero 与产品图用 2K 保证质感，数据密集型信息图用 2:3@4K + high thinking 保证可读性，而这一切的规格依据都来自 gemini-models.md 这张模型规格总表。

最后提醒一句成本纪律：图像生成是付费能力。文档与仓库脚本一致建议——批量前先estimate，生成后立即log，用~/.banana/costs.json账本持续核对实际消耗；且由于官方定价可能调整，涉及预算的正式项目应在生产前重新核实官方定价页的当前价格。

【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-seo