Appearance

Return to top

Host the HTTP API yourself ​

In this guide, we will show you how to host the HTTP API yourself. This is not necessary for most users, but it can be useful in some cases.

You can find the source code for the HTTP API on GitHub. The code is written in TypeScript and uses the Fastify framework.

With docker ​

The easiest way to host the HTTP API yourself is to use the docker image. You can find the image on Docker Hub.

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

Or you can use docker-compose.yml to configure the HTTP API and start it with "docker compose up".

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

Without docker ​

If you don't want to use docker, you can also run the HTTP API directly on your machine. You need to have Node.js installed.

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

npm install
npm run build
npm start

Environment variables ​

The HTTP API supports the following environment variables:

PORT ​

The port on which the HTTP API should listen. Defaults to 3000.

HOST ​

The host on which the HTTP API should listen. Defaults to 0.0.0.0 (all IPv4 addresses). See https://fastify.dev/docs/latest/Reference/Server#listentextresolver

LOGGER ​

Enable the logger. Defaults to 0 (false).

PNG ​

Enable the PNG endpoint. Defaults to 1 (true).

PNG_SIZE_MIN ​

The minimum size for the PNG endpoint. Defaults to 1.

PNG_SIZE_MAX ​

The maximum size for the PNG endpoint. Defaults to 128.

PNG_SIZE_DEFAULT ​

The default size for the PNG endpoint. Defaults to 128.

PNG_EXIF ​

Enable EXIF data for the PNG endpoint. Defaults to 1 (true).

Requirements ​

JPEG ​

Enable the JPEG endpoint. Defaults to 1 (true).

JPEG_SIZE_MIN ​

The minimum size for the JPEG endpoint. Defaults to 1.

JPEG_SIZE_MAX ​

The maximum size for the JPEG endpoint. Defaults to 128.

JPEG_SIZE_DEFAULT ​

The default size for the JPEG endpoint. Defaults to 128.

JPEG_EXIF ​

Enable EXIF data for the JPEG endpoint. Defaults to 1 (true).

WEBP ​

Enable the WebP endpoint. Defaults to 1 (true).

WEBP_SIZE_MIN ​

The minimum size for the WebP endpoint. Defaults to 1.

WEBP_SIZE_MAX ​

The maximum size for the WebP endpoint. Defaults to 128.

WEBP_SIZE_DEFAULT ​

The default size for the WebP endpoint. Defaults to 128.

WEBP_EXIF ​

Enable EXIF data for the WebP endpoint. Defaults to 1 (true).

AVIF ​

Enable the AVIF endpoint. Defaults to 1 (true).

AVIF_SIZE_MIN ​

The minimum size for the AVIF endpoint. Defaults to 1.

AVIF_SIZE_MAX ​

The maximum size for the AVIF endpoint. Defaults to 128.

AVIF_SIZE_DEFAULT ​

The default size for the AVIF endpoint. Defaults to 128.

AVIF_EXIF ​

Enable EXIF data for the AVIF endpoint. Defaults to 1 (true).

Requirements ​

VERSIONS ​

Comma separated specification of desired DiceBear Major versions. Default to 5,6,7,8,9.

CACHE_CONTROL_AVATARS ​

Cache duration for the avatars endpoint in seconds. Defaults to 31536000 (1 year).

WORKERS ​

The number of node worker threads to use. Defaults to 1.

Adventurer by Lisa Wischofsky / CC BY 4.0. Avataaars by Pablo Stanley / Free for personal and commercial use. Face Generator by The Visual Team / CC BY 4.0. Custom Avatar by Ashley Seo / CC BY 4.0. Bottts by Pablo Stanley / Free for personal and commercial use. Croodles - Doodle your face by vijay verma / CC BY 4.0. Dylan! The Avatar Generator by Natalia Spivak / CC BY 4.0. Fun Emoji Set by Davis Uche / CC BY 4.0. Bootstrap Icons by The Bootstrap Authors / MIT. Lorelei by Lisa Wischofsky / CC0 1.0. Avatar Illustration System by Micah Lanier / CC BY 4.0. Miniavs - Free Avatar Creator by Webpixels / CC BY 4.0. Notionists by Zoish / CC0 1.0. Open Peeps by Pablo Stanley / CC0 1.0. Personas by Draftbit by Draftbit - draftbit.com / CC BY 4.0. - All avatars are remixes of the original works.