api reference
No SDK, no auth, public CORS. All endpoints return cacheable image content with 1-year immutable headers (HTML pages cache 5 min).
GET /avatar/:seed[.svg|.png]
Returns a deterministic mascot avatar for the given seed. Same seed → same avatar, byte-for-byte. Append .png to the seed to receive a rasterized PNG instead of SVG.
path
- :seed
- string
- Any unique identifier. Use a stable user id, UUID, or email. Avoid display names — collisions cause duplicate avatars.
query
- size
- number
- Output size in px. Default 96. Range 16–1024.
- palette
- enum
- Force a color family. indigo · mint · amber · sky · violet · cyan · rose · lime · peach · teal · sand · plum · coral · forest · slate · fuchsia · terracotta · navy · lavender · charcoal · butter · aqua
- background
- enum
- Scene fill.
none · solid · ring. Default = seed-derived.
- tileBg
- color
- Opaque circular tile behind avatar. Any CSS color, e.g.
%23ffffff (URL-encoded #fff), or auto to use the palette accent.
- title
- string
- Accessible label. Adds
role="img" + aria-label.
- animated
- 0 | 1
- Opt-in idle motion (float, blink, sway, twinkle). SVG only; PNG ignores. Respects
prefers-reduced-motion.
examples
basic
GET https://navii-api.uxderrick.com/avatar/alice
animated
GET https://navii-api.uxderrick.com/avatar/alice?animated=1
palette: violet
GET https://navii-api.uxderrick.com/avatar/alice?palette=violet
filled tile (white)
GET https://navii-api.uxderrick.com/avatar/alice?tileBg=%23ffffff
dark tile
GET https://navii-api.uxderrick.com/avatar/alice?tileBg=%230b0b0c
with ring bg
GET https://navii-api.uxderrick.com/avatar/alice?background=ring
PNG raster
GET https://navii-api.uxderrick.com/avatar/alice.png?size=256
big PNG
GET https://navii-api.uxderrick.com/avatar/alice.png?size=512&tileBg=auto
GET /group
Renders multiple seeded avatars as a single horizontally-stacked SVG with optional overlap and a +N counter tile for overflow.
query
- seeds
- csv
- Comma-separated list of seeds. Up to 50.
- size
- number
- Per-tile size in px. Default 64. Range 16–256.
- overlap
- number
- Fraction each tile overlaps the previous. 0 = no overlap, 0.7 = heavy stack. Default 0.3.
- max
- number
- Max tiles to render. Extra seeds collapse into a
+N tile. Default = all.
- ring
- color
- Border color around each tile. Default white.
- tileBg
- color
- Opaque fill behind each avatar (prevents overlap show-through). Default white.
- animated
- 0 | 1
- Per-avatar animation in the group.
examples
basic
GET https://navii-api.uxderrick.com/group?seeds=alice,bob,carol
overlap
GET https://navii-api.uxderrick.com/group?seeds=alice,bob,carol,dave,eve&size=64&overlap=0.45
with +N
GET https://navii-api.uxderrick.com/group?seeds=alice,bob,carol,dave,eve,frank,grace&size=56&max=4
animated
GET https://navii-api.uxderrick.com/group?seeds=alice,bob,carol,dave&size=72&animated=1
GET /gallery
Visual debug page — N seeded avatars in a grid. For browsing the cast, not for production embedding.
query
- count
- number
- How many tiles (1–500). Default 96.
- size
- number
- Per-tile size. Default 96.
- prefix
- string
- Seed prefix. Default
user, so seeds become user-0, user-1, …
- animated
- 0 | 1
- Animate each tile.
GET /healthz
Liveness probe. Returns {"ok":true,"pngCacheSize":N}.
GET /api
Service metadata as JSON. Useful for clients that want to discover the endpoint surface programmatically.
headers
All image responses set:
- cache-control
public, max-age=31536000, immutable — safe to cache forever (seed + params fully determine the bytes).- access-control-allow-origin
* — embed anywhere.- content-type
image/svg+xml; charset=utf-8 for SVG, image/png for PNG.
rate limits
Per-IP sliding window: 600 requests / minute on /avatar/*. Exceeds → HTTP 429 + Retry-After header. /group, /gallery, /healthz are unlimited.
determinism guarantee
Same seed + same query params → byte-identical response. Forever. Safe to cache, safe to mirror, safe to depend on.
