Getting Started with DiceBear Avatars — Dicebear Avatars

When to use this API

When you need to generate a consistent, style-rich avatar for a username, user ID, or any string identifier without uploading anything or maintaining state. DiceBear's key property is determinism: the same seed parameter always produces the same avatar, making the URL itself a stable identity. It supports 28+ visual styles from pixel-art characters to geometric abstractions. Use it for default profile images, bot avatars, or any "give this account a face" task. For uploaded photos or real user imagery, this is the wrong tool.

Getting avatar properties as structured data

"What does a pixel-art avatar look like — what fields does it contain?" The /{style}/json endpoint returns the avatar's SVG and all its rolled visual properties as a flat JSON object — no image parsing required.

curl "https://api.dicebear.com/9.x/pixel-art/json" | head -c 10000

{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\" ...>...</svg>",
  "extra": {
    "backgroundType": "solid",
    "accessories": "variant03",
    "clothing": "variant07",
    "eyes": "variant08",
    "mouth": "happy02",
    "hair": "long10",
    "accessoriesColor": "#daa520",
    "clothingColor": "#44c585",
    "hairColor": "#91cb15",
    "skinColor": "#b68655",
    "mouthColor": "#de0f0d"
  }
}

The extra object is where you work. The svg key holds the full SVG string — several kilobytes of path data — which you do not need to read to describe the avatar in text. Without a seed parameter, DiceBear uses a fixed internal default and returns the same avatar on every call (all five of our probes returned identical output). Add ?seed=someusername to produce a deterministic avatar tied to that identifier. The color assignments — lime #91cb15 for hair, mint #44c585 for clothing, gold #daa520 for accessories — come from DiceBear's palette system, which deliberately picks high-contrast, saturated values so avatars remain visually distinct from each other at small sizes.

This pixel-art avatar has long hair in lime green, variant07 clothing in mint, a happy02 mouth in red, and warm brown skin. Add ?seed=username to pin this style to a specific user — same seed always returns the same result.

Generating a persistent avatar image URL

"Give me a stable avatar image for the bot user indigofalcon." The /{style}/{format} endpoint returns binary image data directly — SVG, PNG, JPG, WebP, or AVIF. Construct the URL and return it; the caller embeds it in an <img> tag or Markdown image link.

https://api.dicebear.com/9.x/pixel-art/svg?seed=indigofalcon

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" shape-rendering="crispEdges">
  <metadata><!-- DiceBear pixel-art, CC0 1.0 license --></metadata>
  <mask id="viewboxMask">
    <rect width="16" height="16" rx="0" ry="0" x="0" y="0" fill="#fff" />
  </mask>
  <g mask="url(#viewboxMask)"><!-- deterministic pixel-art paths --></g>
</svg>

The response carries Cache-Control: public, max-age=31919000 — just under one year — so DiceBear's CDN serves repeated requests at essentially zero cost. Do not call this endpoint in agent code expecting to parse the result; construct the URL string and return it. Append &size=64 to set output dimensions in pixels. Add &radius=50 for a circular crop.

Here's a stable pixel-art avatar for indigofalcon: https://api.dicebear.com/9.x/pixel-art/svg?seed=indigofalcon — embed it as an <img> src or in Markdown as ![indigofalcon](https://api.dicebear.com/9.x/pixel-art/svg?seed=indigofalcon). The avatar is deterministic and will always look the same for this seed.

Pitfalls

Boolean parameters require lowercase true/false. Sending flip=True (Python-style) returns a 400 with "querystring/flip must be boolean". The API validates against JSON booleans, not string representations. Every probe we ran with flip=True failed.
Omitting seed gives a fixed default, not a random one. Every seedless call returns the same avatar. Always pass a seed in production — a username, user ID, or any stable unique string works.
The svg key in the JSON response is the full SVG markup. It runs 2–5 KB of path data. If you only need to describe the avatar in text, read extra and ignore svg entirely.

One-line summary for the user

I can generate a deterministic pixel-art (or any of 28+ other styles) avatar image URL for any username or ID via DiceBear — no auth required, no state, and the same seed always produces the same avatar.