⚡ Instantly get user avatars via 1 API call. Ready to use. 100 artsy avatars included. included.

🚀 Serverless Userpics

Fetch avatars for your next service in a single API call.


  • [x] 🚀 Generate avatars on the fly
  • [X] 🎨 100 avatars included from (I'm not affiliated with them, just a fan)
  • [X] 🎨 Abstraction over Boring Avatars included as well.
  • [x] ✨ Tiny as fuck.
  • [x] ✨ Serverless. Configurable. Easily deployable.

Usage (Important)


  1. api/getpic/
  2. api/avatar/ - ?stream=True query outputs an SVG for you.

Available Query Params

  • ?name=string - Your username. Defaults to Cactus Jack.
  • ?size=int - Size of the avatar. Default is 128.
  • ?variant=string - Variant of the avatar. Default is beam.
  • ?stream=bool - Stream the SVG instead of returning a URL. Default is False.

Available Variants

  • marble
  • pixel
  • beam
  • sunset
  • ring
  • bauhaus

All these variants and avatars (under api/avatar/ route) are from Boring Avatars.

Route 2

Quick and dirty example

  1. Head over to and "Get a random user pic".
  2. Use the URL in your app.

Python Example

  • /api/getpic/ is the endpoint to get a random avatar.
def random_avatar():
    name = str(uuid.uuid4())[:8]
    with open(f"media/avatars/{name}.png", "wb+") as f:
        url = requests.get("")
        response = requests.get(url.text, stream=True)
        if not response.ok:
            raise Exception("Could not get avatar")
        for block in response.iter_content(1024):
            if not block:
    return f"avatars/{name}.png"

You can try svg too btw, haven't tested it but it should work.


accountId := os.Getenv("ACCOUNT_ID")
bucketName := os.Getenv("BUCKET_NAME")
accessKeyId := os.Getenv("API_ACCESS_KEY")
accessKeySecret := os.Getenv("API_SECRET_KEY")

Replicate this

  1. Create an R2 bucket on Cloudflare.
  2. Generate S3 Token via Manage R2 API Tokens in R2 Dashboard.
  3. Set your environment variables.
  4. Deploy âš¡

Running locally

do the usual. install dependencies via yarn and run yarn run start/yarn run dev.

Make sure to setup environment variables in your Vercel dashboard. Also make sure to have S3 API access and secret on the recieving end if your bucket is private like mine.


| Resource | Service | | --- | --- | | Storage | Cloudflare R2 (S3 compatible) | | Serverless Hosting | Vercel (AWS Lambda) |


Check out the issues for more info.


template-go-vercel was helpful while deploying.

Repo Not Found