Nano Banana Pro China - 模板生成与图片编辑

Overview

使用 Nano Banana Pro (Gemini 3 Pro Image) 通过 Cloudflare Gateway + OpenRouter API 生成和编辑图片。

核心功能：

模板生成: 使用预定义模板生成统一风格的团队图片
图片编辑: 自由编辑现有图片（修改文本、删除元素、合并图片）

重要优势：

✅ 通过 Cloudflare Gateway 解决国内访问 OpenRouter 的网络问题
✅ 双重认证机制，安全可靠
✅ 支持 1K/2K/4K 多分辨率
✅ 中文友好的输出格式

When to Use

模板生成 - 使用场景

用户请求带"模板"关键词的图片生成
团队需要统一的视觉风格
需要固定标题和插图位置
用户提到"春节海报"、"产品宣传"等模板名称

图片编辑 - 使用场景

用户请求修改现有图片
用户提供图片 + 编辑指令
用户提到"编辑"、"修改"、"更改"关键词
多张图片需要合并
图片上的文字需要修改

Configuration

Cloudflare Gateway 配置（必需）

国内访问 OpenRouter API 必须使用 Cloudflare Gateway。

配置文件 .env：

OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key
OPENROUTER_BASE_URL=https://gateway.ai.cloudflare.com/v1/cdc42e16b43498c2f7acdf3fb6b99fea/openrouter-gateway/openrouter/v1/chat/completions
CF_AIG_TOKEN=cfut_your-cloudflare-gateway-token

双重认证机制：

# 请求时需要两个认证 headers
-H 'cf-aig-authorization: Bearer CF_AIG_TOKEN'     # Gateway 认证
-H 'Authorization: Bearer OPENROUTER_API_KEY'      # OpenRouter 认证

Template Workflow

digraph template_workflow {
    rankdir=TB;
    start [label="User request", shape=ellipse];
    check_template [label="Template specified?", shape=diamond];
    list_templates [label="List templates\nfrom templates/", shape=box];
    user_select [label="User selects\ntemplate name", shape=box];
    load_template [label="Load template\nconfig + base image", shape=box];
    confirm [label="Confirm title\n& illustration", shape=box];
    generate [label="API call\nGemini 3 Pro Image", shape=box];
    download [label="Download\nto materials/raw/", shape=box];
    output [label="Show result\n(Chinese format)", shape=box];

    start -> check_template;
    check_template -> load_template [label="yes"];
    check_template -> list_templates [label="no"];
    list_templates -> user_select;
    user_select -> load_template;
    load_template -> confirm;
    confirm -> generate;
    generate -> download;
    download -> output;
}

Image Editing Workflow

digraph edit_workflow {
    rankdir=TB;
    start [label="User request\n(images + instruction)", shape=ellipse];
    check_images [label="Images count?", shape=diamond];
    single [label="Single image\nmode", shape=box];
    multi [label="Multi-image\nmode", shape=box];
    parse_instruction [label="Parse editing\ninstruction", shape=box];
    api_call [label="API call\nGemini 3 Pro Image", shape=box];
    download [label="Download\nto materials/raw_edit/", shape=box];
    output [label="Show result\n(Chinese format)", shape=box];

    start -> check_images;
    check_images -> single [label="1 image"];
    check_images -> multi [label="2+ images"];
    single -> parse_instruction;
    multi -> parse_instruction;
    parse_instruction -> api_call;
    api_call -> download;
    download -> output;
}

Template Structure

Templates 存储在 templates/ 目录，每个模板有独立的子目录：

templates/
├── spring-festival/
│   ├── template.json       # 模板配置
│   └── base.png           # 基础图片（团队准备的现成图片）
├── product-promotion/
│   ├── template.json
│   └── base.png
└── corporate-culture/
    ├── template.json
    └── base.png

template.json 格式：

{
  "name": "春节海报",
  "description": "春节主题海报模板",
  "base_image": "base.png",
  "title_position": "顶部居中",
  "illustration_position": "中央区域",
  "font_style": "大标题，红色，喜庆字体",
  "dimensions": {
    "width": 2048,
    "height": 2048
  }
}

关键理解：Base images 是团队准备的现成图片，不是 AI 生成的！

Agent Workflow Steps

模板生成流程

检查用户请求: 是否提到模板名称？
如果未指定模板: 运行 python3 scripts/list_templates.py → 显示可用模板 → 请用户选择
如果指定模板: 运行 python3 scripts/verify_template.py --template NAME → 检查 base image 是否存在
如果 base image 缺失: 提示用户"团队必须先准备 base image（现成图片）"
收集参数: 获取 --title 和 --illustration 内容
生成: 运行 python3 scripts/generate_with_template.py
监控响应: 检查状态码，提取图片 URL
下载: 图片自动保存到 ./materials/raw/
显示结果: 使用中文友好的输出格式

图片编辑流程

检测编辑请求: 用户提供图片 + 编辑指令
收集参数:
- --images: 图片路径（多张图片用逗号分隔）
- --instruction: 编辑指令文本
运行编辑脚本: python3 scripts/edit_image.py --images img.png --instruction "修改文字"
监控响应: 检查状态码，提取图片 URL
下载: 图片自动保存到 ./materials/raw_edit/
显示结果: 使用中文友好的输出格式

Script Usage

模板生成

列出可用模板：

python3 scripts/list_templates.py

验证模板配置：

python3 scripts/verify_template.py --template "春节海报"

使用模板生成图片：

python3 scripts/generate_with_template.py \
  --template "春节海报" \
  --title "2026新春快乐" \
  --illustration "一家人团聚吃年夜饭，红灯笼，烟花" \
  --resolution 2K

图片编辑

单图编辑：

python3 scripts/edit_image.py \
  --images test_img/img.png \
  --instruction "把第一段正文标题更改为：如何寻找诱因？其他保持不变" \
  --resolution 1K

多图合并：

python3 scripts/edit_image.py \
  --images car.png,paint.png \
  --instruction "把图2的涂鸦喷绘在图1的汽车上" \
  --resolution 2K

Output Format

模板生成输出示例：

🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉
图片生成成功！

============================================================
📸 图片信息
============================================================
图片 URL: https://gateway-result.com/xxx.png
⚠️  有效期: 30 天，请及时下载保存
本地路径: ./materials/raw/abc123.png
文件大小: 2.5 MB

============================================================
📋 生成参数
============================================================
使用模板: 春节海报
标题内容: 2026新春快乐
插图描述: 一家人团聚吃年夜饭，红灯笼，烟花
图片尺寸: 2048x2048 (2K)
使用模型: google/gemini-3-pro-image-preview
认证方式: Cloudflare Gateway + OpenRouter

============================================================
💡 下一步操作
============================================================
1. 查看图片：open ./materials/raw/abc123.png
2. 发送到钉钉/飞书？（使用 AI 工具的 message tool）
3. 提醒：图片链接 30 天后失效，请及时保存
============================================================

图片编辑输出示例：

🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉
图片编辑成功！

============================================================
📸 图片信息
============================================================
图片 URL: https://gateway-result.com/xxx.png
⚠️  有效期: 30 天，请及时下载保存
本地路径: ./materials/raw_edit/abc123.png
文件大小: 1.8 MB

============================================================
📋 编辑参数
============================================================
输入图片: img.png (1张图片)
编辑指令: 把第一段正文标题更改为：如何寻找诱因？
图片尺寸: 1024x1024 (1K)
使用模型: google/gemini-3-pro-image-preview
认证方式: Cloudflare Gateway + OpenRouter

============================================================
💡 下一步操作
============================================================
1. 查看图片：open ./materials/raw_edit/abc123.png
2. 发送到钉钉/飞书？（使用 AI 工具的 message tool）
3. 提醒：图片链接 30 天后失效，请及时保存
============================================================

Resolution Options

API 支持三种分辨率（uppercase K required）：

1K (default) - ~1024px resolution
2K - ~2048px resolution
4K - ~4096px resolution

映射规则：

未提及分辨率 → 1K
"低分辨率"、"1080"、"1080p"、"1K" → 1K
"2K"、"2048"、"普通"、"中等分辨率" → 2K
"高分辨率"、"高清"、"hi-res"、"4K"、"ultra" → 4K

Common Failures & Solutions

错误	解决方案
`HTTP 401 Unauthorized`	检查 `.env` 文件中的 API keys 是否正确
`HTTP 403 Model not available`	Cloudflare Gateway 可绕过地区限制，确认 Gateway 配置
`Base image NOT FOUND`	团队需要准备 base.png 文件到模板目录
`Template config not found`	运行 `list_templates.py` 查看可用模板
`Network timeout`	确认通过 Cloudflare Gateway 访问，检查网络连接

Important Notes

关键配置要点：

✅ 国内必须使用 Cloudflare Gateway
✅ 需要双重认证 headers（cf-aig-authorization + Authorization）
✅ Base images 是团队准备的现成图片
✅ 模板生成输出到 materials/raw/
✅ 图片编辑输出到 materials/raw_edit/

Red Flags - 立即检查：

❌ 只使用单一 Authorization header → 必须双重认证
❌ 直接访问 OpenRouter API → 必须通过 Gateway
❌ Base image 缺失 → 运行 verify_template.py 检查
❌ 模板名称错误 → 运行 list_templates.py 查看列表
❌ 保存到错误目录 → 模板用 raw/，编辑用 raw_edit/

Examples

模板生成示例：

# 查看可用模板
python3 scripts/list_templates.py

# 验证模板
python3 scripts/verify_template.py --template "春节海报"

# 生成图片
p

nano-banana-pro-china