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

/user@example.com?size=128&text=vb&shape=circle&palette=sunset
/hello@vblinden.dev?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.com/user@example.com?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.com/user@example.com?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.
text-size (alias: ts): Initials size relative to the avatar: xs, sm, md, lg, xl, 2xl, xxl, 3xl, 4xl. Default: md. Use 2xl–4xl for tiny favicons.
shape (aliases: s, style): square (default), circle, or rounded.
palette (aliases: p, vibe): sunset, ocean, daybreak, bubble, forest, fire, crystal, ice, stealth, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.
format: svg (default) or png.
animated: Legacy. Accepted but ignored. Stars are a still field — some bright, some dim — with no twinkle animation.
circular: Legacy boolean; maps to circle or square.