avatars-api/README.md

84 lines
2.7 KiB
Markdown

# Avatars API
A self-hosted avatars API using some of the [DiceBear](https://www.dicebear.com/) CC0 styles
You can take a look at my own self-hosted version here: https://avatars.jusemon.com
The following endpoints are available:
- https://avatars.jusemon.com/list
- https://avatars.jusemon.com/random
- https://avatars.jusemon.com/:seed
The size and style of the image can be changed with the following query params:
- `size`: any number between `16` and `512`
- `style`: see the list endpoint, the valid values are defined by the property `key`
## Example:
https://avatars.jusemon.com/jusemon?size=256&style=open-peeps where jusemon is the :seed
![Example](https://avatars.jusemon.com/jusemon?size=256&style=open-peeps)
## Installation
### Development
For run locally it needs a `.env` file with the environment variables defined in the `.env.example`
ALLOWED_ORIGINS includes a comma separated list for the allowed CORS sites.
Install dependencies `npm install` or `yarn`
To start the project run `npm run dev` or `yarn dev`
### Production
For run it in docker just run `docker compose up`
Alternatively, you can run the image without cloning this repo using the image published [here](https://git.jusemon.com/jusemon/avatars-api/packages)
With docker run:
```sh
docker run -p 3000:3000 -e NODE_ENV=production -e HOST=0.0.0.0 -e PORT=3000 -e API_VERSION=1 -e ALLOWED_ORIGINS=https://example.com git.jusemon.com/jusemon/avatars-api:1.0.0
```
With docker compose:
```yaml
name: avatars
services:
api:
image: git.jusemon.com/jusemon/avatars-api:1.0.0
ports:
- 3000:3000
environment:
NODE_ENV: "production"
HOST: "0.0.0.0"
PORT: 3000
API_VERSION: 1
ALLOWED_ORIGINS: "https://example.com"
```
## Libraries Used
- DiceBear (for avatar generation)
- sharp (for png exportation)
- uuid (for random seeds)
## Credits
- Created by Juan Sebastián Montoya
### Credits for Styles:
| Title | Creator | Source | Homepage | License |
| ---------- | ------------- | -------------------------------------------------------- | -------------------------------- | ------- |
| Open Peeps | Pablo Stanley | https://www.openpeeps.com/ | https://twitter.com/pablostanley | CC0 1.0 |
| Pixel Art | DiceBear | https://www.figma.com/community/file/1198754108850888330 | https://www.dicebear.com | CC0 1.0 |
| Thumbs | DiceBear | https://www.dicebear.com | https://www.dicebear.com | CC0 1.0 |
## License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).