DocsAPI reference

Avatar API

Public, no-auth, deterministic SVG avatars rendered server-side from any seed.

The Avatar API is a tiny no-auth endpoint that returns a deterministic SVG avatar for any seed. Same seed + style → byte-identical SVG, forever.

It exists so seedkit-generated data can carry stable, self-hosted avatar URLs that don't depend on third-party image services. You can also use it directly in your own apps — there's no quota.

Base URL

https://app.seedkit.dev/api/avatars/<seed>

<seed> is any URL-safe string up to 128 chars. Use a stable identifier like a user id or slug.

Quick example

<img src="https://app.seedkit.dev/api/avatars/sarah-chen" />
<img src="https://app.seedkit.dev/api/avatars/sarah-chen?style=bottts" />

Styles

Style	Looks like
`avataaars` (default)	Cartoon faces — varied skin/hair/clothing.
`initials`	Letter monogram on a colored circle.
`shapes`	Abstract geometric composition.
`bottts`	Friendly robots.
`lorelei`	Soft hand-drawn portraits.
`fun-emoji`	Emoji-style faces.
`notionists`	Notion-style line illustrations.
`thumbs`	Thumbs-up hand variants.

The renderer is @dicebear/core running server-side — we host so your seed data isn't pinned to a third-party domain.

Response

HTTP/1.1 200 OK
Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=31536000, immutable

The 1-year immutable cache means the first request to any seed warms the CDN; subsequent hits are essentially free. Safe to embed in millions of <img> tags without hammering origin.

Determinism

Same seed + same style always produces the exact same SVG bytes. This is the property that makes it safe to bake the URL into seeded database rows: the avatar your test fixture saw on day 1 is the same avatar your test fixture sees on day 1000.

Errors

HTTP	`error`	When
`400`	`invalid_seed`	Empty or > 128 chars.
`400`	`invalid_style`	Not one of the supported styles. Response includes `supported`.

CORS

Access-Control-Allow-Origin: *. You can fetch directly from any origin without preflight.