# Nb2 Batch

> Batch-generate 2x2 contact sheet grids via the Nanobanana MCP (Nano Banana / NB2 / Gemini Image) for AI media pipelines. Handles prompt cleaning, up to 3 reference images per call, parallel batch orchestration, and generation logging so prior runs inform new ones. Use whenever the user asks to "generate frames", "run NB2 batch", "regen scenes", "generate contact sheets", "make grid variants", "batch generate with nano banana", or needs parallel image generation for AI film or media production. Trigger this skill after prompt edits when new frames are needed, even if the user only says "regenerate those".

- Skill: `luishiluy/nb2-batch` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add luishiluy/nb2-batch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luishiluy/nb2-batch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: LuisHiluy (https://skillmd.com/u/luishiluy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luishiluy/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

```python
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

```json
{
  "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

```bash
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

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

### Check what was previously generated

```bash
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](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.