Avatar Generator API - Documentation

📖 Overview

A high-performance JSON API that generates unique, deterministic SVG avatars based on a name input. Perfect for user profiles, comments, and any application needing consistent, personalized avatars.

🚀 Quick Start

Base URL

GET /avatars/api/generate-avatar

Example Request

GET /avatars/api/generate-avatar?name=John%20Doe&type=avatar&size=200

Parameters

Parameter	Type	Required	Default	Description
`name`	String	Optional	"User"	Name used to generate the avatar. Same name always produces the same avatar.
`type`	String	Optional	"avatar"	Avatar style. See available types below.
`size`	Integer	Optional	100	Size of the avatar in pixels (width and height).
`color`	String	Optional	Auto	Hex color code (e.g., #FF5733). If not provided, color is generated from name.

🎭 Avatar Types

All examples use the name "Alex Morgan" for consistency. Each type generates a unique, deterministic design.

avatar

Classic circular avatar with initials

type=avatar

gravatar

GitHub-style identicon

type=gravatar

dither

Retro dithered plasma effect

type=dither

ascii

Procedural ASCII robot

type=ascii

dotmatrix

LED dot matrix display

type=dotmatrix

terminal

Retro terminal block text

type=terminal

bauhaus

Geometric Bauhaus design

type=bauhaus

ring

Gradient ring pattern

type=ring

beam

Connected network nodes

type=beam

marble

Marble texture effect

type=marble

glitch

Cyberpunk glitch effect

type=glitch

sunset

Procedural sunset scene

type=sunset

smile

Minimalist face with expressions

type=smile

circuit

Circuit board pattern

type=circuit

pixel

Isometric pixel art cube

type=pixel

constellation

Real constellation star maps

type=constellation

💡 Usage Examples

HTML Image Tag

<img src="/avatars/api/generate-avatar?name=Jane%20Smith&type=avatar&size=100" alt="Avatar">

With Custom Color

<img src="/avatars/api/generate-avatar?name=John&type=gravatar&color=%23FF5733" alt="Avatar">

Large Size

<img src="/avatars/api/generate-avatar?name=Sarah&type=dotmatrix&size=500" alt="Avatar">

JavaScript Fetch

fetch('/avatars/api/generate-avatar?name=Bob%20Johnson&type=beam')
  .then(response => response.text())
  .then(svg => {
    document.getElementById('avatar').innerHTML = svg;
  });

⚡ Features

✅ Deterministic - Same name always generates the same avatar
✅ SVG Format - Scalable to any size without quality loss
✅ 16 Unique Styles - From classic to creative designs
✅ Fast & Lightweight - Generated on-the-fly, no storage needed
✅ CORS Enabled - Use from any domain
✅ Rate Limited - 100 requests per minute per IP
✅ Dark Mode Support - Responsive documentation

📝 Response Format

All avatars are returned as SVG (Scalable Vector Graphics) with the content type:

Content-Type: image/svg+xml; charset=utf-8

Status Codes

Code	Description
`200 OK`	Request successful, avatar returned
`400 Bad Request`	Invalid avatar type specified
`429 Too Many Requests`	Rate limit exceeded (100 req/min)
`500 Internal Server Error`	Server-side error occurred

🎨 Color Generation

When no color is specified, avatars use the OKLCH color space for perceptually uniform, accessible colors. The algorithm:

Generates a deterministic hash from the input name
Maps hash values to hue, chroma, and lightness
Ensures sufficient contrast for readability
Produces consistent colors across all sessions

🎨 Avatar Generator API