Banana 2

banana-2

Overview

通过 aihubmax.com 的 Nano Banana 2（模型 gemini-3.1-flash-image-preview）接口创建异步图片生成任务，创建成功后必须继续查询直到任务终态（completed 或 failed）。鉴权采用 Authorization: Bearer <key>。

支持文生图、图生图、图像编辑。尺寸由 aspect_ratio（宽高比）+ resolution（画质档，非像素） 两个字段共同决定。

完整字段说明、错误码、响应结构见 references/api-guide.md。

When to Use

• 用户明确点名 Nano Banana 2 / Banana 2 / nano banana / 香蕉 / gemini flash image / gemini-3.1-flash-image-preview
• 用户用宽高比描述尺寸（16:9、9:16、21:9、match_input_image 等），而非具体像素
• 用户用画质档描述清晰度（512、0.5K、1K、2K、4K）
• 用户想要联网搜索实时信息辅助生成（google_search）或图像搜索辅助生成（image_search，本模型独有）
• 用户提供参考图，希望基于参考图编辑/重绘（图生图，传 image_urls）

When NOT to Use

• 泛化的「生成图片 / 海报图 / 封面图」且用像素分辨率（如 1024x1024、1920x1080）描述 → 用 image-2 skill
• 视频生成、视频处理、音频处理
• OCR、文档解析、表格识别
• 非生成式编辑（裁剪、压缩、加水印、加边框）

CRITICAL

• 调用前必须完成参数校验，缺必填先补齐再调用 API
• 不得回显完整 Authorization token，日志只允许 head4****tail4 掩码
• 同参数任务在同一轮对话内禁止二次提交（参数任意变化即视为新任务，可创建）
• 禁止自动循环重试创建接口；重试需先告知会再次消耗积分并取得用户同意。唯一例外：HTTP 401 触发的 key 链 fallback——它换的是 key 不是同请求，且 401 不消耗积分，详见下方「401 自动 fallback」
• 创建接口返回的是异步任务，必须接着轮询查询接口直到终态
• 生成的图片 URL 24 小时后失效，需要长期保留请下载或转存
• 默认会把图片下载到当前工作区根目录，文件名 {YYYYMMDD-HHMMSS}-{≤10字标签}.{ext}；优先级：--filename > --label > 自动从 prompt 前 10 字提取。环境变量 BANANA_2_OUTPUT_DIR 或 --output-dir 可改保存目录
• 本模型每次只产 1 张图，没有 num_outputs；也没有 quality/background/mask_url 字段，不要臆造

Auth & Key Handling

读取优先级（从高到低）：

1. 本轮对话显式提供的 key（通过 X_API_KEY=... 注入给脚本）
2. 环境变量 X_API_KEY
3. $PWD/.env.local 中的 X_API_KEY=...（自动读取，无需 flag）
4. $PWD/.env 中的 X_API_KEY=...（自动读取，无需 flag）
5. ~/.config/banana-2/.env（仅 --use-local-key 时读）

环境变量名 X_API_KEY 与 image-2 一致（都是 aihubmax.com 的 key，可共用同一个）；值通过 Authorization: Bearer <key> 提交给 aihubmax.com。

401 自动 fallback：

• 如果某一层的 key 调用 POST /v1/images/generations 返回 HTTP 401（authentication_error），脚本会自动尝试链条中的下一个 key。401 不消耗积分，所以这种 fallback 安全。
• 其他错误码（402 余额不足 / 422 参数非法 / 429 限流 / 5xx 服务错误）以及网络错误不触发 fallback，立即返回让用户决定。
• 同一个 key 值在多个来源重复出现时只会试一次（按值去重）。
• 一旦某层 key 通过 create 调用成功，后续轮询查询接口都用同一个 key。

作用域约束：

• 第 3、4 层只读 $PWD 下的文件，不向上递归，避免在 Agent 任意 cwd 下误读父项目的 key。
• 想用 ~/.config/banana-2/.env 必须显式 --use-local-key，避免 Agent 在用户不知情时静默用持久化 key 扣费。
• key 在日志中始终掩码为 head4****tail4，完整值只出现在 Authorization header 内。

首次配置 key（可选）：

./scripts/set_key.sh                  # 交互式输入，存到 ~/.config/banana-2/.env
echo 'sk-xxx' | ./scripts/set_key.sh --stdin

会话级使用（推荐）：

export X_API_KEY='sk-xxx'

项目级使用：在项目根目录建 .env 或 .env.local：

# .env.local（不入版本控制）
X_API_KEY=sk-xxx

.env / .env.local 解析规则（极简，不等同于 shell）：

• 支持：KEY=value / KEY="value" / KEY='value'、等号两侧空白、# 起首的注释行、空行
• 文件中 X_API_KEY 出现多次时取最后一次
• 不支持 shell 展开（${OTHER} / $OTHER）、命令替换（$(...) / 反引号）、续行符 \ ——这些都会被当作字面字符串
• 只识别变量名 X_API_KEY，不识别 OPENAI_API_KEY / FOXAPI_KEY 等其他命名

Required & Optional Parameters

aspect_ratio 取值（15 种）

1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9 match_input_image

• match_input_image：尽量沿用输入参考图的宽高比（仅在传了 image_urls 时有意义）。

resolution 取值（5 档画质）

512 0.5K 1K 2K 4K

• 512 与 0.5K：half-size 输出
• 1K：约 1MP；2K：约 4MP；4K：约 16MP
• 这是画质档位，不是像素宽高；具体像素由 aspect_ratio × 档位共同决定

Workflow

1. 收集与校验：补齐 prompt；如果用户描述涉及"基于这几张图"/"参考这张图"/"把背景换成…"等编辑意图，需要 image_urls；按上表校验 aspect_ratio（15 值）、resolution（5 档）、output_format（如传）。
2. 预览摘要：向用户输出请求摘要（模型、模式、aspect_ratio、resolution、是否有参考图、是否开 google_search/image_search），明确"将消耗积分"，等待用户确认后再调用脚本。
3. 调用脚本：用 scripts/create_task.sh 提交。脚本本身不再二次确认，直接发起 create 并轮询。
4. 查询直到终态：脚本会以默认 8 秒间隔轮询 /v1/tasks/{id}?sync_upstream=true，直到 status=completed 或 failed。
5. 返回结果 & 自动保存：成功时输出 results[].url，并把图片下载到本地（详见下方 Output & Save）。失败时输出 error.code / error.message，不下载。

Output & Save

任务终态为 completed 后，脚本会自动下载 results[].url 中的图片到本地。Agent 必须把这一步当成主流程，不要只把 URL 抛给用户——24 小时后 URL 失效。

默认行为

• 保存目录：$PWD（脚本被调用时的工作目录 = 当前工作区根目录）
• 文件名：{YYYYMMDD-HHMMSS}-{标签}.{ext}
  • 时间戳取脚本启动时刻
  • 标签 = prompt 前 10 个 Unicode 字符，去除 /\:*?"<>| 等文件系统不安全字符，空白折叠为 _
  • 扩展名推断（本模型 results[] 通常只有 url、无 content_type）：--output-format（最可靠，用户显式意图）→ 响应 content_type（偶有）→ URL 路径尾缀（png/jpg/jpeg/webp）→ 默认 png
• 文件冲突：同名文件存在时追加 -2、-3...
• 本模型恒 1 张输出，不会出现 -01/-02 多图编号

覆盖优先级

Agent 解析用户意图

# 文生图（默认 1:1 / 1K）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "A futuristic city skyline at dusk, cyberpunk style" \
  --aspect-ratio 16:9 --resolution 1K

# 图像编辑（传参考图 + match_input_image + 图像搜索辅助）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "Replace the background with a tropical beach" \
  --image-url 'https://example.com/photo.jpg' \
  --aspect-ratio match_input_image --resolution 2K \
  --image-search

# 多张参考图（重复 --image-url）
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "把这两张图融合成一张极简海报" \
  --image-url 'https://example.com/a.png' \
  --image-url 'https://example.com/b.png' \
  --aspect-ratio 4:5 --resolution 2K

# 联网搜索辅助 + 指定输出格式
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "今天的科技新闻头条做成信息图" \
  --aspect-ratio 3:4 --resolution 2K \
  --google-search --output-format webp

# 保存到指定目录 + 指定文件名
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "Logo 设计" --aspect-ratio 1:1 --resolution 1K \
  --output-dir ~/Desktop --filename brand-logo

# 只要 URL，不下载
X_API_KEY='sk-xxx' ./scripts/create_task.sh \
  --prompt "..." --aspect-ratio 1:1 --resolution 1K --no-save

Error Handling

• 缺 prompt：提示用户补全提示词
• 缺 image_urls 但 prompt 暗示需要参考图（"基于这张图"/"把…换成…"）：先和用户确认是否提供参考图，再选择 text2img 或图像编辑
• aspect_ratio 非法：返回 15 种合法值清单，要求重选
• resolution 非法：返回 5 档合法值（512/0.5K/1K/2K/4K），要求重选
• output_format 非法：只支持 jpg/png/webp
• HTTP 401 authentication_error：key 无效/过期/权限不足，去 aihubmax.com 检查
• HTTP 402 insufficient_quota：余额不足，请用户充值后再试
• HTTP 422 validation_error：根据 error.message 调整参数
• HTTP 429 rate_limit_error：限流，禁止自动重试，告知用户稍后再试
• HTTP 5xx：服务异常，建议用户确认后由用户决定是否重试
• 轮询超时：明确告知任务可能仍在运行，给出 task_id 让用户后续手动查询

Dedup Rule

同一轮对话内，若 model + prompt + image_urls + aspect_ratio + resolution + output_format + google_search + image_search 全部相同，禁止再次提交；任何一项变化都允许新建。

Pre-Response Checklist

最终响应前自检：

• 是否完成必填与字段约束校验（aspect_ratio 15 值、resolution 5 档）
• 是否对 key 做了 head4****tail4 掩码
• 创建成功后是否输出了 task_id
• 是否轮询到 completed / failed 才结束
• 是否提示了图片 URL 24 小时过期
• 是否输出了本地保存路径（除非显式 --no-save）
• 用户在上下文里指定了保存位置/文件名时，是否被正确传给 --output-dir / --filename

Directory

• SKILL.md
• scripts/set_key.sh、scripts/create_task.sh
• references/api-guide.md
• tests/（pressure 场景文档）