Avatar Builder

An open, extensible avatar builder that composes SVG parts into complete avatars. It includes:

• a zero-dependency Python rendering engine;
• a responsive browser-based builder;
• SVG and 1024px PNG export;
• a public JSON-to-SVG API;
• thousands of bundled hair, face, clothing, and accessory parts;
• more than 16.8 sextillion component combinations before skin color;
• validation that hides enum entries whose SVG assets are missing;
• tests, CI, contributor guidance, and Vercel deployment configuration.

Live demo

Open the production avatar builder.

Quick start

Requirements: Python 3.12 or newer.

git clone https://github.com/aakashkakkar/avatar-builder.git
cd avatar-builder
python3 dev_server.py

Open http://127.0.0.1:8765.

No package installation is needed for local development.

Project structure

.
├── api/avatar.py              # Vercel Function: catalog + SVG renderer
├── avatar/                    # Python renderer, enums, and SVG part library
├── avatar_app/                # Catalog discovery and payload validation
├── src/
│   ├── components/            # Browser UI components
│   ├── api.js                 # API client
│   ├── app.js                 # Builder state and event orchestration
│   └── downloads.js           # SVG and PNG exporters
├── tests/                     # Renderer and catalog tests
├── scripts/check_assets.py    # SVG catalog integrity check
├── index.html                 # Application shell
├── styles.css                 # Responsive visual system
└── dev_server.py              # Local static/API development server

See Architecture for the full request and rendering flow.

API

Get the catalog

curl https://avatar-builder-rust.vercel.app/api/avatar

The response contains options, defaults, counts, and a catalog schema version.

Render an SVG

curl https://avatar-builder-rust.vercel.app/api/avatar \
  -X POST \
  -H 'Content-Type: application/json' \
  --data '{
    "style": "MALE_CUSTOM_STYLE_5",
    "top_kind": "hair",
    "top": "MALE_CUSTOM_HAIR_187",
    "clothing": "MALE_CUSTOM_CLOTH_63",
    "facial_hair": "",
    "eyes": "MALE_DEFAULT_EYE_2",
    "eyebrows": "MALE_CUSTOM_EYEBROWS_37",
    "mouth": "MALE_CUSTOM_MOUTH_63",
    "nose": "MALE_DEFAULT_NOSE_2",
    "accessory": "",
    "necklace": "",
    "skin_color": "#EDC092"
  }'

Successful requests return image/svg+xml. Invalid input returns JSON with an error field and HTTP 400.

See API reference for the complete payload contract.

Add new avatar parts

Each category consists of:

1. an SVG in the category’s directory under avatar/avatar_parts;
2. a value in the matching enum under avatar/enums.

The catalog only exposes a part when both are present. See Adding parts for SVG requirements, naming conventions, and checks.

Validation

python3 -m unittest discover -s tests
python3 scripts/check_assets.py
python3 -m compileall -q avatar avatar_app api

GitHub Actions runs these checks for every push and pull request.

Deploy

The repository is ready for Vercel’s Python runtime:

npx vercel link
npx vercel --prod

The static frontend is served from the repository root and api/avatar.py is deployed as a Python Function. The bundled SVG catalog is explicitly included in the function bundle.

See Deployment notes for verification and rollback instructions.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, then review the Code of Conduct.

License and attribution

The project is available under the MIT License. The renderer is derived from the MIT-licensed python-avatars project. Avatar artwork is based on designs by Pablo Stanley, with additional project-specific SVG parts. See THIRD_PARTY_NOTICES.md.