Generate Image

Commands

Generate New Image

source .venv/bin/activate && python scripts/generate_image.py generate "prompt" output_path.png

Examples:

# Character sprite with transparent background
source .venv/bin/activate && python scripts/generate_image.py generate "A cartoon knight character, side view, pixel art style" assets/sprites/knight.png --transparent

# Game background (16:9 for landscape games)
source .venv/bin/activate && python scripts/generate_image.py generate "A fantasy forest scene, vibrant colors, game background" assets/backgrounds/forest.png --aspect-ratio 16:9

# Portrait background (9:16 for portrait games)
source .venv/bin/activate && python scripts/generate_image.py generate "A vertical dungeon corridor, dark and atmospheric" assets/backgrounds/dungeon.png --aspect-ratio 9:16

# App icon (square)
source .venv/bin/activate && python scripts/generate_image.py generate "App icon for a space shooter game, bold neon colors, minimal" assets/icons/appicon.png

Edit Existing Image

source .venv/bin/activate && python scripts/generate_image.py edit "prompt" input.png output.png

Examples:

# Create damage variant of a character
source .venv/bin/activate && python scripts/generate_image.py edit "Add battle damage, torn clothes, scratches" assets/sprites/knight.png assets/sprites/knight_damaged.png

# Change scene mood
source .venv/bin/activate && python scripts/generate_image.py edit "Make the scene nighttime with moonlight" assets/backgrounds/forest.png assets/backgrounds/forest_night.png

# Remove elements
source .venv/bin/activate && python scripts/generate_image.py edit "Remove the clouds, make sky clear blue" assets/backgrounds/sky.png assets/backgrounds/sky_clear.png

Mix Multiple Images

Combine elements from multiple images into a new image. Supports composition, style transfer, and element fusion. The Gemini API accepts up to 14 reference images (up to 6 high-fidelity objects, up to 5 human references).

source .venv/bin/activate && python scripts/generate_image.py mix "prompt" image1.png image2.png ... -o output.png

Examples:

# Combine a character with a background
source .venv/bin/activate && python scripts/generate_image.py mix \
    "Place the knight character in front of the castle gate" \
    assets/sprites/knight.png assets/backgrounds/castle.png \
    -o assets/scenes/knight_at_castle.png

# Style transfer — apply one image's art style to another subject
source .venv/bin/activate && python scripts/generate_image.py mix \
    "Redraw the character in the art style of the reference image" \
    assets/sprites/hero.png assets/references/watercolor_style.png \
    -o assets/sprites/hero_watercolor.png

# Combine elements from three images
source .venv/bin/activate && python scripts/generate_image.py mix \
    "Create a scene with the warrior holding the sword, standing on the cliff" \
    assets/sprites/warrior.png assets/items/sword.png assets/backgrounds/cliff.png \
    -o assets/scenes/warrior_cliff.png --aspect-ratio 16:9

Crop Transparent Borders

source .venv/bin/activate && python scripts/generate_image.py crop image1.png image2.png ...

Examples:

# Crop a single sprite
source .venv/bin/activate && python scripts/generate_image.py crop assets/sprites/knight.png

# Crop with padding
source .venv/bin/activate && python scripts/generate_image.py crop assets/sprites/knight.png --padding 4

# Crop all sprites
source .venv/bin/activate && python scripts/generate_image.py crop assets/sprites/*.png

Parameters

Generate Command

Edit Command

Mix Command

Crop Command

iOS-Specific Asset Tips

App Icon Sizes

Generate at 1024x1024 (App Store size), then resize for device sizes:

Sprite Sizes (@2x/@3x)

Design sprites at @2x resolution, then scale for other densities:

Background Sizes

Launch Screen Images

Generate separate launch screen backgrounds for different device families.

Transparent Backgrounds

The --transparent flag creates images with transparent backgrounds, ideal for game sprites.

How It Works

1. Appends "solid bright green background #00FF00" to your prompt
2. Generates the image with a green screen background
3. Automatically removes the green pixels and makes them transparent
4. Auto-crops transparent borders

Tips

• Keep subjects simple and distinct from green (avoid green objects)
• Works best for: sprites, icons, characters, objects, UI elements
• May not work well for: landscapes, scenes with green elements

Creating Character Variants with Edit

The edit command creates consistent character variations (moods, damage states, power-ups).

Technique

1. Start with ONE good reference image
2. Use edit to change only the expression/state
3. Always edit from the SAME reference (don't chain edits)

Example: Character State Set

REF=assets/sprites/hero.png

# Idle state (reference)
source .venv/bin/activate && python scripts/generate_image.py generate \
    "A cartoon hero character, standing pose, pixel art, side view" \
    $REF --transparent

# Attack state
source .venv/bin/activate && python scripts/generate_image.py edit \
    "Change ONLY the pose to attacking with a sword swing. Same character, same art style, same colors." \
    $REF assets/sprites/hero_attack.png

# Damaged state
source .venv/bin/activate && python scripts/generate_image.py edit \
    "Add battle damage, scratches, torn clothes. Same character, same art style, same pose." \
    $REF assets/sprites/hero_damaged.png

# Power-up state
source .venv/bin/activate && python scripts/generate_image.py edit \
    "Add a glowing golden aura around the character. Same character, same pose, same style." \
    $REF assets/sprites/hero_powered.png

Tips for Consistency

• Always edit from the SAME reference image
• Be explicit about what stays the same (style, colors, proportions)
• Describe changes in physical terms
• Run variants in parallel (independent operations)

Combining Multiple Images with Mix

The mix command lets you compose new images from multiple references. This is useful for scene assembly, style transfer, and creating variations that draw from several source assets.

Composition: Placing Elements Together

Combine separate sprites or assets into a single scene:

source .venv/bin/activate && python scripts/generate_image.py mix \
    "Create a battle scene with the knight fighting the dragon in the forest clearing" \
    assets/sprites/knight.png assets/sprites/dragon.png assets/backgrounds/forest.png \
    -o assets/scenes/battle.png --aspect-ratio 16:9

Style Transfer: Applying Art Styles

Use one image as a style reference to restyle another:

# Apply watercolor style to a character
source .venv/bin/activate && python scripts/generate_image.py mix \
    "Redraw this character in the art style of the reference painting. Keep the character's pose and features identical." \
    assets/sprites/hero.png assets/references/watercolor_sample.png \
    -o assets/sprites/hero_watercolor.png

# Match an existing game's art direction
source .venv/bin/activate && python scripts/generate_image.py mix \
    "Create a new enemy character in the same art style as the reference character" \
    assets/references/style_guide.png \
    -o assets/sprites/new_enemy.png

Limits

• Up to 14 total reference images per call
• Up to 6 high-fidelity object images
• Up to 5 human reference images
• Output aspect ratio follows the --aspect-ratio flag; when omitted, defaults to 1:1

Tips for Multi-Image Prompts

• List what role each image plays: "Using the character from the first image and the background from the second..."
• Be explicit about what to keep and what to change
• For style transfer, emphasize "same art style" and describe what should carry over (colors, linework, shading)
• Simpler compositions (2-3 images) produce more reliable results than complex ones

Prompt Tips

For Game Sprites

• Specify art style: "pixel art", "cartoon", "flat vector", "hand-drawn"
• Include view: "side view", "top-down", "isometric", "front-facing"
• Describe clearly: size, pose, key features

For Backgrounds

• Include mood: "peaceful", "dangerous", "mysterious"
• Describe depth: "foreground trees, midground path, background mountains"
• Specify lighting: "golden hour", "moonlit", "overcast"

For UI Elements

• Keep it simple: "flat design button with rounded corners"
• Specify state: "normal state", "pressed state", "disabled state"
• Include style: match the game's overall art direction

Troubleshooting

"GEMINI_API_KEY environment variable not set"

# Add to .env file
echo 'GEMINI_API_KEY=your-api-key-here' >> .env

# Or export directly
export GEMINI_API_KEY="your-api-key-here"

"No image was generated"

• Prompt may have triggered safety filters - rephrase it
• Avoid content that might trigger restrictions

"google-genai package not installed"

source .venv/bin/activate && pip install google-genai Pillow