Placeholder Avatar API

Live examples

Every image below is served live by the endpoint documented on this page.

200roundedsquareBPgriddotsdiagonalcheckerid 237grayblur 4colors

Quick start

Drop the URL straight into an image tag. Sizes are in pixels and the default shape is a circle, so no extra styling is needed.

<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="Alice" width="200" height="200">

Or use it as a CSS background:

.avatar {
  width: 96px;
  height: 96px;
  border-radius: 50%;
  background-image: url("https://blankpfp.com/api/avatar/seed/alice/96");
  background-size: cover;
}

In JavaScript, build the URL from whatever identifies the user:

avatar.src = 'https://blankpfp.com/api/avatar/seed/' + encodeURIComponent(user.email) + '/200';

URL syntax

All four forms accept an optional height. Append .json to any of them to get the metadata described below instead of the image.

Deterministic seeds

A seed is hashed into one colour from a 48-entry palette, so the same seed always returns the same avatar with no database and nothing stored on disk. Use a username, an email address or a record id. Seeds containing spaces or symbols must be percent-encoded, and /api/avatar/id/ is a shortcut for numeric ids.

<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="alice">\n<img src="https://blankpfp.com/api/avatar/seed/bob/200" alt="bob">\n<img src="https://blankpfp.com/api/avatar/id/237/200" alt="record 237">

Query parameters

All parameters are optional and can be combined. An unrecognised value returns a 400 with a JSON explanation rather than a broken image.

Hex colours may be written with or without the leading hash, and three-digit shorthand such as #abc is expanded. Without bg the background comes from the seed; without fg the ink is picked automatically to stay readable. A blur above the maximum is capped rather than rejected, and initials never exceed two characters.

Silhouettes

The same fifteen bust silhouettes as the generator, addressable by id or by name. fg paints the silhouette and bg the backdrop, so one id looks different on every palette.

Solid fill

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Hollow outline (outline=1)

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Try it

Pick any avatar on this page, then change the parameters below. The preview and the code update as you go, and what you copy is exactly what the endpoint returns.

Preview

Shape circle rounded square Pattern solid grid dots diagonal checker Initials

Background auto

Foreground auto

Blur

0

Outline Grayscale

Reset

URL

Response formats

Images are returned as SVG, which keeps a typical avatar between 200 and 1000 bytes and stays sharp at any pixel density. Append .json to the same URL to read the resolved colours instead, which is handy for matching surrounding UI to the avatar.

{
  "ok": true,
  "mode": "seed",
  "seed": "alice",
  "width": 200,
  "height": 200,
  "shape": "circle",
  "pattern": "solid",
  "figure": null,
  "background": "#9CA3AF",
  "foreground": "#111827",
  "initials": null,
  "outline": false,
  "grayscale": false,
  "blur": 0,
  "format": "svg",
  "bytes": 266,
  "url": "https://blankpfp.com/api/avatar/seed/alice/200/200.svg",
  "info": "https://blankpfp.com/api/avatar/seed/alice/200/200.json"
}

Invalid requests answer with a 400 and a JSON body:

{
  "ok": false,
  "error": "invalid_parameters",
  "errors": ["pattern: expected one of solid, grid, dots, diagonal, checker"],
  "docs": "https://blankpfp.com/docs"
}

Caching and limits

Seeded URLs are a pure function of the address, so they are served with a one-year immutable cache header and an ETag. Put a CDN in front of your app and the images cost you nothing after the first request. Width and height may be anything from 16 to 2048 pixels; larger values are clamped rather than rejected, and the resolved size comes back in the JSON. To show a different image on every request, add ?random= followed by any value.

FAQ

Related tools