Sprite Animator
Turn any image into an animated pixel art sprite GIF. Uses Gemini image generation to create 16-frame sprite sheets, then assembles them into looping GIFs.
Requirements
GEMINI_API_KEYorGOOGLE_API_KEYenv var must be set- Install:
uv tool install sprite-animator(oruvx sprite-animatorfor one-off runs)
Quick Usage
# Best quality for photos — two-step converts to pixel art first, then animates
sprite-animator -i photo.png -o dance.gif -a dance --two-step -s 256 -r 2K
# From drawings or pixel art (single step is fine)
sprite-animator -i drawing.png -o idle.gif -a idle -s 256 -r 2KAnimation Types
idle— gentle breathing + blink (default)wave— arm raise → wave → returnbounce— crouch → jump → landdance— lean, spin, jump — full party mode
Key Options
| Flag | Description | Default |
|---|---|---|
-i | Input image path | required |
-o | Output GIF path | required |
-a | Animation type (idle/wave/bounce/dance) | idle |
-s | Output sprite size in px | 128 |
-r | Generation resolution (1K/2K) | 1K |
-d | Frame duration in ms | 100 |
--two-step | Pixelate first, then animate (better for photos) | off |
--keep-sheet | Save raw sprite sheet | off |
--keep-frames | Save individual frame PNGs | off |
Tips
- Use
--two-stepfor photos of real people — Gemini loses likeness otherwise - Use
-r 2Kfor noticeably better quality - Use
-d 180for more natural playback speed (default 100ms is fast) - Save good base pixel art sprites and reuse them for different animations
- On Telegram, send GIFs as documents to avoid MP4 conversion
Python API
from pathlib import Path
from PIL import Image
from sprite_animator.cli import ANIMATION_PRESETS, generate_sprite_sheet, create_gif, call_gemini, get_api_key
from sprite_animator.template import create_template, extract_frames
api_key = get_api_key()
preset = ANIMATION_PRESETS["dance"]
# Create template and generate sprite sheet
template = create_template(cols=4, rows=4, labels=preset["labels"])
template.save("template.png")
generate_sprite_sheet(
api_key=api_key,
input_image=Image.open("input.png"),
template_path=Path("template.png"),
output_path=Path("sheet.png"),
prompt=preset["prompt"],
resolution="2K",
)
# Extract frames and build GIF
frames = extract_frames(Image.open("sheet.png"), cols=4, rows=4)
create_gif(frames, Path("output.gif"), frame_duration=180, size=256)