Nb2 batch

NB2 Batch Generation — 2x2 Contact Sheet Grids

Description

Generate 2x2 contact sheet grids for AI media projects using the Nanobanana MCP (mcp__nanobanana__generate_image). Each call produces a single image with 4 panels for hero frame selection.

When to Use

• User asks to generate or regenerate 2x2 grids, variant frames, or scene images
• User says "generate frames", "run NB2 batch", "regen scenes"
• After prompt block edits when new frames are needed

Generation Settings (recommended defaults)

Parameter	Value	Why
aspect_ratio	"16:9"	Cinematic frame ratio
model_tier	"nb2"	Nano Banana 2 (may auto-escalate to pro)
resolution	"4k"	Highest resolution available
n	1 (coverage) or 4 (variants)	1 for coverage pass, 4 for hero selection
negative_prompt	"text, watermark, logo, title card, UI elements, split screen borders, white borders"	Prevent unwanted artifacts
enable_grounding	false	Grounding adds noise for fictional content

Prompt Rules

• No character names — use descriptors ("the son", "the soldier", "the mother")
• Strip external tag references — MCP-specific tags from other tools are ignored
• Include grid directive — add "2x2 contact sheet grid, four equal panels, thin borders" in the prompt
• Front-load character descriptions in the first 200 chars
• Camera specs — include lens and film stock for cinematic tone

Reference Images

• Pass up to 3 reference images via input_image_path_1/2/3
• Priority order: character turnaround > location > prop
• Source from your references/approved/ directory

Output

• Save to: runs/grids/variants/{ITEM_ID}/
• Use output_path parameter pointing to the variant directory
• Files are auto-named by the MCP tool

Batch Workflow

1. Load prompts

import json
with open("runs/prompts.json") as f:
    prompts = json.load(f)

2. Build manifest

For each item, extract:

• prompt_text (strip references and external tag refs)
• ref_images (up to 3 resolved absolute paths)
• output_dir (e.g., runs/grids/variants/{item_id}/)

3. Generate in parallel batches of 3

Run 3 concurrent mcp__nanobanana__generate_image calls per batch to balance API load. More may hit rate limits.

4. Example MCP call

{
  "prompt": "2x2 contact sheet grid, four equal panels, thin borders, no text. [scene prompt here]",
  "aspect_ratio": "16:9",
  "model_tier": "nb2",
  "resolution": "4k",
  "negative_prompt": "text, watermark, logo, title card, UI elements, split screen borders, white borders",
  "enable_grounding": false,
  "n": 1,
  "input_image_path_1": "/abs/path/to/turnaround.png",
  "input_image_path_2": "/abs/path/to/location.png",
  "output_path": "/abs/path/to/runs/grids/variants/shot-01/"
}

Cost Reference

• Pro tier: ~$0.04 per image
• 27 scenes × 1 image = ~$1.08 per full pass
• 27 scenes × 4 images = ~$4.32 per variant pass

World / Palette Anchoring (example)

Include a palette hint in each prompt for consistent world identity:

World	Colors
Cold	Steel blue, black, cold grey — no warm tones
Diffused	Teal, cyan, soft light
Warm	Red, terracotta, rust
Liminal	Cold moonlight plus distant warm glow in tension
Neutral	Dawn light, warm and cool coexisting

Generation Memory

Every batch run should be logged. This lets future sessions know what was generated, what prompts worked, and what scores were achieved.

Log a generation

python3 "${CLAUDE_SKILL_DIR}/scripts/log-generation.py" log \
  --scene shot-06 \
  --prompt "2x2 contact sheet grid..." \
  --model nb2 \
  --refs "references/approved/characters/hero/front.jpg" \
  --output-path "runs/grids/variants/shot-06/" \
  --notes "Round 2 — strengthened character descriptors"

Attach quality scores after verification

python3 "${CLAUDE_SKILL_DIR}/scripts/log-generation.py" add-scores --scene shot-06

Check what was previously generated

python3 "${CLAUDE_SKILL_DIR}/scripts/log-generation.py" history --scene shot-06

Before generating: always read history first

At the start of any batch run, read the generation history for target items. This tells you:

• Which prompts were already tried
• What worked (GOOD verdict) and what did not (FAIL)
• Whether to iterate on the best prompt or try something new

For log format details, see reference/generation-format.md.

Gotchas

• Model tier escalation — nb2 may auto-escalate to pro tier. Changes cost slightly.
• 2x2 grid splitting — the MCP generates a single 4-panel image. Crop with a separate tool if you need individual frames.
• Reference image limit — NB2 MCP accepts max 3 reference images. Priority: character > location > prop.
• Prompt length — NB2 handles long prompts well, but front-load key descriptors in the first 200 chars.
• Output directory — must exist before generation. Create with mkdir -p if needed.
• Parallel batch size — 3 concurrent calls is the safe limit. More may hit rate limits.