nano-banana (Google Gemini image models)

Direct Vertex AI calls via google-genai SDK. No third-party deps beyond what gemini-consult already needs. Auth via Application Default Credentials.

Prerequisites

• google-genai Python package (already installed for gemini-consult)
• ADC authenticated: gcloud auth application-default login
• GOOGLE_CLOUD_PROJECT env var set, or quota_project_id in ADC

If auth fails, the script exits with the GCP error verbatim. Direct the user to run gcloud auth application-default login and retry.

Models — pick one per call

Routing heuristic — Claude decides per request

Default to nano-banana-2. Escalate to nano-banana-pro when any of these signals appears:

Stay on nano-banana-2 when:

• General illustrations, icons, banners with no in-image text
• User says "빠르게", "대충", "draft", "초안"
• Batch jobs where cost / throughput matters
• Non-standard aspect ratios (1:4, 4:1, 1:8, 8:1) — only Nano Banana 2 supports these

Session-first-confirm pattern (mimics gemini-consult)

• First call of a session: announce the routing decision in one line before invoking the script. Example:

  → Nano Banana 2.1 사용 (기본 라우팅). 로고·텍스트·고품질이 필요하면 "Pro로" 말씀해 주세요.

  Or:

  → Nano Banana Pro 사용 (이미지 안에 텍스트가 들어가는 작업이라 자동 격상).

• Subsequent calls in the same session: skip the announcement, just say which model in one short line (e.g. → Nano Banana Pro (텍스트 렌더링)).
• User explicit override ("프로로 바꿔", "이번 건 2로", "그냥 빠른 거로"): switch immediately and keep that choice for the rest of the session unless the user changes their mind.

Workflow

1. Compose the prompt — Google-native 5-slot structure

Do not pass the user's raw request to the API. Rewrite as a flowing-prose paragraph using Google's Nano Banana structure — this is the biggest determinant of output quality.

Start the prompt with a strong verb (Generate, Create, Photograph, Illustrate, Render). The most important elements (subject + style) follow right after, which front-loads them naturally.

Positive framing, NOT negative constraints. Do NOT append "no watermark, no extra text, no border" lists — on Gemini those tokens enter the attention window and often summon the thing you forbade. To get a clean image, describe the clean state ("a clean empty studio backdrop"), not the absence.

Skip empty adjectives ("stunning, 8K, masterpiece"). Name concrete materials ("navy tweed" > "suit"). For literal text in the image: wrap in double quotes and name the font ("bold white sans-serif", "Century Gothic") — do NOT use EXACT TEXT verbatim markers or letter-by-letter spelling (both are obsolete and the latter actively breaks Gemini's tokenizer).

If multiple slots are missing from what the user said, ask one clarifying question targeting the most important gap and proceed with reasonable inferences for the rest.

Full prompting playbook (text rendering, camera/film-stock control, edit patterns, anti-patterns, multilingual, before/after): see references/prompting-guide.md.

2. Apply a DESIGN.md if present

If DESIGN.md exists in the current working directory (optional — skip silently if absent), or the user references one ("DESIGN.md 보고", "이 사이트 톤", "editorial-photo.md 스타일"), read it first and merge its palette / typography / illustration-style into slot 3 (Details) of every prompt in the current session. Same DESIGN.md = stylistic consistency across multiple images.

The descriptive lines ("hand-folded paper feel", "soft natural light from upper left", "single subject, plenty of whitespace") carry more weight than hex codes — preserve them verbatim.

Don't invent a DESIGN.md or nag the user to create one.

3. Pick aspect and size

Aspect from user intent:

Size:

• Default omit --size on legacy (nano-banana) — fixed 1024
• nano-banana-2: default to 1K; bump to 2K for hero/print, 4K for posters
• nano-banana-pro: default to 2K (Pro is for asset quality — don't waste it on 1K); 4K for print

4. Decide the output path

Default — save under cwd with a meaningful filename:

• ./assets/icons/dashboard.png
• ./public/og-image.png
• ./hero-banner.png
• ./gardener-autumn.png

Pass a kebab-case --name derived from the subject when the subject is clear. Otherwise let it default to the timestamp.

5. Run the script

python3 ~/.claude/skills/nano-banana/scripts/generate.py \
  "<Subject → Action → Location → Composition → Style prose>" \
  --model nano-banana-2 \
  --aspect 1:1 \
  --size 1K \
  --out . \
  --name <kebab-case-name>

Expected on success: stdout = N absolute path(s) (one per image), stderr = 1 model/usage line + N token lines. Empty stdout means generation failed — see Errors.

Bash tool timeout: ≥ 240,000 ms (Pro with thinking=high can take 1–2 min).

Editing an existing image — pass it with --ref and write a change-X / preserve-Y prompt (prefer Nano Banana Pro for fidelity):

python3 ~/.claude/skills/nano-banana/scripts/generate.py \
  "Change only the background to deep navy. Preserve everything else identically: \
the logo, all text, layout, lighting." \
  --ref ./current-banner.png \
  --model nano-banana-pro --aspect 16:9 --size 2K \
  --out . --name banner-navy

Combine several references (assign roles in the prompt): --ref pose.png --ref style.png + "use image 1 for the pose, image 2 for the art style."

If a benign prompt gets refused by the safety filter (empty result), retry with --safety relaxed (loosens the 4 tunable IMAGE harm categories + person_generation=allow_all), or --safety off for the loosest the API exposes. Server-side hard blocks (real public-figure likeness, CSAM, etc.) are unaffected by these flags — rephrasing the prompt is the only path there.

The script prints absolute path(s) on stdout, one per saved file, and tokens on stderr.

6. Report back

Tell the user:

1. The saved absolute path
2. Model + aspect + size used
3. Token usage (from stderr tokens: line)

If verification matters (text rendered correctly, layout right), open the PNG with the Read tool before reporting. Do not embed inline — just the path.

Completion checklist — verify all four before reporting (each check is mechanical; skipping them is the main way a silently-failed generation gets reported as success):

1. At least one image file exists at the reported path and is >0 KB — run ls -la <path> (a 0-byte file means the write failed even if the script exited 0).
2. stdout printed exactly one absolute path per generated image (--n 3 → 3 paths) — fewer paths means some calls returned no image.
3. If --ref was used, every reference image was PNG/JPEG/WebP — other formats (e.g. animated GIF, HEIC) are rejected and the edit silently degrades or fails.
4. The reported path(s) match what the user asked for (output dir, file name) — a wrong --out/--name saves to the wrong place even on an otherwise successful run.

Script CLI parameters

Errors

The script exits non-zero on failure with the raw error text. Common cases:

• PERMISSION_DENIED / UNAUTHENTICATED → gcloud auth application-default login
• Model not found → check the model ID is still in preview in your region
• aspect not supported → script catches before the API; check capability table
• 429 RESOURCE_EXHAUSTED → capacity or quota is temporarily exhausted; seen in bursts on gemini-nano-banana-2.1. The script waits and retries 3 times (10s, 30s, 60s). If it still fails, try later or use --model nano-banana-pro, and tell the user which model produced the image.
• IMAGE_RECITATION in the no-image error → the model declined that output, seen on a very generic prompt. Make the prompt more specific; safety flags don't change it.
• No image returned → safety filter or weak prompt. First try --safety relaxed / off; if still blocked it's a hard block — rephrase (drop named real people, ambiguous anatomy, violence). Do NOT auto-retry the same text.
• Timeout → bump Bash timeout; Pro thinking=high can be slow

Retry caution: every call is billed, and even a failed-looking run may have already produced a file. Before retrying, check whether the output file already exists (ls <out dir>); re-running overwrites same-name files but double-bills.

Limitations

• Editing & multi-reference: supported via --ref <image> (repeatable; nb2/pro up to 14, legacy nano-banana 3). One ref → edit that image (use change-X/preserve-Y, prompting-guide.md §4). Several refs → assign roles in the prompt ("image 1 for pose, image 2 for style"). Best on Nano Banana Pro. The script dedupes repeated paths, rejects animated GIF, and caps total inline input at ~20MB.
• Non-deterministic: same prompt yields different results each call. No seed support exposed.
• Safety: --safety tunes the 4 IMAGE harm categories + person_generation. Server-side hard blocks (real public-figure likeness, CSAM, sexual content) and the SynthID/C2PA watermark cannot be removed by any flag.

References

• references/prompting-guide.md — Google-native 5-slot (Subject/Action/Location/Composition/Style), strong-verb start, text rendering, camera/film-stock control, edit patterns, anti-patterns, multilingual, before/after
• references/api-reference.md — Vertex AI endpoints, ImageConfig fields, model capabilities matrix, pricing, error codes