aipixel

Python library for generating pixel art game assets via the Retro Diffusion API (Replicate).

Installation

pip install -e .
# Dev extras (pytest, pytest-mock):
pip install -e ".[dev]"
# ML extras (scikit-learn for better palette extraction on complex images):
pip install -e ".[ml]"

Setup

Set your Replicate API token:

export REPLICATE_API_TOKEN=your_token_here

Or pass it directly: AiPixel(api_token="r8_...").

Quick Start

from aipixel import AiPixel, GenerationConfig

ap = AiPixel()  # reads REPLICATE_API_TOKEN from env
images = ap.generate("a dark mossy rock", reference="reference/environment/rocks/rock_001.png")
images[0].save("rock_generated.png")

Usage

Text prompt only

from aipixel import AiPixel, GenerationConfig

ap = AiPixel()
config = GenerationConfig(width=64, height=64, style="low_res")
images = ap.generate("small wooden barrel, top-down pixel art", config=config)
images[0].save("barrel.png")

With reference image for style matching

images = ap.generate(
    "dark rock formation",
    reference="reference/environment/rocks/rock_001.png",
    config=GenerationConfig(width=64, height=64),
)

With explicit hex palette

from aipixel.palette import hex_to_rgb

palette = hex_to_rgb(["#1a1a2e", "#16213e", "#0f3460", "#e94560"])
images = ap.generate("neon chest", palette=palette)

Auto-paired palette from a single color

palette = ap.auto_palette("#3A7BD5", count=4)
images = ap.generate("blue crystal", palette=palette)

Extract palette from existing asset

palette = ap.extract_palette("reference/environment/rocks/rock_001.png", max_colors=6)
print(palette)  # [(r, g, b), ...]

Generate variations from a reference

variations = ap.variations(
    "reference/environment/trees/dark-1.png",
    count=3,
    prompt="dark fantasy tree silhouette",
)
for i, img in enumerate(variations):
    img.save(f"tree_variant_{i}.png")

Generate animations (rd-animation)

Generate a complete multi-direction animated spritesheet in a single API call, powered by the Retro Diffusion rd-animation model.

from aipixel import AiPixel, AnimationConfig

ap = AiPixel()
result = ap.animate(
    "pixel art knight walking cycle",
    reference="reference/player/player.png",
    config=AnimationConfig(style="walking_and_idle"),
)
result.spritesheet.save("knight_walk.png")

Access frames by direction:

# result.directions: {'front': [...], 'left': [...], 'back': [...], 'right': [...]}
for direction, frames in result.directions.items():
    for i, frame in enumerate(frames):
        frame.save(f"knight_{direction}_{i}.png")

Available animation styles:

Style	Grid	Frame size	Directions
walking_and_idle	4×4	48×48	front / left / back / right
four_angle_walking	4×4	48×48	front / left / back / right
small_sprites	5×4	32×32	front / left / back / right
vfx	1 row	24–96px	— (no directions)

Full pipeline: extract palette → generate → save

from aipixel import AiPixel, GenerationConfig

ap = AiPixel()
ref = "reference/environment/rocks/rock_001.png"
palette = ap.extract_palette(ref, max_colors=6)
config = GenerationConfig(width=64, height=64, max_colors=6, remove_bg=True)
images = ap.generate("dark rock pile", reference=ref, palette=palette, config=config)
images[0].save("rock_pile.png")

Configuration

GenerationConfig (ap.generate, ap.variations)

Parameter	Type	Default	Description
width	int	128	Output width in pixels (16–384)
height	int	128	Output height in pixels (16–384)
style	str	"low_res"	RD Plus style preset (see Available Styles)
strength	float	0.7	img2img strength when reference provided (0.0–1.0)
max_colors	int | None	None	Post-process palette enforcement (1–256)
remove_bg	bool	True	Transparent background — output is RGBA
bypass_prompt_expansion	bool	True	Use prompt as-is without expansion
seed	int | None	None	Random seed for reproducibility
num_images	int	1	Number of images to generate (1–10)

AnimationConfig (ap.animate)

Parameter	Type	Default	Description
style	str	"walking_and_idle"	Animation style (see table above)
width	int	48	Frame width — must match style constraint
height	int	48	Frame height — must match style constraint
seed	int | None	None	Random seed for reproducibility
bypass_prompt_expansion	bool	False	Use prompt as-is without expansion

Available Styles

default  retro  watercolor  textured  cartoon  ui_element  item_sheet
character_turnaround  environment  isometric  isometric_asset  topdown_map
topdown_asset  classic  topdown_item  low_res  mc_item  mc_texture  skill_icon

Tests

# Unit tests (no API key needed):
pytest tests/ -k "not integration"

# Integration tests (real API call — requires REPLICATE_API_TOKEN):
REPLICATE_API_TOKEN=your_token pytest tests/ -m integration -v