AvatarHub: Building a Free Avatar Placeholder API

Background

AvatarHub started as a fork of an existing project, transforming into a full-featured avatar placeholder API. The goal was simple: provide developers a free, no-registration-needed service for generating avatar images. No rate limits, no API keys—just instant access to 100+ built-in avatars or dynamic SVG generation.

The Challenge

The original project had limited functionality—just static avatars. The fork needed to support multiple use cases: gender-based selection (boy/girl), job-specific avatars, dynamic SVG generation from names, and batch API access. Key technical hurdles included SVG-to-image conversion, supporting multiple formats (PNG, JPG, WebP), and ensuring CDN-ready cache headers.

The most interesting challenge was building the pixel art avatar generator—which uses golden ratio proportions to create procedurally-generated cartoon faces with randomized features (skin tone, hair, glasses, beards, earrings).

The Solution

Built on Express.js with TypeScript for type safety. The architecture separates concerns:

• publicController: Serves static avatars and handles gender/job routing
• username route: SVG generator from initials with 8 color themes
• pixel route: Procedural pixel art with 10 shapes, 16 skin tones, 16 hair colors

The pixel art generator uses the golden ratio (φ ≈ 1.618) to calculate face proportions, creating natural-looking cartoon characters. It applies seeded random generation—so the same username always produces the same avatar.

Technical Deep Dive

SVG Generation

The SVG generator (publicController/svgAvatar):

• Parses full name → extracts initials
• Applies themes or custom hex colors
• Renders via svg2img with Roboto fonts
• Returns with ETag + Cache-Control headers

Pixel Art Engine

The pixel art engine (publicController/pixelAvatar):

• Grid-based rendering with configurable pixel size
• Golden ratio for face feature placement
• Shape masks: circle, square, hexagon, diamond, heart, star, rounded, triangle, octagon, pentagon
• Randomization with optional seed (username hashing)
• Features: glasses, beard, earring (40-50% probability using inverse φ)

API Features

• Batch avatar URLs: /api/avatars?ids=1,5,25
• Job categories: police, doctor, designer, chef, etc.
• Tag-based filtering: /api/tags/:tag
• Swagger docs at /api-docs/

Results & Impact

• 100+ built-in avatars across boy/girl/job categories
• 8 color themes: Ocean, Forest, Fire, Sky, Sunset, Purple, Mint, Coral
• 3 output shapes + 10 pixel art shapes
• Multi-format: PNG, JPG, WebP
• Production-ready: Vercel deployment, PM2 for Node.js hosting, Docker support
• Developer-friendly: No auth required, comprehensive Swagger docs, React/JS/HTML examples

Key Takeaways

1. Fork wisely: Starting from an existing project gave head start, but full TypeScript rewrite improved maintainability
2. Seed everything: Username seeding ensures consistent avatars—same name always produces same face
3. Golden ratio works: Using φ for facial proportions creates naturally-balanced pixel art
4. Cache aggressively: Immutable cache headers + ETags enable CDN deployment
5. No friction: The no-registration, no-rate-limit model removes barriers for developers