pag — Pixel Art Generator

pag (pixel art generator) — a Python CLI tool for generating pixel art using the Retro Diffusion API.

Features

Generate pixel art from text prompts with 60+ style presets
Six model tiers: RD_PRO, RD_FAST, RD_PLUS, RD_TILE (tilesets), Animation, Advanced Animation
Sprite sheet and GIF animation generation (walking, idle, VFX, rotations, advanced character animations)
Tileset generation (full tilesets, single tiles, variations, objects)
Image editing with text prompts (pag edit)
img2img transformation with strength control
Palette reference for color guidance
Reference image support (up to 9 images for RD_PRO)
Seamless tiling (X/Y axis)
Background removal
Custom style management (create, update, delete)
Cost estimation and balance checking
Flexible output naming: exact path, directory + auto-name, or custom pattern
Installs globally via uv

Requirements

Python 3.12+
Ubuntu 25.10+ (or any Linux with uv support)
A Retro Diffusion API key

Quickstart

# 1. Clone and install
git clone git@github.com:Ymx1ZQ/pag.git
cd pag
chmod +x install.sh
./install.sh

# 2. Set your API key (the installer will ask, or do it manually)
pag config set-key

# 3. Generate your first pixel art image
pag generate "a cute red mushroom" --style rd_fast__simple --size 64x64

# 4. Check the output — the PNG is saved in your current directory
ls *.png

That's it! The image is saved as a_cute_red_mushroom_<timestamp>.png in your current directory.

Installation

Via install.sh (recommended)

git clone git@github.com:Ymx1ZQ/pag.git
cd pag
chmod +x install.sh
./install.sh

The install script will:

Check that Python 3.12+ is installed
Install uv if not already present
Install pag as a global CLI tool via uv tool install
Verify the installation with pag --version

One-liner from GitHub

uv tool install git+https://github.com/Ymx1ZQ/pag.git

Manual installation (from local clone)

uv tool install .

Configuration

Your API key is stored in ~/.pag/.env. The installer will prompt you to set it up, or you can do it anytime:

# Interactive (hides input)
pag config set-key

# Or pass it directly
pag config set-key YOUR_KEY

# Check current configuration
pag config show

You can also override the saved key for a single command with --api-key:

pag generate "a cat" --style rd_pro__default --api-key OTHER_KEY

Resolution order: --api-key flag > ~/.pag/.env

Usage

`pag generate` — Generate pixel art

Generate one or more pixel art images from a text prompt.

# Basic generation (uses style's default size)
pag generate "a cool corgi" --style rd_pro__default

# Specify exact size
pag generate "a cool corgi" --style rd_pro__default --size 128x128

# Multiple images with a fixed seed
pag generate "dungeon tileset" --style rd_pro__dungeon_map -n 4 --seed 42

# With background removal
pag generate "sword icon" --style rd_fast__item_sheet --size 64x64 --remove-bg

# With reference images (RD_PRO supports up to 9)
pag generate "a warrior" --style rd_pro__fantasy --ref image1.png --ref image2.png

# Seamless tiling (for textures)
pag generate "grass texture" --style rd_pro__default --tile-x --tile-y

# img2img — transform an existing image
pag generate "pixel art cat" --style rd_pro__default --input-image photo.png --strength 0.8

# With palette reference
pag generate "forest scene" --style rd_pro__default --input-palette palette.png

# Native resolution output
pag generate "a cat" --style rd_pro__default --upscale-output-factor 1

# Disable prompt expansion
pag generate "exactly this" --style rd_pro__default --bypass-prompt-expansion

All generate options:

Option	Description
`PROMPT`	Text description of the image (required)
`--style`	Style key, e.g. `rd_pro__default` (required). See `pag list-styles`
`--size WxH`	Image dimensions, e.g. `128x128`. Defaults to style minimum
`-n, --num-images`	Number of images to generate (default: 1)
`--seed`	Seed for generation
`--ref PATH`	Reference image file (repeatable, up to 9 for RD_PRO)
`--tile-x`	Enable horizontal seamless tiling
`--tile-y`	Enable vertical seamless tiling
`--remove-bg`	Remove image background
`--input-image PATH`	Input image for img2img transformation
`--strength FLOAT`	img2img strength, 0.0–1.0 (how much to modify the input)
`--input-palette PATH`	Palette reference image for color guidance
`--return-pre-palette`	Also return the image before palette application
`--bypass-prompt-expansion`	Disable automatic prompt expansion
`--upscale-output-factor INT`	Output scale factor (1 = native resolution)
`--include-downloadable-data`	Include downloadable data (e.g. sprite atlas JSON)
`--return-non-bg-removed`	Also return the image before background removal
`-o, --output`	Exact output file path
`-d, --output-dir`	Output directory (auto-names files)
`--name-pattern`	Custom filename template (see Filename patterns)
`--stdout`	Write base64 to stdout instead of saving files
`--open`	Open generated file(s) with system viewer (`xdg-open`)
`--api-key`	Override API key for this command

Verbose mode and spinner

All API calls show an animated spinner with elapsed time:

⠹ Generating... 3.2s
Generating... done (12.4s)

Use -v / --verbose (before the subcommand) to see full request and response payloads:

pag -v generate "a cat" --style rd_pro__default --size 128x128

This prints the JSON request body and response to stderr, with base64 fields truncated for readability.

`pag animate` — Generate animations

Generate animated sprites as GIF or PNG spritesheet. Supports both standard and advanced animation styles.

# Walking + idle animation (outputs GIF)
pag animate "walking knight" --style walking_and_idle

# As spritesheet (outputs PNG)
pag animate "walking knight" --style walking_and_idle --spritesheet

# VFX animation with custom size
pag animate "fire effect" --style vfx --size 48x48

# With transparent background
pag animate "walking knight" --style walking_and_idle --remove-bg

# Using a reference image
pag animate "walking knight" --style walking_and_idle --input-image knight.png

# Advanced animation — animate a starting frame (requires --input-image)
pag animate "slow walk" --style walking --input-image sprite.png --size 96x96 --frames-duration 8

# Advanced animation — attack sequence
pag animate "sword slash" --style attack --input-image warrior.png --frames-duration 6

You can use either the short name (walking_and_idle) or the full key (animation__walking_and_idle). For advanced animations, use the short name (walking) or full key (rd_advanced_animation__walking).

Standard animation styles:

Style	Size	Notes
`any_animation`	64x64 fixed	General purpose animations
`8_dir_rotation`	80x80 fixed	8-direction rotation
`four_angle_walking`	48x48 fixed	4-angle walk cycle
`walking_and_idle`	48x48 fixed	Walk + idle
`small_sprites`	32x32 fixed	Small animated sprites
`vfx`	24x24 → 96x96	Visual effects (square only)

Advanced animation styles (require --input-image):

Style	Size range	Description
`attack`	32x32 → 256x256	Character attack sequence
`crouch`	32x32 → 256x256	Character crouching
`custom_action`	32x32 → 256x256	Any custom action (describe in prompt)
`destroy`	32x32 → 256x256	Object destruction
`idle`	32x32 → 256x256	Character idle
`jump`	32x32 → 256x256	Character jump
`subtle_motion`	32x32 → 256x256	Environmental motion (rain, leaves)
`walking`	32x32 → 256x256	Character walking cycle

All animate options:

Option	Description
`PROMPT`	Text description (required)
`--style`	Animation style (required)
`--size WxH`	Override default size
`--spritesheet`	Output PNG spritesheet instead of GIF
`--remove-bg`	Remove background
`--input-image PATH`	Reference image (required for advanced animations)
`--frames-duration`	Number of frames: 4, 6, 8, 10, 12, or 16 (advanced only)
`-o, --output`	Exact output file path
`-d, --output-dir`	Output directory
`--name-pattern`	Custom filename template
`--stdout`	Write base64 to stdout
`--open`	Open generated file with system viewer (`xdg-open`)
`--api-key`	Override API key

`pag tileset` — Generate tilesets

Generate tileset pixel art for game maps.

# Simple tileset
pag tileset "stone floor" --style tileset --size 32x32

# Advanced tileset with inside/outside textures
pag tileset "grey stones" --style tileset_advanced --extra-prompt "green grass" --size 32x32

# Single tile texture
pag tileset "volcanic rock" --style single_tile --size 32x32

# Tile variation from an existing tile
pag tileset "add moss" --style tile_variation --input-image base_tile.png

# Large scene object
pag tileset "oak tree" --style scene_object --size 128x128

You can use the short name (tileset) or full key (rd_tile__tileset).

Available tileset styles:

Style	Size range	Description
`tileset`	16x16 → 32x32	Full wang-style tilesets
`tileset_advanced`	16x16 → 32x32	Two-texture tilesets (use `--extra-prompt`)
`single_tile`	16x16 → 64x64	Single tile textures
`tile_variation`	16x16 → 128x128	Variations of an existing tile
`tile_object`	16x16 → 96x96	Small objects for tiles
`scene_object`	64x64 → 384x384	Large scene objects

All tileset options:

Option	Description
`PROMPT`	Text description (required)
`--style`	Tileset style (required)
`--size WxH`	Tile size
`--extra-prompt`	Secondary prompt (for `tileset_advanced` outside texture)
`--input-image PATH`	Input/inspiration image
`--extra-input-image PATH`	Extra input image (for `tileset_advanced`)
`-o, --output`	Exact output file path
`-d, --output-dir`	Output directory
`--name-pattern`	Custom filename template
`--stdout`	Write base64 to stdout
`--open`	Open generated file with system viewer
`--api-key`	Override API key

`pag edit` — Edit pixel art

Edit an existing pixel art image using a text prompt.

# Add a hat to a character
pag edit "add a red hat" --input-image character.png -o character_hat.png

# Progressive editing — chain edits
pag edit "add wings" --input-image character_hat.png -o character_final.png

Supported image sizes: 16x16 to 256x256. Cost: 0.06 credits per edit.

All edit options:

Option	Description
`PROMPT`	Description of the edit (required)
`--input-image PATH`	Image to edit (required)
`-o, --output`	Output file path
`-d, --output-dir`	Output directory
`--name-pattern`	Custom filename template
`--stdout`	Write base64 to stdout
`--open`	Open generated file with system viewer
`--api-key`	Override API key

`pag cost` — Estimate credit cost

Check how many credits a generation would cost without actually generating images.

pag cost "a cool corgi" --style rd_pro__default --size 128x128
pag cost "tileset" --style rd_pro__dungeon_map -n 4

Options: PROMPT, --style, --size, -n, --api-key

`pag balance` — Check credit balance

pag balance

`pag list-styles` — Browse available styles

List all built-in styles with their size ranges.

# All styles
pag list-styles

# Filter by model
pag list-styles --model rd_pro
pag list-styles --model rd_fast
pag list-styles --model rd_plus
pag list-styles --model rd_tile
pag list-styles --model animation
pag list-styles --model rd_advanced_animation

`pag styles` — Manage custom styles

Create, update, and delete custom RD_PRO styles.

# Create a new custom style
pag styles create --name "my style" --description "A dark fantasy style" --ref reference.png --icon skull

# Update a style
pag styles update <style_id> --name "renamed style" --description "Updated description"

# Delete a style
pag styles delete <style_id>

# List built-in styles (same as pag list-styles)
pag styles list

styles create options:

Option	Description
`--name`	Style name (required)
`--description`	Style description
`--ref PATH`	Reference image file
`--icon`	Icon name (e.g. `skull`, `sparkles`, `fire`, `sword`)
`--api-key`	Override API key

Shell completions

Enable tab completion for all commands, options, and style names:

# Bash — add to ~/.bashrc
eval "$(pag completions bash)"

# Zsh — add to ~/.zshrc
eval "$(pag completions zsh)"

Filename patterns

Control how output files are named using --name-pattern with these placeholders:

Placeholder	Description
`{prompt_slug}`	First 48 chars of prompt, lowercased, special chars → `_`
`{prompt}`	Same as `{prompt_slug}`
`{style}`	Style key with `__` replaced by `_`
`{seed}`	Seed value, or `noseed` if not set
`{n}`	Image index (0-based)
`{timestamp}`	Unix timestamp

Examples:

# Custom pattern
pag generate "a cat" --style rd_pro__default --name-pattern "{prompt_slug}_{style}_{seed}"
# → a_cat_rd_pro_default_noseed.png

# Exact output path
pag generate "a cat" --style rd_pro__default -o my_cat.png
# → my_cat.png

# Output to directory with auto-naming
pag generate "a cat" --style rd_pro__default -d ./output/
# → ./output/a_cat_1700000000.png

# Multiple images get index suffix automatically
pag generate "gems" --style rd_pro__default -n 3 -d ./output/
# → ./output/gems_1700000000_0.png, gems_1700000000_1.png, gems_1700000000_2.png

Default pattern: {prompt_slug}_{timestamp}.png (single image) or {prompt_slug}_{timestamp}_{n}.png (multiple). Animations use .gif unless --spritesheet is set.

Available styles and size limits

Important: Each style has a minimum and maximum allowed size. Requests below the minimum or above the maximum will be rejected by the API.

RD_PRO — min 96x96, max 256x256

All RD_PRO styles share the same size range.

default, painterly, fantasy, ui_panel, horror, scifi, simple, isometric, topdown, platformer, dungeon_map, edit, pixelate, spritesheet, typography, hexagonal_tiles, fps_weapon, inventory_items

RD_FAST — varies by style

Style group	Styles	Min size	Max size
Default	`default`, `retro`, `simple`, `detailed`, `anime`, `game_asset`, `portrait`, `texture`, `ui`, `item_sheet`, `character_turnaround`, `1_bit`, `no_style`	64x64	384x384
Low res	`low_res`	16x16	128x128
Minecraft	`mc_item`, `mc_texture`	16x16	128x128

RD_PLUS — varies by style

Style group	Styles	Min size	Max size
Default	`default`, `retro`, `watercolor`, `textured`, `cartoon`, `ui_element`, `item_sheet`, `character_turnaround`, `environment`, `topdown_map`, `topdown_asset`, `isometric`, `isometric_asset`	64x64	384x384
Classic	`classic`	32x32	192x192
Low res	`low_res`	16x16	128x128
Minecraft	`mc_item`, `mc_texture`	16x16	128x128
Top-down item	`topdown_item`	16x16	128x128
Skill icon	`skill_icon`	16x16	128x128

RD_TILE — tileset styles

Style	Min size	Max size
`tileset`	16x16	32x32
`tileset_advanced`	16x16	32x32
`single_tile`	16x16	64x64
`tile_variation`	16x16	128x128
`tile_object`	16x16	96x96
`scene_object`	64x64	384x384

Standard animations — fixed or limited sizes

Style	Size	Notes
`any_animation`	64x64 fixed
`8_dir_rotation`	80x80 fixed
`four_angle_walking`	48x48 fixed	Other sizes are ignored
`walking_and_idle`	48x48 fixed
`small_sprites`	32x32 fixed
`vfx`	24x24 → 96x96	Must be square

Advanced animations — 32x32 to 256x256

All advanced animation styles require --input-image and support --frames-duration.

attack, crouch, custom_action, destroy, idle, jump, subtle_motion, walking

Development

Setup

git clone git@github.com:Ymx1ZQ/pag.git
cd pag
uv sync

Running tests

# Unit tests only (no API key needed)
uv run pytest tests/unit/ -v

# Live tests (requires RETRODIFFUSION_API_KEY)
uv run pytest tests/live/ -v

# All tests
uv run pytest -v

Live tests are automatically skipped when RETRODIFFUSION_API_KEY is not set.

Project structure

pag/
├── pyproject.toml          # Package metadata and dependencies
├── install.sh              # Global CLI installer
├── src/
│   └── pag/
│       ├── __init__.py     # Version
│       ├── __main__.py     # python -m pag entry point
│       ├── cli.py          # Click-based CLI (generate, animate, tileset, edit, cost, balance, styles)
│       ├── client.py       # Retro Diffusion API client (httpx)
│       ├── models.py       # Pydantic request/response models
│       ├── styles.py       # Style registry and validation
│       ├── config.py       # API key resolution
│       └── output.py       # Base64 decoding, file saving, filename resolution
├── tests/
│   ├── unit/               # 158 tests — mocked, no API calls
│   └── live/               # 10 tests — real API, need RETRODIFFUSION_API_KEY

Dependencies

Package	Purpose
`click`	CLI framework
`httpx`	HTTP client
`pydantic`	Input/output validation
`python-dotenv`	`.env` file loading

Dev: pytest, pytest-mock, respx

License

MIT

Name		Name	Last commit message	Last commit date
src/pag		src/pag
tests		tests
.env.example		.env.example
.gitignore		.gitignore
DEVPLAN.md		DEVPLAN.md
DEVPLAN_ARCHIVE.md		DEVPLAN_ARCHIVE.md
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

pag — Pixel Art Generator

Features

Requirements

Quickstart

Installation

Via install.sh (recommended)

One-liner from GitHub

Manual installation (from local clone)

Configuration

Usage

pag generate — Generate pixel art

Verbose mode and spinner

pag animate — Generate animations

pag tileset — Generate tilesets

pag edit — Edit pixel art

pag cost — Estimate credit cost

pag balance — Check credit balance

pag list-styles — Browse available styles

pag styles — Manage custom styles