wehub-resource-sync
8.5 KiB
title, description
| title | description |
|---|---|
| HTTP API – Generate SVG Avatars via URL | Free avatar API and profile picture API by DiceBear. Generate random user avatars and user placeholder images with a simple URL. No authentication required. |
HTTP API: generate SVG avatars via URL
Our HTTP API is the simplest way to use DiceBear as a profile picture API or avatar placeholder API. No authentication is required.
Usage
Use the following address and replace <styleName> with your preferred avatar
style. Style names are lowercase, with hyphens for multi-word styles, e.g.
lorelei, pixel-art, adventurer-neutral. Every official
avatar style is supported.
https://api.dicebear.com/10.x/<styleName>/svg
A few examples
Generate a consistent avatar from a user ID
Use a stable identifier as the seed and every user gets the same avatar on
every visit. A user ID works well, and the same seed always returns the same
image. That makes it a good default avatar for people who haven't uploaded a
photo yet, since the picture stays the same across pages and sessions.
https://api.dicebear.com/10.x/lorelei/svg?seed=user-8f3a2c
If the seed contains spaces or other special characters, URL-encode it first.
:::info
We provide a large number of avatar styles from different artists. The avatar styles are licensed under different licenses that the artists can choose themselves. For a quick overview we have created an license overview for you.
:::
Listing available styles
To discover which avatar styles an instance supports, send a request to the version root. It returns the available style names as JSON, sorted alphabetically:
https://api.dicebear.com/10.x
{
"styles": ["adventurer", "adventurer-neutral", "avataaars", "..."]
}
::: info
This endpoint is available from version 10.x onwards. Earlier versions do not
support listing styles.
:::
Style definition and options
Each style also exposes two metadata endpoints. They are handy for building tooling on top of the API, such as avatar editors:
https://api.dicebear.com/10.x/<styleName>/definition.json
https://api.dicebear.com/10.x/<styleName>/options.json
definition.json returns the raw style definition, the same JSON that is
shipped with the style's npm package.
options.json describes every option the style accepts as query parameter,
including field types, allowed enum values, and value ranges. An excerpt for
Pixel Art:
{
"seed": { "type": "string" },
"flip": {
"type": "enum",
"values": ["none", "horizontal", "vertical", "both"],
"list": true
},
"backgroundColor": { "type": "color", "list": true },
"hairVariant": {
"type": "enum",
"values": ["long01", "long02", "...", "short24"],
"list": true,
"weighted": true
},
"hairProbability": { "type": "number", "min": 0, "max": 100 }
}
::: info
These endpoints are available from version 10.x onwards. On self-hosted
instances they are disabled by default. See the
self-hosting guide.
:::
Options
All core options (such as seed,
flip, rotate, scale, borderRadius, and backgroundColor) are available
as query parameters.
Style-specific options are listed on each avatar style page. For
example:
:::tip
If you want to pass more options, you connect them with a & as usual with
query strings.
:::
::: warning
The options idRandomization, fontFamily, fontWeight, and title are not
supported by our public HTTP API. You can enable them by
hosting your own instance.
:::
Array options
Array values are separated by a comma. For example, the URL could look like this if you want to provide the PRNG with several hair styles in addition to the seed. Note that the avatar styles provide different options. In this example, we use the Pixel Art avatar style.
Enum options
Enum values are passed as strings. For example, the flip option accepts
none, horizontal, vertical, or both:
File format
PNG, JPG, WebP and AVIF use the
Noto Sans font and currently
supports the following subsets: cyrillic, cyrillic-ext, devanagari,
greek, greek-ext, japanese, korean, latin, latin-ext,
simplified-chinese, thai and vietnamese.
Versioning
You can set the version in the URL. Just replace the 10.x from the previous
examples with the one you want.
| Version | Status | End of Life |
|---|---|---|
10.x |
Active | None |
9.x |
Active | None |
8.x |
Deprecated | April 30, 2028 |
7.x |
Deprecated | April 30, 2028 |
6.x |
Deprecated | April 30, 2028 |
5.x |
Deprecated | April 30, 2028 |
::: warning
Versions 5.x to 8.x will reach End of Life on April 30, 2028. After that date, the HTTP API for these versions will be shut down and no longer available. Please upgrade to the latest version. See the announcement for details.
:::
::: info
You can host the API yourself to keep using discontinued versions after their End of Life.
:::
Self-hosted avatar API
Need a private or commercial setup? You can host the Avatar API yourself for full control over availability, rate limits, and data privacy.
Fair use & rate limits
Our API is free to use for non-commercial purposes, but please use it responsibly. We reserve the right to block abusive users.
We currently limit requests per second to 50 for SVG and 10 for PNG, JPG,
WebP, and AVIF. Exceeding the limit returns HTTP 429 Too Many Requests. We
reserve the right to change these limits at any time without notice.
For commercial use or higher limits, please set up your own instance. We're happy to answer questions: open a discussion on GitHub.
Changes and availability
Please be aware that we reserve the right to update the API at any time. While we will do our best to maintain backwards compatibility, we cannot guarantee this. Even though we try to always return the same avatar, the design and especially the source code may change. Additionally, we cannot guarantee that the API will always be available. If you need consistent access to the API, we recommend setting up your own instance.