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 -ti -p 3000:3000 dicebear/api:latest

docker run -ti -p 3000:3000 dicebear/api:latest

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 start

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

npm install
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.

ADDRESS ​

The address on which the HTTP API should listen. Defaults to 0.0.0.0 (all IPv4 addresses).

ENABLE_LOGGER ​

Enable the logger. Defaults to 0 (false).

ENABLE_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 256.

PNG_SIZE_DEFAULT ​

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

ENABLE_PNG_EXIF ​

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

Requirements ​

• Perl (https://www.npmjs.com/package/exiftool-vendored#installation)
• procps (https://www.npmjs.com/package/exiftool-vendored#this-package-requires-procps)

ENABLE_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 256.

JPEG_SIZE_DEFAULT ​

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

ENABLE_JPEG_EXIF ​

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

Requirements ​

• Perl (https://www.npmjs.com/package/exiftool-vendored#installation)
• procps (https://www.npmjs.com/package/exiftool-vendored#this-package-requires-procps)

ENABLE_VERSION_4_4 ​

Enable the version 4.4 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_5 ​

Enable the version 4.5 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_6 ​

Enable the version 4.6 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_7 ​

Enable the version 4.7 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_8 ​

Enable the version 4.8 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_9 ​

Enable the version 4.9 endpoint. Defaults to 1 (true).

ENABLE_VERSION_4_10 ​

Enable the version 4.10 endpoint. Defaults to 1 (true).

ENABLE_VERSION_5_0 ​

Enable the version 5.0 endpoint. Defaults to 1 (true).

ENABLE_VERSION_5_1 ​

Enable the version 5.1 endpoint. Defaults to 1 (true).

ENABLE_VERSION_5_2 ​

Enable the version 5.2 endpoint. Defaults to 1 (true).

ENABLE_VERSION_5_3 ​

Enable the version 5.3 endpoint. Defaults to 1 (true).

ENABLE_VERSION_6 ​

Enable the version 6 endpoint. Defaults to 1 (true).

ENABLE_VERSION_7 ​

Enable the version 7 endpoint. Defaults to 1 (true).

CACHE_CONTROL_AVATARS ​

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