DiceBear API

Self-host the DiceBear avatar API for privacy-by-design and commercial use. Built on Fastify.

Playground | Documentation | Docker Hub

Getting Started

With Docker

docker run --tmpfs /run --tmpfs /tmp -p 3000:3000 -i -t dicebear/api:3

Or with docker-compose.yml:

services:
  dicebear:
    image: dicebear/api:3
    restart: always
    ports:
      - '3000:3000'
    tmpfs:
      - '/run'
      - '/tmp'

Without Docker

Requires Node.js.

git clone git@github.com:dicebear/api.git
cd api

npm install
npm run build
npm start

Environment Variables

Variable	Default	Description
PORT	3000	Port to listen on.
HOST	0.0.0.0	Host to bind to (all IPv4 addresses by default).
LOGGER	0	Enable request logger (1 = on, 0 = off).
WORKERS	1	Number of Node.js worker threads.
VERSIONS	5,6,7,8,9	Comma-separated list of supported DiceBear major versions.
CACHE_CONTROL_AVATARS	31536000	Cache duration for avatar responses in seconds (1 year).
PNG	1	Enable the PNG endpoint (1 = on, 0 = off).
PNG_SIZE_MIN	1	Minimum allowed PNG size in px.
PNG_SIZE_MAX	256	Maximum allowed PNG size in px.
PNG_SIZE_DEFAULT	128	Default PNG size in px.
PNG_EXIF	1	Enable EXIF metadata for PNG (1 = on, 0 = off).
JPEG	1	Enable the JPEG endpoint (1 = on, 0 = off).
JPEG_SIZE_MIN	1	Minimum allowed JPEG size in px.
JPEG_SIZE_MAX	256	Maximum allowed JPEG size in px.
JPEG_SIZE_DEFAULT	128	Default JPEG size in px.
JPEG_EXIF	1	Enable EXIF metadata for JPEG (1 = on, 0 = off).
WEBP	1	Enable the WebP endpoint (1 = on, 0 = off).
WEBP_SIZE_MIN	1	Minimum allowed WebP size in px.
WEBP_SIZE_MAX	256	Maximum allowed WebP size in px.
WEBP_SIZE_DEFAULT	128	Default WebP size in px.
WEBP_EXIF	1	Enable EXIF metadata for WebP (1 = on, 0 = off).
AVIF	1	Enable the AVIF endpoint (1 = on, 0 = off).
AVIF_SIZE_MIN	1	Minimum allowed AVIF size in px.
AVIF_SIZE_MAX	256	Maximum allowed AVIF size in px.
AVIF_SIZE_DEFAULT	128	Default AVIF size in px.
AVIF_EXIF	1	Enable EXIF metadata for AVIF (1 = on, 0 = off).
JSON	1	Enable the JSON endpoint (1 = on, 0 = off).
QUERY_STRING_ARRAY_LIMIT_MIN	20	Minimum number of values allowed per array parameter.
QUERY_STRING_PARAMETER_LIMIT_MIN	100	Minimum number of query string parameters allowed.

Note

The *_EXIF variables require Perl and procps to be installed.

Sponsors

Advertisement: Many thanks to our sponsors who provide us with free or discounted products.