sticker-generator 0.9.0

Generate stickers with transparent backgrounds using Gemini AI

Sticker Generator

Generate stickers with transparent backgrounds using Google's Gemini AI.

Examples

Kawaii	3D	Pixel Art	Watercolor	Minimal
"a cute happy cat"	"a sleek rocket ship"	"a friendly robot"	"a beautiful rose"	"a coffee cup"

Installation

pip install sticker-generator

Setup

Set your Gemini API key as an environment variable:

export GEMINI_API_KEY="your-api-key"

Or pass it directly to the functions/CLI.

Usage

Command Line

# Basic usage
sticker-generator "a cute happy cat with big eyes"

# Specify output file
sticker-generator "a rocket ship" -o rocket.png

# Use reference images
sticker-generator "similar style illustration" -i reference1.png -i reference2.png

# Custom aspect ratio
sticker-generator "a wide banner" --aspect-ratio 16:9

# Use a style preset
sticker-generator "a happy robot" --style kawaii
sticker-generator "a space astronaut" -s 3d -o astronaut.png

# Save raw image before processing
sticker-generator "a dog" --save-raw

# Generate multiple variations as a sheet
sticker-generator "happy cat" -n 4 --sheet -o cat_sheet.png

# Generate variations as individual files
sticker-generator "cute dog" -n 6 -o dog.png
# Creates: dog_1.png, dog_2.png, ..., dog_6.png

# Sheet with custom grid (3 columns)
sticker-generator "star" -n 9 --sheet --columns 3 -o stars.png

# Sheet + individual files
sticker-generator "robot" -n 4 --sheet --save-individuals -o robots.png

# Resize output to specific dimensions
sticker-generator "cute cat" --resize 512          # 512x512 square
sticker-generator "cute cat" --resize 512x256      # Fit within 512x256, maintain aspect ratio
sticker-generator "cute cat" --resize 512x256 --resize-exact  # Force exact dimensions (may distort)

# Output formats (PNG default, WebP supported)
sticker-generator "cute cat" -o cat.webp                    # Auto-detect from extension
sticker-generator "cute cat" -o cat.webp --lossy -q 85      # Lossy WebP with quality
sticker-generator "cute cat" -f webp-lossy -q 90            # Explicit format preset
sticker-generator "cute cat" -n 4 --sheet -o sheet.webp     # Sheet in WebP format

# Process an existing green-screen image (no API key needed)
sticker-generator --process photo_with_green_bg.png -o transparent.png
sticker-generator --process input.png -o out.webp --resize 512

# Strict mode: exit with error if quality validation fails
sticker-generator "a cat" --strict

# Tune green removal for tricky images
sticker-generator "a cat" --hue-center 120 --hue-range 40 --min-saturation 30

# Retry options for unreliable connections
sticker-generator "a cat" --max-retries 5 --retry-delay 2.0
sticker-generator "a cat" --max-retries 0  # Disable retries

# Verbose mode (shows processing details on stderr)
sticker-generator "a cat" -o cat.png --verbose

# Debug mode (verbose + auto-saves intermediate images)
sticker-generator "a cat" -o cat.png --debug
ls cat_intermediates/  # 01_raw_from_api.png, 02_after_hsv_removal.png, ...

# Quiet mode (only warnings and errors)
sticker-generator "a cat" -o cat.png --quiet

# Save intermediate images to a custom directory
sticker-generator "a cat" -o cat.png --save-intermediates /tmp/debug/

# Save intermediates with auto-generated directory name
sticker-generator "a cat" -o cat.png --save-intermediates

# Batch generate from a prompts file (one prompt per line, # for comments)
sticker-generator --batch-prompts prompts.txt --output-dir ./stickers/

# Batch generate with style and format options
sticker-generator --batch-prompts prompts.txt --output-dir ./stickers/ -s kawaii -f webp

# Batch process all images in a directory (remove green backgrounds)
sticker-generator --batch-dir ./green-screen-photos/ --output-dir ./processed/

# Batch with strict mode (stop on first failure)
sticker-generator --batch-prompts prompts.txt --output-dir ./stickers/ --strict

# Control delay between API requests in batch mode
sticker-generator --batch-prompts prompts.txt --output-dir ./stickers/ --delay 2.0

# Concurrent batch generation (4 workers)
sticker-generator --batch-prompts prompts.txt --output-dir ./stickers/ --max-workers 4

# Concurrent sheet generation
sticker-generator "happy cat" -n 8 --sheet -o cats.png --max-workers 4

Available Styles

Style	Description
kawaii	Cute Japanese style with big eyes and pastel colors
minimal	Clean minimalist style with flat colors
3d	3D rendered look with depth and lighting
pixel-art	Retro pixel art style
retro	Vintage retro style with muted colors
watercolor	Soft watercolor painting style

Output Formats

Format	Description
png	Lossless PNG (default)
webp	Lossless WebP (smaller files)
webp-lossy	Lossy WebP with quality setting (smallest files)

Format options:

• -f, --format FORMAT - Explicit format preset (auto-detects from extension if omitted)
• -q, --quality 1-100 - Quality for lossy formats (higher is better)
• --lossless - Force lossless compression
• --lossy - Force lossy compression

Concurrent Execution

Speed up batch and sheet generation by processing multiple stickers in parallel:

Flag	Default	Description
--max-workers	1	Max concurrent workers (1 = sequential)

When max_workers > 1, --delay is ignored (concurrency controls rate limiting instead). Strict mode (--strict) forces sequential execution for deterministic error handling.

Green Removal Tuning

If green removal produces bad results (incomplete removal or subject removal), tune these parameters:

Flag	Default	Description
--hue-center	115	Center hue for green detection (degrees)
--hue-range	35	Tolerance around hue center (degrees)
--min-saturation	25	Minimum saturation % to consider green
--min-value	40	Minimum brightness % to consider green
--green-threshold	1.1	Aggressive green ratio threshold (higher = more conservative)

Retry Options

Failed API calls are automatically retried with exponential backoff. This handles transient HTTP errors (429 rate limits, 500/502/503/504 server errors) and cases where the API returns no image.

Flag	Default	Description
--max-retries	3	Maximum number of retries for failed API calls
--retry-delay	1.0	Initial delay between retries in seconds (doubles each retry)

Quality Validation

After processing, the tool automatically checks the transparency ratio and warns about potential issues:

• >95% transparent: The subject may have been removed along with the background
• <5% transparent: Green background removal may have failed

Use --strict to make these warnings exit with a non-zero status code (useful in scripts/CI).

Verbosity & Debug Mode

Flag	Level	What you see
(default)	INFO	Progress messages, completion, quality warnings
-v, --verbose	DEBUG	Above + processing params, pixel stats, API details
--debug	DEBUG	Same as verbose, plus auto-saves intermediate images
--quiet	WARNING	Only warnings and errors

Troubleshooting

If green removal produces unexpected results, use --debug to inspect each processing stage:

sticker-generator "a tree frog" -o frog.png --debug
ls frog_intermediates/
# 01_raw_from_api.png        - Raw image from Gemini
# 02_after_hsv_removal.png   - After HSV-based green removal
# 03_after_aggressive_removal.png - After aggressive green pass
# 04_after_edge_cleanup.png  - After edge cleanup

You can also save intermediates without debug verbosity:

sticker-generator "a frog" -o frog.png --save-intermediates /tmp/debug/

Python API

from sticker_generator import create_sticker, get_available_styles, get_available_formats

# Basic usage
sticker = create_sticker(
    prompt="a cute happy cat with big eyes",
    output="cat.png"
)

# With a style preset
sticker = create_sticker(
    prompt="a happy robot",
    output="robot.png",
    style="kawaii"
)

# List available styles
print(get_available_styles())
# ['3d', 'kawaii', 'minimal', 'pixel-art', 'retro', 'watercolor']

# List available formats
print(get_available_formats())
# ['png', 'webp', 'webp-lossy']

# Save as WebP (auto-detected from extension)
sticker = create_sticker(
    prompt="a rocket ship",
    output="rocket.webp"
)

# Lossy WebP with custom quality
sticker = create_sticker(
    prompt="a star",
    output="star.webp",
    output_format="webp-lossy",
    quality=85
)

# With reference images
sticker = create_sticker(
    prompt="similar style illustration",
    output="custom.png",
    input_images=["reference1.png", "reference2.png"]
)

# Just get the image without saving
sticker = create_sticker(
    prompt="a rocket ship",
    output=None  # Returns PIL Image
)

# Resize output
sticker = create_sticker(
    prompt="a cute cat",
    output="cat_small.png",
    resize=(256, 256)  # Fit within 256x256, maintain aspect ratio
)

# Force exact dimensions (may distort)
sticker = create_sticker(
    prompt="a cute cat",
    output="cat_exact.png",
    resize=(512, 256),
    resize_exact=True
)

# Custom green removal parameters for tricky images
sticker = create_sticker(
    prompt="a tree frog",
    output="frog.png",
    hue_center=120,
    hue_range=40,
    min_saturation=30,
    min_value=50,
    green_threshold=1.3
)

# Custom retry settings
sticker = create_sticker(
    prompt="a cute cat",
    output="cat.png",
    max_retries=5,     # More retries for unreliable connections
    retry_delay=2.0    # Start with 2s delay, doubles each retry
)

# Save intermediate images for debugging
sticker = create_sticker(
    prompt="a tree frog",
    output="frog.png",
    save_intermediates="frog_debug/"  # Saves each pipeline stage as PNG
)

Batch Processing

Generate multiple stickers from a prompts file or process a directory of images:

from sticker_generator import batch_generate, batch_process_images, parse_prompt_file

# Generate stickers from a list of prompts
result = batch_generate(
    prompts=["a cute cat", "a happy dog", "a friendly robot"],
    output_dir="./stickers/",
    style="kawaii",
    max_workers=4,  # Generate 4 stickers concurrently
)
print(f"Generated {len(result.successful)}/{result.total} stickers")
for item in result.failed:
    print(f"  Failed: {item.source} - {item.error}")

# Read prompts from a file
prompts = parse_prompt_file("prompts.txt")
result = batch_generate(prompts=prompts, output_dir="./stickers/")

# Process all images in a directory (remove green backgrounds)
result = batch_process_images(
    input_dir="./green-screen-photos/",
    output_dir="./processed/",
    output_format="webp",
)
print(f"Processed {len(result.successful)}/{result.total} images")

# Strict mode: stop on first failure
result = batch_generate(
    prompts=["a cat", "a dog"],
    output_dir="./stickers/",
    strict=True,
)

Process Existing Images

Remove green backgrounds from existing images without using the Gemini API:

from sticker_generator import process_image

# Basic usage - remove green background from an existing image
result = process_image("green_screen_photo.png", output="transparent.png")

# With resize and format options
result = process_image(
    "input.png",
    output="output.webp",
    resize=(512, 512),
    output_format="webp-lossy",
    quality=90
)

# Just get the PIL Image without saving
image = process_image("input.png")

CLI equivalent:

sticker-generator --process green_screen_photo.png -o transparent.png
sticker-generator --process input.png -o output.webp --resize 512 -f webp-lossy -q 90

Quality Validation

Check the quality of processed images programmatically:

from sticker_generator import validate_transparency, create_sticker

sticker = create_sticker("a cute cat", output="cat.png")

# Inspect transparency metrics
metrics = validate_transparency(sticker)
print(f"Transparent: {metrics.transparent_ratio:.0%}")
print(f"Opaque: {metrics.opaque_ratio:.0%}")
print(f"Semi-transparent: {metrics.semi_transparent_pixels} pixels")

if metrics.has_quality_warning:
    print(f"Warning: {metrics.warning_message}")

Sticker Sheets

Generate multiple variations and combine into a grid:

from sticker_generator import generate_sticker_sheet

# Generate 4 variations as a sheet
result = generate_sticker_sheet(
    prompt="happy cat",
    variations=4,
    output="cat_sheet.png",
    max_workers=4,  # Generate 4 variations concurrently
)

# Access individual stickers
for i, sticker in enumerate(result.stickers):
    sticker.save(f"cat_{i}.png")

# Check for failures
if result.failed_indices:
    print(f"Failed variations: {result.failed_indices}")

# Custom grid layout
result = generate_sticker_sheet(
    prompt="star",
    variations=6,
    output="stars.png",
    columns=3,      # 3x2 grid
    padding=20      # 20px between stickers
)

# Sheet in WebP format with lossy compression
result = generate_sticker_sheet(
    prompt="robot",
    variations=4,
    output="robots.webp",
    output_format="webp-lossy",
    quality=90,
    save_individuals=True  # Individual files also saved as .webp
)

Image Processing Only

If you have your own green-screen images and want fine-grained control:

from PIL import Image
from sticker_generator import remove_green_screen_hsv, cleanup_edges, resize_image, save_transparent_image

# Load your image
img = Image.open("green_background.png")

# Remove green background
transparent = remove_green_screen_hsv(img)

# Clean up edges
clean = cleanup_edges(transparent, threshold=64)

# Optional: resize the result
resized = resize_image(clean, (256, 256))  # Fit within bounds, maintain aspect ratio
resized = resize_image(clean, (256, 256), maintain_aspect=False)  # Force exact size

# Save as PNG
resized.save("transparent.png")

# Save as WebP with format options
save_transparent_image(resized, "transparent.webp")  # Lossless WebP
save_transparent_image(resized, "transparent.webp", "webp-lossy")  # Lossy WebP

How It Works

1. Style Application: Optional style presets modify your prompt to achieve specific visual styles
2. Generation: Uses Gemini AI to generate an image with a chromakey green (#00FF00) background
3. Green Removal: Converts to HSV color space and removes pixels matching green hue (configurable thresholds)
4. Aggressive Green Pass: Catches darker greens and tinted shadows using green channel dominance ratio
5. Edge Cleanup: Removes semi-transparent edge artifacts for clean results
6. Resize (optional): Resizes output to specified dimensions using LANCZOS resampling
7. Quality Validation: Checks transparency ratio and warns about potential issues

License

MIT