Avatar Placeholder API

Q: How do I get the same avatar for the same user?

Pass a stable seed (e.g. the username) to the image route — the same seed always renders the same avatar, so a user keeps their identicon across sessions.

Q: Which avatar styles are available?

style accepts identicon (symmetric pixel pattern), initials (letters drawn from name) and shapes (geometric composition); the image route defaults to identicon.

Q: Can I control size and shape?

size sets the pixel dimensions, bg overrides the background and rounded=true switches to a rounded-corner tile (radius = 20% of size).

MOCK DATA

Deterministic SVG avatars from any seed string — identicons, initials and abstract shapes. Same seed, same avatar forever; plus ready-to-use avatar URL batches.

Generated test data for fixtures and development

Base URL: /api/avatars
Category: Design & Media
Capabilities: 2 routes Seedable
Last updated: July 29, 2026

GET /api/avatars/image Render a deterministic SVG avatar for a seed Returns an image (SVG)

Returns the image itself (image/svg+xml), not JSON. The seed is the identity: equal seeds render byte-identical SVGs, so the URL is safe to store and hotlink.

Live requestRuns against the public API

No key required

GET/api/avatars/image?seed=user-42

Request parameters

styledefault identicon

Artwork: 'identicon' = mirrored 5×5 pixel grid, 'initials' = lettered tile, 'shapes' = 2–3 overlapping abstract shapes.

seeddefault random-user

Identity key — the same seed always renders the exact same avatar, so use a user ID, email or username. Max 64 characters.

name

Initials source for style=initials: first letters of the first two words, uppercased ('Jane Doe' → JD). Without it the seed's first two characters are used. Ignored by the other styles.

sizedefault 128

Rendered width/height in pixels (also the viewBox). The artwork is identical at every size — SVG scales losslessly.

roundeddefault true

Rounded-square tile (corner radius = 20% of size). Set false for sharp corners (rx="0").

bg

Background as a 6-digit hex color, with or without '#' (e.g. 1e293b) — anything else is a 400. Defaults to a pastel derived from the seed, stable across styles.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 6 params · 0 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

HTML curl JavaScript Python

<img src="https://randomapi.dev/api/avatars/image?seed=user-42" alt="Generated image" />

curl -o image.svg "https://randomapi.dev/api/avatars/image?seed=user-42"

const res = await fetch("https://randomapi.dev/api/avatars/image?seed=user-42");
const svg = await res.text();

import requests

svg = requests.get("https://randomapi.dev/api/avatars/image?seed=user-42").text

Parameters Route-specific request inputs 6

Parameter	Type	Default & allowed	Description
`style`	enum	default: identicon allowed: identicon \| initials \| shapes example: initials	Artwork: 'identicon' = mirrored 5×5 pixel grid, 'initials' = lettered tile, 'shapes' = 2–3 overlapping abstract shapes.
`seed`	string	default: random-user allowed: ≤ 64 example: user-42	Identity key — the same seed always renders the exact same avatar, so use a user ID, email or username. Max 64 characters.
`name`	string	allowed: ≤ 60 example: Jane Doe	Initials source for style=initials: first letters of the first two words, uppercased ('Jane Doe' → JD). Without it the seed's first two characters are used. Ignored by the other styles.
`size`	int	default: 128 allowed: 16 – 512 example: 256	Rendered width/height in pixels (also the viewBox). The artwork is identical at every size — SVG scales losslessly.
`rounded`	boolean	default: true example: false	Rounded-square tile (corner radius = 20% of size). Set false for sharp corners (rx="0").
`bg`	string	example: ffadad	Background as a 6-digit hex color, with or without '#' (e.g. 1e293b) — anything else is a 400. Defaults to a pastel derived from the seed, stable across styles.

style enum

Artwork: 'identicon' = mirrored 5×5 pixel grid, 'initials' = lettered tile, 'shapes' = 2–3 overlapping abstract shapes.

default: identicon

allowed: identicon | initials | shapes

example: style=initials

seed string

Identity key — the same seed always renders the exact same avatar, so use a user ID, email or username. Max 64 characters.

default: random-user

allowed: ≤ 64

example: seed=user-42

name string

Initials source for style=initials: first letters of the first two words, uppercased ('Jane Doe' → JD). Without it the seed's first two characters are used. Ignored by the other styles.

allowed: ≤ 60

example: name=Jane Doe

size int

Rendered width/height in pixels (also the viewBox). The artwork is identical at every size — SVG scales losslessly.

default: 128

allowed: 16 – 512

example: size=256

rounded boolean

Rounded-square tile (corner radius = 20% of size). Set false for sharp corners (rx="0").

default: true

example: rounded=false

bg string

Background as a 6-digit hex color, with or without '#' (e.g. 1e293b) — anything else is a 400. Defaults to a pastel derived from the seed, stable across styles.

example: bg=ffadad

Documented examples

Build-generated requests and complete responses 3

Identicon for a user ID /api/avatars/image?seed=user-42

Initials avatar for Jane Doe /api/avatars/image?style=initials&name=Jane%20Doe&seed=jane-doe&size=256

GET /api/avatars/image?style=initials&name=Jane%20Doe&seed=jane-doe&size=256

Abstract shapes, sharp corners, navy background /api/avatars/image?style=shapes&seed=acme-prod&bg=1e293b&rounded=false&size=64

GET /api/avatars Generate ready-to-use avatar image URLs Returns a list

Generates avatar URLs pointing at /api/avatars/image, each with a readable adjective-noun-NN seed. Pin the platform ?seed=<int> to get the same batch every time.

Live requestRuns against the public API

No key required

GET/api/avatars

Request parameters

style

Bake one style into every generated URL. Omit for a random mix of all three.

sizedefault 128

Pixel size baked into every generated URL's `size` parameter.

Advanced response options7 options

countdefault 10

How many records to generate (1–100).

seed

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 9 params · 3 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/avatars"

const res = await fetch("https://randomapi.dev/api/avatars");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/avatars").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/avatars"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 2

Parameter	Type	Default & allowed	Description
`style`	enum	allowed: identicon \| initials \| shapes example: identicon	Bake one style into every generated URL. Omit for a random mix of all three.
`size`	int	default: 128 allowed: 16 – 512 example: 256	Pixel size baked into every generated URL's `size` parameter.

style enum

Bake one style into every generated URL. Omit for a random mix of all three.

allowed: identicon | initials | shapes

example: style=identicon

size int

Pixel size baked into every generated URL's `size` parameter.

default: 128

allowed: 16 – 512

example: size=256

Universal parameters Shared response and formatting options 7

Parameter	Type	Default & allowed	Description
`count`	int	default: 10 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`fields`	list	example: url,style	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: seed	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

How many records to generate (1–100).

default: 10

allowed: 1 – 100

example: count=3

seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=url,style

exclude list

Return all fields except these (comma-separated).

example: exclude=seed

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 3

Field	Type	Description	Example
`url`	string (URL)	Absolute, ready-to-hotlink image URL on this platform — deterministic, so it is safe to store.	https://randomapi.dev/api/avatars/image?style=identicon&seed=brave-falcon-42&size=128
`style`	string	Avatar style baked into the URL: identicon \| initials \| shapes.	identicon
`seed`	string	The generated human-readable identity key (adjective-noun-number).	brave-falcon-42

url string (URL)

Absolute, ready-to-hotlink image URL on this platform — deterministic, so it is safe to store.

example: https://randomapi.dev/api/avatars/image?style=identicon&seed=brave-falcon-42&size=128

style string

Avatar style baked into the URL: identicon | initials | shapes.

example: identicon

seed string

The generated human-readable identity key (adjective-noun-number).

example: brave-falcon-42

Documented examples

Build-generated requests and complete responses 3

Ten avatar URLs, mixed styles /api/avatars

GET /api/avatars

{
  "data": [
    {
      "url": "https://randomapi.dev/api/avatars/image?style=initials&seed=nimble-moose-38&size=128",
      "style": "initials",
      "seed": "nimble-moose-38"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=amber-koala-57&size=128",
      "style": "identicon",
      "seed": "amber-koala-57"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=shapes&seed=cheerful-glacier-51&size=128",
      "style": "shapes",
      "seed": "cheerful-glacier-51"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=loyal-bison-25&size=128",
      "style": "identicon",
      "seed": "loyal-bison-25"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=shapes&seed=plucky-kestrel-32&size=128",
      "style": "shapes",
      "seed": "plucky-kestrel-32"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=graceful-hawk-35&size=128",
      "style": "identicon",
      "seed": "graceful-hawk-35"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=golden-narwhal-77&size=128",
      "style": "identicon",
      "seed": "golden-narwhal-77"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=shapes&seed=keen-lantern-91&size=128",
      "style": "shapes",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Reproducible identicon batch /api/avatars?style=identicon&count=5&seed=7

GET /api/avatars?style=identicon&count=5&seed=7

{
  "data": [
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=nimble-river-60&size=128",
      "style": "identicon",
      "seed": "nimble-river-60"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=lively-moose-40&size=128",
      "style": "identicon",
      "seed": "lively-moose-40"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=hardy-penguin-67&size=128",
      "style": "identicon",
      "seed": "hardy-penguin-67"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=quiet-fjord-57&size=128",
      "style": "identicon",
      "seed": "quiet-fjord-57"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=snappy-finch-48&size=128",
      "style": "identicon",
      "seed": "snappy-finch-48"
    }
  ],
  "meta": {
    "endpoint": "avatars",
    "count": 5,
    "seed": 7,
    "params": {
      "style": "identicon",
      "size": 128
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Large avatars, URLs only /api/avatars?size=256&fields=url&count=3

GET /api/avatars?size=256&fields=url&count=3

{
  "data": [
    {
      "url": "https://randomapi.dev/api/avatars/image?style=initials&seed=nimble-moose-38&size=256"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=identicon&seed=amber-koala-57&size=256"
    },
    {
      "url": "https://randomapi.dev/api/avatars/image?style=shapes&seed=cheerful-glacier-51&size=256"
    }
  ],
  "meta": {
    "endpoint": "avatars",
    "count": 3,
    "seed": 42,
    "params": {
      "size": 256
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Profile pictures without storing profile pictures. /api/avatars/image renders an SVG avatar fully determined by the seed string: the same seed returns the byte-identical image today and in ten years, so you can hotlink avatars for user IDs, emails or API keys with zero storage. Images are served with long cache headers and scale losslessly (size only sets the rendered dimensions — the artwork is identical at every size).

Three styles, all computed from a hash of the seed (never from the clock or a random number generator):

identicon — a horizontally mirrored 5×5 pixel grid in a hash-picked color that always contrasts with the background.
initials — up to two centered letters: the first letters of the first two words of name (Jane Doe → JD), falling back to the seed's first two characters. Text renders black or white depending on background luminance.
shapes — 2–3 overlapping translucent circles and rounded rectangles in hash-derived hues.

The background defaults to a pastel derived from the seed (stable across styles and sizes) or can be pinned with bg=<6-digit hex>; rounded toggles the 20% corner radius (rx="0" when false).

The root route /api/avatars generates batches of ready-to-use avatar URLs with human-readable seeds like brave-falcon-42 — handy when every fixture row just needs a working avatar link.

Use it for

Stable default profile pictures keyed by user ID or email — no image storage, no upload flow
Visual fingerprints that make API keys, commits or devices recognizable at a glance (identicons)
Seed databases and mockups with distinct, ready-to-hotlink avatar URLs in one call

Frequently asked questions

Practical answers about this endpoint 4

How do I get the same avatar for the same user?

Pass a stable seed (e.g. the username) to the image route — the same seed always renders the same avatar, so a user keeps their identicon across sessions.

Which avatar styles are available?

style accepts identicon (symmetric pixel pattern), initials (letters drawn from name) and shapes (geometric composition); the image route defaults to identicon.

Can I use the image URL directly in an img tag?

Yes — the image route returns cacheable SVG, so hot-linking it as an img src is the intended use.

Can I control size and shape?

size sets the pixel dimensions, bg overrides the background and rounded=true switches to a rounded-corner tile (radius = 20% of size).

Useful next tools in the catalog

Random User Data API MOCK DATA

Complete fake people — name, age-consistent birth date, email, phone, job and address — with working filters for gender, age range and email domain.

Placeholder Image API MOCK DATA

Hotlinkable SVG placeholder images at any size from 8 to 4000 px — custom label, colors and an optional gradient. Deterministic and crisp at every scale.

Random Username Generator API MOCK DATA

Random usernames in four distinct styles — handle, gamer, professional, anonymous — with a maxLength that is honored by construction, never by truncation.

Random Color API MOCK DATA

Random colors in hex, RGB and HSL with hue and luminosity filters, nearest CSS color names and WCAG contrast text — plus deterministic color-scheme palettes.

GET /api/avatars/image Render a deterministic SVG avatar for a seed Returns an image (SVG)

Request parameters

Response

Route reference

Documented examples

GET /api/avatars Generate ready-to-use avatar image URLs Returns a list

Request parameters

Response

Route reference

Documented examples

About this API

Coverage & behavior

Use it for

Frequently asked questions

Related APIs