avatar.waldrand.dev — Avatare & Identicons

Seeds & Determinismus

Der Seed ist alles zwischen dem führenden Schrägstrich und der Dateiendung. Er wird mit SHA-256 gehasht, und der Digest ist die einzige Zufallsquelle, aus der ein Stil schöpfen darf — das Zeichen zu einem Seed liegt damit fest, auf jeder Maschine, in jedem Prozess, solange der Stil steht.

Es gibt keine Datenbank und kein Konto. Zwei Aufrufer mit demselben Seed bekommen dieselben Bytes, ohne sich je begegnet zu sein.

Beliebiger UTF-8-Text bis 256 Zeichen. Alles, was eine URL sonst als Struktur liest, prozentkodieren — /, ?, #.
Seeds unterscheiden Groß- und Kleinschreibung: Ada und ada sind zwei verschiedene Personen.
Punkte sind erlaubt. Nur ein abschließendes .svg, .png oder .webp gilt als Format, ada.lovelace.png ist also der Seed ada.lovelace.
Der Stil geht in den Hash ein, ?style=grid ist also eine andere Zeichnung und nicht dieselbe in anderen Farben.

Hash die Kennung vorher, wenn sie personenbezogen ist. Eine E-Mail-Adresse in einer URL steht in jedem Log und jedem Cache dazwischen; ihr SHA-256 zeichnet sich genauso gut.

Formate

Die Endung wählt den Encoder. SVG ist die Vorgabe und das Günstigste — ein paar hundert Bytes Geometrie, die auf jede Größe skalieren, weshalb size dort nichts tut.

Pfad	Content-Type	Anmerkungen
`/{seed}.svg`	image/svg+xml	Die Vorgabe. Auflösungsunabhängig, rund 400 Bytes.
`/{seed}.png`	image/png	Gerastert auf `size`. Transparent bei `bg=none`.
`/{seed}.webp`	image/webp	Dieselben Pixel, etwa ein Drittel der Bytes.

Stile

Vier, und kein fünfter geplant. Jeder macht aus demselben Digest eine andere Form; der Akzent taucht in jedem Zeichen genau einmal auf, und das hält eine ganze Wand davon zusammen.

`GET /{seed}.svg`

Liefert image/svg+xml. Das Markup trägt ein <title> und ein aria-label mit dem Seed, ein Screenreader sagt also etwas Besseres als „Bild“. Kein Skript, keine externe Referenz darin.

# ein 64px-Zeichen für eine Nutzer-ID, rund geschnitten
curl "https://avatar.waldrand.dev/u_18f2c9.svg?radius=50"

# direkt ins HTML — kein Build-Schritt, kein Proxy
<img src="https://avatar.waldrand.dev/u_18f2c9.svg?radius=50" width="64" height="64" alt="">

`GET /{seed}.png`

Liefert image/png, gerastert auf size. Für alles, wo SVG nicht willkommen ist — E-Mail, OpenGraph-Karten, native Bildansichten. Endung auf .webp tauschen, um ein Drittel der Bytes zu senden.

# 512px, transparenter Grund, auf die Platte
curl "https://avatar.waldrand.dev/ada.png?size=512&bg=none" -o ada.png

# derselbe Seed, dieselben Pixel, kleinere Datei
curl "https://avatar.waldrand.dev/ada.webp?size=512" -o ada.webp

Parameter

Name	Typ	Vorgabe	Anmerkungen
seed	string	erforderlich	Im Pfad. Beliebiger UTF-8-Text bis 256 Zeichen.
size	16–1024	256	Kantenlänge in Pixeln. Bei SVG ohne Wirkung.
style	enum	ridge	ridge · grid · initials · rings
radius	0–50	0	Eckenrundung in Prozent. 50 = Kreis.
bg	hex	auto	Hintergrundfüllung, oder `none` für transparent.

Limits

Limit — pro IP

60Anfr. / Min.

Der Eimer fasst vier Minuten, eine Seite mit 200 Avataren lädt also in einem Rutsch; er füllt sich mit einer pro Sekunde nach. Es zählen nur frische Renderings: ein 304 oder ein Avatar aus dem Server-Cache ist frei, und vom Browser gecachte Bilder erreichen uns gar nicht.

Antwort-Header

X-RateLimit-Limit:: 60
X-RateLimit-Remaining:: 237
X-RateLimit-Reset:: 1738 (Epoch s)
Retry-After:: nur bei 429

Jeder gerenderte Avatar kommt mit einem starken ETag und Cache-Control: public, max-age=2592000, immutable zurück. Eine bedingte Anfrage, die trifft, wird mit 304 beantwortet und kostet dich kein Rendern.

Fehler

Der gute Fall ist ein Bild; alles andere ist JSON, weil ein Aufrufer mit einem Fehler in der Hand ihn lieber parst als liest.

Status	Code	Wann
400	bad_seed	Leer, über 256 Zeichen, oder keine gültige Prozentkodierung.
400	bad_param	Ein Parameter liegt außerhalb des Bereichs oder ist kein bekannter Wert. Der Body nennt welcher.
400	unknown_format	Eine andere Endung als .svg, .png oder .webp.
405	method_not_allowed	Alles außer GET, HEAD oder OPTIONS.
429	rate_limited	Über der Decke. `Retry-After` sagt, wie lange.

{
  "error": {
    "status": 400,
    "code": "bad_param",
    "param": "size",
    "message": "size must be between 16 and 1024, got 4096."
  },
  "docs": "https://avatar.waldrand.dev/"
}