PixelLab API v2 — Direct Pixel Art Generation

Generate pixel art assets via PixelLab REST API v2 — animations, UI elements, sprites, editing, and more. Complements the PixelLab MCP server with endpoints not available through MCP.

When to use this skill

Use PixelLab MCP instead for: characters with directional views, Wang tilesets, sidescroller tilesets, map objects.

Setup

1. Get API key from https://pixellab.ai/account
2. Add to project .env: PIXELLAB_API_KEY=your-token
3. Copy tools/pixellab.sh to your project's scripts/ directory
4. Make executable: chmod +x scripts/pixellab.sh

Reference Files

Tool: scripts/pixellab.sh

Helper script that wraps all PixelLab API v2 endpoints. Reads PIXELLAB_API_KEY from .env. Handles base64 encoding, async job polling, and saves output PNGs automatically.

Commands

# Animate a static sprite (SYNC — most useful for game dev)
./scripts/pixellab.sh animate <sprite.png> "<action>" [frame_count] [outdir]

# Generate pixel art from text (ASYNC — polls automatically)
./scripts/pixellab.sh generate "<description>" [WxH] [outdir]

# Generate UI elements (ASYNC)
./scripts/pixellab.sh generate-ui "<description>" [WxH] [palette] [outdir]

# Edit existing sprite (ASYNC)
./scripts/pixellab.sh edit <sprite.png> "<description>" [outdir]

# Generate matching style (ASYNC)
./scripts/pixellab.sh style <ref-sprite.png> "<description>" [WxH] [outdir]

# Rotate sprite direction (SYNC)
./scripts/pixellab.sh rotate <sprite.png> <from-dir> <to-dir> [outpath]

# Smart resize (SYNC)
./scripts/pixellab.sh resize <sprite.png> <WxH> [description] [outpath]

# Remove background (SYNC)
./scripts/pixellab.sh remove-bg <sprite.png> [outpath]

# Poll async job manually
./scripts/pixellab.sh poll <job-id> [outdir]

Quick Examples

Animate existing character sprite

# 8-frame walk animation from static south-facing sprite
./scripts/pixellab.sh animate public/assets/games/frost-hold/player-south.png \
  "walking forward" 8

# Attack animation
./scripts/pixellab.sh animate public/assets/games/frost-hold/player-south.png \
  "attacking with sword, slash animation" 8

# Casting spell
./scripts/pixellab.sh animate public/assets/games/frost-hold/player-south.png \
  "casting ice spell, magical frost blast" 8

Output: public/assets/test-api/animate-player-south/frame-{0..7}.png

Generate UI elements

# Button states
./scripts/pixellab.sh generate-ui \
  "pixel art medieval stone button with gold trim, normal and pressed states side by side" \
  256x128 "brown and gold"

# Health bar frame
./scripts/pixellab.sh generate-ui \
  "pixel art health bar frame, ornate metal border, empty inside, horizontal" \
  256x64 "red and silver"

# Inventory slot
./scripts/pixellab.sh generate-ui \
  "pixel art inventory grid slot, dark stone background, subtle border" \
  64x64 "dark grey and brown"

Generate game items / icons

# Multiple icon variants (64x64 generates 16 results)
./scripts/pixellab.sh generate "pixel art golden trophy cup, game achievement icon" 64x64

# Weapon sprites
./scripts/pixellab.sh generate "pixel art flaming sword, fantasy RPG weapon" 64x64

Style-matched generation

# Generate new enemy matching existing game style
./scripts/pixellab.sh style \
  public/assets/games/frost-hold/player-south.png \
  "ice goblin enemy, aggressive stance" 48x48

Rotate missing directions

# Generate east-facing from south-facing
./scripts/pixellab.sh rotate \
  public/assets/games/crystal-td/golem.png south east

# Generate north-facing
./scripts/pixellab.sh rotate \
  public/assets/games/crystal-td/golem.png south north

Edit existing sprite

# Add equipment to character
./scripts/pixellab.sh edit player.png "add a red cape and iron helmet"

# Recolor
./scripts/pixellab.sh edit enemy.png "change color to ice blue, frost theme"

Sync vs Async Endpoints

Async commands poll every 10s with a 120s timeout. Use poll command to resume if needed.

Output Behavior

• Sync commands: save directly to output path
• Async commands: poll until complete, then save all result images
• Default output: public/assets/test-api/<command>-<name>/
• Custom output: pass outdir/outpath as last argument
• Multiple results: generate/generate-ui often return multiple variants (4-64 depending on size)

Image Size → Result Count (generate/generate-ui)

Animation Frame Guidelines

Frame count must be even. Max 256x256 per frame. Pixel budget: width x height x frames ≤ 524,288.

Tips

• Describe actions, not poses: "walking forward" > "left foot forward right foot back"
• no_background: true is always set by the helper — sprites come transparent
• Seed parameter: not exposed in helper yet — edit script if you need reproducibility
• Asset format: all output is PNG with transparency
• Animate best practice: use the "south" facing idle frame as first_frame for best results
• Always outline: "lineless" preference — matches PixelDen art style