Ugly Avatars API & Documentation
A deterministic vector avatar for any seed, rendered on demand via <svg>. The same seed always yields the same avatar, with no stored images and no network
database. Self-contained: the engine is edge-native.
Quickstart
Embed generative avatars directly into HTML, React, or any framework using simple image tags.
<img src="https://avatars.reicon.dev/v1/svg/dev?size=400&shape=square" alt="Avatar" width="400" height="400" />
API Endpoints
Consume vector or rasterized avatars via HTTP GET requests on our global edge network (https://avatars.reicon.dev).
Parameters
Customize output shape, dimensions, and seed values via query parameters.
| Parameter | Type | Default | Description |
|---|---|---|---|
| seed | string | avatar |
Path parameter. Any string or ID used for 100% deterministic avatar generation. |
| shape | string | square |
Outer clipping mask. Options: square, circle, or squircle. |
| size / width / height | number | 500 |
Output resolution in pixels (e.g. 250, 400, 500). |
Rate Limits & Caching
Edge requests are rate limited to 100 requests per minute per IP.
Responses include rate limit diagnostic headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and immutable CDN caching (Cache-Control: public, max-age=31536000, immutable).
Shapes & Clipping Masks
Control outer geometry using the shape query parameter. Choose between circle, squircle, or square.
Seed Determinism
Pass any string, email, or user ID as a seed. The generator produces a 100% unique avatar with consistent palette, torso pattern, and expression every single time.
Formats (SVG, JSON)
Vector SVG images for web apps, or structured JSON payloads with raw SVG markup.
GET /v1/json/dev { "seed": "dev", "shape": "square", "size": 500, "svg": "<svg width=\"500\" height=\"500\" ...>...</svg>" }
License
MIT Licensed. Free for commercial and open-source use.