How to use them

Put an image tag where the avatar goes. Change the word at the end of the path and you get another Kuberdon.

<img src="https://cdn.kuberdon.eu/kuberdons/v1/Ada.svg" width="64" height="64" alt="">

v1

The version. v1 never changes. A new look would come as v2, at a new URL.

seed

Any text, up to 256 characters. The same seed always gives the same face. Encode it for a URL.

.svg or .png

SVG is a few kilobytes and sharp at any size. Use PNG where SVG is not welcome, like email.

parameters

All optional. Leave them out and the seed picks everything.

Add them as a query, like ?size=64&shape=squircle. A trait you set wins over the one the seed picked; the rest stay as they were.

Names are exact and lower case. The editor shows every part, and its Copy URL button gives you the address of the face you made.

• The seed alonehttps://cdn.kuberdon.eu/kuberdons/v1/Ada.svg
• A rounded squarehttps://cdn.kuberdon.eu/kuberdons/v1/Ada.svg?shape=squircle
• Another palettehttps://cdn.kuberdon.eu/kuberdons/v1/Ada.svg?palette=mint
• Glasses and happy eyeshttps://cdn.kuberdon.eu/kuberdons/v1/Ada.svg?extra=glasses&eyes=happy
• A trait codehttps://cdn.kuberdon.eu/kuberdons/v1/Ada.svg?t=k1.9.0.5.4.1.8

![Ada](https://cdn.kuberdon.eu/kuberdons/v1/Ada.png?size=128)

function Avatar({ seed, size = 40 }) {
  const src = `https://cdn.kuberdon.eu/kuberdons/v1/${encodeURIComponent(seed)}.svg`
  return <img src={src} width={size} height={size} alt="" />
}

.avatar {
  width: 40px;
  height: 40px;
  background: url("https://cdn.kuberdon.eu/kuberdons/v1/Ada.svg") center / cover;
}

Use something that stays the same for a person, like their user id. Please send a hash, never a raw email: anything in a URL can end up in logs along the way. Our own apps use the sha256 of the id.

async function kuberdonSeed(email) {
  const bytes = new TextEncoder().encode(email.trim().toLowerCase())
  const digest = await crypto.subtle.digest('SHA-256', bytes)
  return [...new Uint8Array(digest)].map(b => b.toString(16).padStart(2, '0')).join('')
}

import { createHash } from 'node:crypto'

const seed = createHash('sha256').update(email.trim().toLowerCase()).digest('hex')

Below 24 pixels the extras (glasses stay) and the cheeks drop out, so the face stays clear. Ask for the size you show, or larger for sharp screens.

The same URL always gives the same bytes, so every answer can be kept for good.

• Cache-Control: public, max-age=31536000, immutable: kept for a year.
• A strong ETag, the same for every spelling of one avatar (parameter order and defaults do not matter).
• Access-Control-Allow-Origin: *, so you can load them from any site.
• SVG comes compressed (brotli or gzip) when your client asks for it.
• No seeds or paths are logged. The server keeps request counts only, and the seed is never written into the image.

Nothing falls back quietly. An unknown parameter, a name that is not in the list, a size out of range, a parameter given twice or a bad trait code gets a 400 that says what is wrong:

{ "error": "bad-request", "reason": "size must be a whole number from 16 to 1024" }

Each IP address can make 1,200 requests a minute. Past that you get a 429 until the minute is up. Let browsers cache the images and you will not come close.

The code is MIT. The artwork, the faces themselves, is CC BY 4.0. You can use them anywhere, also in a commercial product, as long as you credit them as “Kuberdons by Kuberdon”. A line in your footer or credits is plenty.

Avatars: <a href="https://kuberdon.eu">Kuberdons by Kuberdon</a>, CC BY 4.0

The package, to draw them yourself offline, and the public code repository are coming soon Soon