BulkGen Agent Skill

Generate AI images with BulkGen. Scripts are bundled at ~/.claude/skills/bulkgen/scripts/ — always use this full path.

Language: Always respond in the user's language. This skill is written in English for consistency, but all replies to the user should match their language.

API Key

No environment variable setup needed. When the user asks to generate images:

Check if BULKGEN_API_KEY is already set in the environment.
If not set, ask the user in their language to share their key (format: sk_live_...). They can get one at bulk-gen.com → user menu → API Keys.
Once received, pass it inline — do not export it or persist it anywhere:

BULKGEN_API_KEY="sk_live_..." node $SCRIPTS/generate.js ...

If the user gets a 401 error, ask them to check their key or get a new one at bulk-gen.com.

Workflow

Clarify → If parameters are ambiguous, ask ratio + mode before generating
Generate → Run generate.js with the user's key inline
Preview → Always run build_preview.js and open the HTML immediately after

Before generating: clarify parameters

When the user asks for multiple images without specifying ratio or mode, ask before generating.

Ask when: User requests N images without specifying ratio or mode.

Skip asking when: Single image (solo mode), or all parameters already specified.

When asking, explain the two choices in the user's language:

Ratio: square (1:1), portrait (9:16), landscape (16:9) — default square
Mode: variation (one prompt, multiple styles) vs batch (different prompt per cell) — default variation

If the user says they don't mind or leaves it to you, use defaults (1:1 + variation) and confirm briefly.

Quick start

SCRIPTS=~/.claude/skills/bulkgen/scripts
KEY="sk_live_..."   # key provided by the user

# Single image
BULKGEN_API_KEY=$KEY node $SCRIPTS/generate.js --prompts "a sunset" --mode solo

# 3x3 variations (same prompt, different styles)
BULKGEN_API_KEY=$KEY node $SCRIPTS/generate.js --prompts "cyberpunk city" --mode variation --cols 3 --rows 3 --canvas-ratio 1:1

# 2x2 batch (different prompts per cell)
BULKGEN_API_KEY=$KEY node $SCRIPTS/generate.js --prompts "cat" "dog" "bird" "fish" --cols 2 --rows 2

# Edit with reference image
BULKGEN_API_KEY=$KEY node $SCRIPTS/generate.js --prompts "watercolor style" --input ./photo.jpg

# Build preview and open (always do this after generating)
node $SCRIPTS/build_preview.js ./bulkgen-result.json ./bulkgen-preview.html && open ./bulkgen-preview.html

Options

Option	Values	Default
`--mode`	solo, batch, variation	variation
`--cols`, `--rows`	Grid dimensions	auto
`--canvas-ratio`	1:1, 16:9, 9:16, 4:5, 3:4, 3:2, 2:3, 4:3, 5:4, 21:9	1:1
`--resolution`	1K, 2K, 4K	1K
`--input`	Reference image path	none

Modes

Mode	Use when
`solo`	Single image
`variation`	One prompt → multiple creative variants (same subject, different styles)
`batch`	Different prompts → each cell gets its own independent scene

Layouts

Valid: 1x1, 2x1, 1x2, 3x1, 1x3, 2x2, 3x2, 2x3, 4x2, 2x4, 3x3, 4x3, 3x4, 4x4

--canvas-ratio is the aspect ratio of the full grid, not a single cell. Some layout/ratio combinations are unsupported — the script will error and suggest alternatives.

Reference images

Use --input for style transfer or editing. Up to 14 images, 7 MB each. Formats: PNG, JPG, WebP, HEIC, HEIF.

Post-generation

Image URLs expire in 12 hours — always build the preview immediately.

SCRIPTS=~/.claude/skills/bulkgen/scripts

# Build HTML preview (always run this)
node $SCRIPTS/build_preview.js ./bulkgen-result.json ./bulkgen-preview.html && open ./bulkgen-preview.html

# Download permanent local copies (only if user explicitly asks)
node $SCRIPTS/download_images.js ./bulkgen-result.json ./downloads

Errors

Status	Action
401	Invalid key — ask user to check or get a new one at bulk-gen.com
402	Insufficient credits — ask user to top up at bulk-gen.com
400	Invalid params — check layout/ratio compatibility
500	Server error — retry once