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_KEYis 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
exportit 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.jswith the user's key inline - Preview → Always run
build_preview.jsandopenthe 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.htmlOptions
| 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 ./downloadsErrors
| 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 |