Docs

Avatars are deterministic by path. Same path and same query options always produce the same image. Responses are cached and include long-lived cache headers.

Quick start

The easiest way to add Star Avatars is to ask your coding agent:

Can you add staravatars.com to my project?

URL format

GET /{seed}?{query-params}

Examples

• /[email protected]?size=128&text=vb&shape=circle&palette=sunset
• /[email protected]?t=v&p=sunset
• /my-project?size=96&shape=rounded&format=png

Embedding

Hotlinking is permitted. Use a standard image tag:

<img src="https://staravatars.onfizz.dev/[email protected]?size=64&shape=circle" alt="" />

See Terms and Acceptable use for rate limits and production integration guidance.

Favicons

Complex SVG avatars often fail as favicons in Chromium and Firefox. Prefer format=png so the icon and initials render reliably everywhere (the text is baked into the pixels):

<link rel="icon" type="image/png" href="https://staravatars.onfizz.dev/[email protected]?size=32&shape=rounded&text=vb&format=png" />

Query parameters

size

Avatar size in px (16–1024). Default: 64.

initials (aliases: i, text, t)

Up to two characters shown on the avatar.

shape (aliases: s, style)

square (default), circle, or rounded.

palette (aliases: p, vibe)

sunset, ocean, daybreak, bubble, forest, fire, crystal, ice, stealth.

format

svg (default) or png.

animated

SVG only. Set to 0 to omit the star twinkle animation. Recommended when a page shows many avatars, since every animated avatar costs continuous client CPU. Animated avatars also honor the viewer's reduced-motion preference.

circular

Legacy boolean; maps to circle or square.