$waldrand docs

4 endpoints, one rule: GET and go.

No auth, no SDKs, no sign-up. Every route answers a bare GET and caches. Planned endpoints are documented already because their shape is settled — the implementation is what's next.

Common behaviour

Authentication: None. There are no keys, no tokens, no account.
Rate limit: 60 requests per minute per IP, with bursts of up to 240 so a page full of avatars loads in one go. Only fresh renders count: a 304 or a response served from cache is free. Every response carries x-ratelimit-limit and x-ratelimit-remaining; going over returns 429 with retry-after.
Caching: Deterministic routes send cache-control: public, max-age=31536000, immutable. Same URL, same bytes.
CORS: access-control-allow-origin: * on every route. Usable straight from the browser.
Errors: 400 on invalid parameters, 404 on unknown routes, 429 at the limit. Error bodies are JSON, including on image routes.
Versioning: A deterministic route's output never changes. If a rendering gets reworked it gets a new route rather than new bytes.

Endpoints

avatar.waldrand.dev

online

Returns a deterministic avatar for any seed. The same seed gives the same SVG forever — good for placeholder profile pictures, commit authors, seats in a demo.

GET /{seed}.svg → image/svg+xml

Parameters: size (px, 16–512, default 128), palette (forest | mono | ink).

Full reference ↗

image.waldrand.dev

planned

A placeholder image at the requested dimensions, served as WebP. Meant for layout work, where lorem-ipsum images otherwise become half your load time.

GET /{w}x{h} → image/webp

Parameters: bg, fg (hex, no #), text (overlay label), grid (on | off).

Not live yet — shape settled, implementation to follow.

qr.waldrand.dev

planned

Encodes the given data as a QR code and hands back vector — scalable, printable, no watermark.

GET /{data}.svg → image/svg+xml

Parameters: ec (L | M | Q | H, default M), margin (modules, default 2), fg, bg.

Not live yet — shape settled, implementation to follow.

color.waldrand.dev

planned

Generates a colour palette as JSON. Deterministic on the seed, so the same brand gets the same colours twice.

GET /palette → application/json

Parameters: seed, count (2–12, default 5), mode (analogous | triad | mono).

Not live yet — shape settled, implementation to follow.

Example

# an avatar, pinned to a seed
curl "https://avatar.waldrand.dev/ada.svg?size=96"

# a 1200x630 placeholder with a label
curl "https://image.waldrand.dev/1200x630?text=og&grid=on" -o og.webp

# five colours off a seed
curl "https://color.waldrand.dev/palette?seed=waldrand&count=5"

{
  "seed": "waldrand",
  "mode": "analogous",
  "colors": ["#12100E", "#2A251E", "#A8A196", "#EFECE4", "#E8552F"]
}