nanobanana-image-generation

Nanobanana 图像生成

概览

此技能现在支持两种模式：

• image 模式
  通过官方 generateContent 流程使用 Gemini 或 Nanobanana 进行生成和编辑
• plot 模式
  使用 Python 对数值数据进行精确渲染，生成出版风格的图表

机制图、图形摘要、设备示意图、风格匹配的重绘以及以图表为主的工作，请使用 image 模式。 需要保留数值准确性的精确柱状图、趋势曲线、热图、散点图和多面板图，请使用 plot 模式。

运行时策略：

• Python 是此技能所需的运行时，也是 image 和 plot 工作流的标准路径。
• scripts/generate_image.js 是可选的兼容性 CLI，适用于已使用 Node.js 的环境，并非注册表审核所需的运行时基线。

如果用户在 Codex 中用自然语言描述图表，不要要求他们手动编写 JSON 规范。Codex 应将请求转换为内部绘图请求或规范，并运行绘图脚本。

对于 image 模式，请遵循 Google 的官方示例，并替换：

• 将 API 密钥替换为提供商密钥
• 将基础 URL 替换为选定的兼容 Google 的 Gemini 端点

此技能请勿使用 OpenAI 风格的 /images/generations 或 /images/edits 路由。

仅作为附件提供的输入

如果图像仅作为聊天附件存在，且平台未提供本地文件路径，请勿声称脚本可以直接上传该图像。

请遵循以下规则：

1. 如果用户需要精确编辑原始上传像素，请先询问本地文件路径。
2. 如果用户接受近似重现，请目视分析附件图像，并生成一张尽可能保留原始构图和风格的新图像。

对于“将此附件图像中的英文替换为中文”之类的请求，如果无法精确保留像素，采用回退重现工作流是可以接受的。

快速开始

预检：

• plot 模式仅在本地运行，无需 API 凭据或出站网络访问。
• image 模式会将提示词文本、API 凭据以及任何 --input-image 文件发送到配置的兼容 Gemini 端点。
• 除非你有意信任其他提供商，否则请优先使用 Google 官方端点。
• 如果使用第三方端点，必须指定 --allow-third-party 或 NANOBANANA_ALLOW_THIRD_PARTY=1，并将此视为明确的信任决定。

设置环境变量：

export NANOBANANA_API_KEY="your-provider-key"
export NANOBANANA_BASE_URL="https://generativelanguage.googleapis.com"
export NANOBANANA_MODEL="gemini-3.1-flash-image-preview"

可选的第三方提供商：

export NANOBANANA_BASE_URL="https://api.zhizengzeng.com/google"
export NANOBANANA_ALLOW_THIRD_PARTY=1

如果不想让 API 密钥出现在命令行中，请将其存储在文件中并使用：

export NANOBANANA_API_KEY_FILE="$PWD/.secrets/nanobanana_api_key"

生成图像：

python3 scripts/generate_image.py "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"

编辑图像：

python3 scripts/generate_image.py "Using the provided image, change only the blue sofa to a vintage brown leather Chesterfield sofa. Keep everything else exactly the same." --input-image ./living-room.png

重现带有翻译后标签的附件示意图：

python3 scripts/generate_image.py "Recreate the attached pastel technical diagram with the same layout, icons, arrows, and hand-drawn style. Replace all visible English labels with natural Simplified Chinese. Keep the composition unchanged." --aspect-ratio 16:9 --image-size 2K

安全提示：

• scripts/build_materials_figure_prompt.py 和 --print-prompt 仅在本地运行，不会通过网络发送数据。
• 只有在针对已配置的提供商运行生成脚本时，实际提示词文本、API 密钥和用户提供的输入图像才会被发送。
• 使用非官方的兼容 Gemini 端点时，必须通过 --allow-third-party 或 NANOBANANA_ALLOW_THIRD_PARTY=1 明确确认。
• 如果不希望密钥出现在 shell 历史记录中，请优先使用 NANOBANANA_API_KEY_FILE，而不是内联指定 --api-key。

工作流

先选择一种模式：

1. 如果用户提供了数值数据，并且需要精确绘图，请使用 plot 模式。 阅读 references/publication-plot-api.md，并运行 scripts/plot_publication_figure.py。 对于自然语言请求，还要阅读 references/natural-language-plot-workflow.md。
2. 如果用户需要示意图、图形摘要或图像编辑工作流，请使用 image 模式。 按照下方 Gemini generateContent 流程操作。

对于 image 模式：

1. 保持官方 Gemini 请求结构。 使用 POST /v1beta/models/{model}:generateContent，并添加 X-goog-api-key。
2. 将提示词文本和图像输入放入 contents[].parts。 纯文本生成使用一个文本部分。图像编辑则追加一个或多个内联图像部分。
3. 将图像选项放入 generationConfig.imageConfig。 优先使用 --aspect-ratio 和 --image-size，与官方文档保持一致。
4. 对于材料科学图，优先先构建最终提示词。 如果想在发送任何 API 请求前检查或优化提示词，请使用 python3 scripts/build_materials_figure_prompt.py --materials-figure ...。
5. 对于出版风格的研究图，按需加载随附的设计指南。 阅读 references/publication-figure-design.md，了解统一风格、配色语义、排版和面板逻辑。
6. 如果图中包含类似图表的面板，请阅读 references/publication-chart-patterns.md。 使用其中的模式来指定分组柱状图、热图、趋势布局、专用图例和宽幅对比面板。
7. 从 candidates[0].content.parts[].inlineData 保存图像输出。 如果返回文本部分，也一并保存。
8. 如果源图像仅作为附件提供，请在精确编辑和重新绘制之间作出选择。 对于精确编辑，请索取本地路径。如果用户想要结果并接受视觉上匹配的重绘，请使用重新绘制。

对于 plot 模式：

1. 阅读 references/publication-plot-api.md。
2. 如果用户使用自然语言，请推断绘图意图和数据结构。 除非用户明确希望进行底层控制，否则不要要求用户编写内部规范。
3. 对于简洁的内部转换，可选创建请求 JSON，并使用 scripts/build_plot_spec.py 将其扩展。
4. 构建或生成一个顶层包含 style、layout 和 panels 的 JSON 规范。
5. 使用 bar、trend、heatmap、scatter、legend 或 empty 面板。
6. 使用以下命令渲染：

python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py spec.json

7. 导出精确的 PNG、PDF 或 SVG 输出。

环境

必需：

• NANOBANANA_API_KEY
• NANOBANANA_BASE_URL 必须显式设置。Google 官方端点：https://generativelanguage.googleapis.com

可选：

• NANOBANANA_MODEL 默认值：gemini-3.1-flash-image-preview
• NANOBANANA_TIMEOUT 默认值：120
• NANOBANANA_API_KEY_FILE 包含 API 密钥的文件路径。如果不希望密钥显示在命令历史记录或命令日志中，建议使用此项。
• NANOBANANA_ALLOW_THIRD_PARTY 仅当你有意将 API 密钥和用户提供的文件发送给非官方的 Gemini 兼容服务提供商时，才设为 1。

脚本

• scripts/generate_image.py 遵循官方 Gemini generateContent 请求格式的 Python CLI。
• scripts/generate_image.js 使用相同请求格式的 Node.js CLI。
• scripts/plot_publication_figure.py 根据 JSON 规格精确绘制出版风格图表的 Python CLI。
• scripts/build_plot_spec.py 将简洁的请求 JSON 扩展为完整绘图规格的 Python CLI。

通用选项：

• --input-image ./source.png
• --prompt-file ./background.md
• --aspect-ratio 16:9
• --image-size 2K
• --text-only
• --thinking-level high
• --include-thoughts
• --materials-figure mechanism-figure
• --lang zh
• --style-note "Nature Energy style"
• --print-prompt
• --allow-third-party
• --api-key-file ./.secrets/nanobanana_api_key

默认输出位置：

• 相对于当前 Codex 工作目录的 ./output/nanobanana/
• 仅当用户明确要求其他文件夹时才覆盖

确定性绘图：

python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py ./spec.json \
  --out-path ./output/plots/result \
  --formats png pdf svg \
  --dpi 300

便于使用自然语言的内部工作流：

python3 skills/nanobanana-image-generation/scripts/build_plot_spec.py ./request.json --out ./spec.json
python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py ./spec.json

官方映射

Google 官方示例：

• api_key="GEMINI_API_KEY"
• base_url="https://generativelanguage.googleapis.com"

第三方提供商替换项：

• api_key="your_provider_api_key"
• base_url="your_google_compatible_endpoint"
• allow_third_party=true

可选的知增增示例：

• api_key="your_zzz_api_key"
• base_url="https://api.zhizengzeng.com/google"
• allow_third_party=true

其他内容都应与 Gemini 官方文档保持一致。

提示词规则

• 生成图像时，描述场景，而不是罗列关键词。
• 编辑图像时，明确指出哪些内容必须保持不变。
• 对于多图工作流，说明每张参考图的用途。
• 图像保真度很重要时，优先使用英文或 zh-CN 提示词。
• 对于仅针对附件进行翻译的任务，请列出所有需要改写的标签，避免重新生成的图像遗漏文字。
• 如果布局保真度很重要，请明确要求保留图标位置、箭头、间距、层级和阅读顺序。
• 对于出版级图表，请说明颜色的语义用途、面板顺序、箭头逻辑，以及哪些元素应保持中性。
• 图表文字应简短。优先使用简洁的标签和图例条目，而不是嵌入图像的段落式注释。
• 如果图像类似图表，请说明它是概念图表、风格匹配的重绘，还是精确的定量复现。

材料科学插图快捷指南

如果用户需要材料科学论文插图、期刊风格科学示意图、图形摘要、机理图、合成流程图、微观结构-性能关系图、器件架构图或表征方案图，请使用随附的材料科学模板，而不是从头编写提示词。

工作流：

1. 阅读 references/materials-science-figure-template.md。
2. 选择最接近的子类型：
   • graphical-abstract
   • mechanism-figure
   • device-architecture
   • processing-workflow
3. 选择输出语言：
   • en
   • zh
4. 将用户提供的科学内容填入 Scientific Background 栏，或直接使用脚本快捷方式。
5. 遵循模板中有关因果关系、配色、排版和避免无依据断言的约束。
6. 如果用户未提供准确数值，请使用定性标签或明确使用占位符，不要编造数据。
7. 如果用户希望采用特定期刊风格，请将该偏好附加在模板之后，而不要改写模板。
8. 如果科学背景较长，请将其写入 Markdown 文件，并使用 --prompt-file 或 scripts/build_materials_figure_prompt.py --background-file ...，而不要将内容挤进一个 shell 参数。
9. 如需优化提示词，请参考：
   • references/materials-science-figure-template.md
   • references/publication-figure-design.md
   • references/publication-chart-patterns.md

研究插图设计整合

此技能包含一套从 figures4papers 项目改编而来的精简版期刊插图指南。使用它可以让 Nanobanana 输出更像期刊插图，而非普通 AI 艺术作品。

仅在需要时阅读参考文件：

• references/publication-figure-design.md 用于整体插图艺术指导：排版、配色语义、分面层级、白色背景规范、图例处理和适合印刷的简化设计。
• references/publication-chart-patterns.md 用于包含柱形图、趋势线、热图、对比矩阵或专用图例分面的插图。

编写提示词时应用以下规则：

• 保持整体构图简洁、对比鲜明，并以分面为主。
• 使用蓝色表示主要机理或所提方法，绿色表示改进，红色表示对比，使用中性灰表示支架/背景类别。
• 要求使用简短、专业的标签、无边框图例和整洁的白色背景。
• 保持各分面间的视觉编码一致，让同一种颜色始终表示同一相、状态或方法。
• 对于类似图表的插图，要求模型模仿期刊排版和风格，但除非插图是根据提供的源数据或参考图像重新绘制的，否则不要暗示其定量结果准确无误。

定量边界

此技能适用于：

• 图形摘要
• 机理图
• 器件示意图
• 加工流程图
• 类似图表的概念分面
• 按风格重绘现有论文插图

此技能不保证定量绘图精确。如果用户需要准确的柱形高度、热图数值，或根据原始数值忠实计算坐标轴刻度，除非明确要求根据可信的参考图像重绘，否则应将 Nanobanana 视为排版或视觉指导工具。

如需精确绘图，请切换到 plot 模式，并使用 references/publication-plot-api.md 和 scripts/plot_publication_figure.py。

Python 快捷方式：

python3 scripts/generate_image.py "paste the scientific background here" \
  --materials-figure mechanism-figure \
  --lang en \
  --style-note "Benchmark the figure against Nature Materials aesthetics." \
  --aspect-ratio 4:3 \
  --image-size 2K

JavaScript 快捷方式：

node scripts/generate_image.js "paste the scientific background here" \
  --materials-figure graphical-abstract \
  --lang zh \
  --aspect-ratio 4:3 \
  --image-size 2K

仅提示词预检：

python3 scripts/build_materials_figure_prompt.py \
  --materials-figure mechanism-figure \
  --lang en \
  --background-file ./background.md \
  --style-note "Nature Materials aesthetic with concise panel labels."

失败处理

• 如果 API 返回 401 或 403，请验证 NANOBANANA_API_KEY。
• 如果 CLI 提示缺少基础 URL，请设置 NANOBANANA_BASE_URL 或传入 --base-url。
• 如果 CLI 拒绝非官方端点，请添加 --allow-third-party，或仅在有意使用该提供方时设置 NANOBANANA_ALLOW_THIRD_PARTY=1。
• 如果 API 返回 404，请确认请求发送到了 /v1beta/models/{model}:generateContent。
• 如果提供方提示模型不存在，请在官方文档和该提供方支持的模型列表中核对准确的模型名称。
• 如果未返回图像，请检查 candidates[0].content.parts，并确认请求要求了图像输出。
• 如果用户只提供了聊天附件，没有提供文件路径，除非平台实际提供了附件字节数据，否则不要将结果描述为精确编辑。

参考资料

• 请阅读 references/api-reference.md，了解官方请求格式。
• 请阅读 references/prompt-templates.md，了解生成和编辑提示词模板。
• 生成材料科学论文插图时，请阅读 references/materials-science-figure-template.md。
• 请阅读 references/publication-figure-design.md，了解改编自 figures4papers 的出版风格研究插图规则。
• 请阅读 references/publication-chart-patterns.md，了解图表和多面板布局模式。
• 请阅读 references/publication-plot-api.md，了解如何根据数值数据进行精确绘图。
• 当用户用自然语言描述精确图表，且 Codex 需要将其转换为内部绘图请求时，请阅读 references/natural-language-plot-workflow.md。