GET /avatar

Generate deterministic African-style silhouette profile pictures on the fly. No AI inference — all avatars are composed from layered SVG paths at request time. The same parameters always return the same image.

GET/v1/avatar

Returns an SVG or PNG silhouette avatar. Pass a seed tied to your user (e.g. their ID or email) to get a consistent avatar across requests.

PARAMETERS

Name	Type	Default	Description
gender	string	neutral	Silhouette gender variant. One of: male, female, neutral.
style	string	seeded	Hair style. One of: cornrows, gele, afro, dreadlocks, twa, fade, natural. Derived from seed when omitted.
width	int	200	Output width in pixels. Min 1, max 2000.
height	int	200	Output height in pixels. Min 1, max 2000.
bg	string	F5F5F5	Background colour - 6-character hex without #.
fg	string	333333	Silhouette colour - 6-character hex without #.
seed	string	random	Any string (e.g. user ID or email). Same seed always produces the same output. Auto-generated when omitted.
format	string	svg	Output format. One of: svg, png.

EXAMPLE REQUEST

GET /v1/avatar?seed=user_12345&gender=female&style=gele&width=200&height=200

EXAMPLE RESPONSE

HTTP/1.1 200 OK
Content-Type: image/svg+xml
Cache-Control: public, max-age=86400

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200">
  <!-- background, body, head, hair layers -->
</svg>

GET/v1/avatar?format=png

Rasterises the SVG silhouette to PNG.

EXAMPLE REQUEST

GET /v1/avatar?seed=user_12345&style=afro&format=png&width=400&height=400

EXAMPLE RESPONSE

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=86400

<binary PNG data>

Determinism: If you omit style, it is derived from your seed via a stable hash - same seed, same style, always. The seed itself is not included in the cache key, so different seeds that map to the same style share a cached response.