API Reference

ZLA Gravatar CDN

Serve avatars from Gravatar with modern WebP/AVIF support, intelligent caching, and graceful fallback handling.

Endpoints

GET /avatar/me

Returns the configured maintainer avatar.

GET /avatar/:hash

Returns an avatar for a precomputed MD5 or SHA-256 email hash.

hash: The MD5 or SHA-256-hashed value of the email (lowercased and trimmed).

GET /avatar?email=<email>

Resolves a raw email address after server-side normalization. Enable this endpoint only when you accept that email addresses can appear in URLs, logs, browser history, and intermediary proxies. Raw email lookups are disabled on this deployment.

<email>: The plain email address to resolve. It is trimmed and lowercased before hashing; invalid or missing values fall back to email@example.com.

Generate Avatar Links

Query Parameters

s= orsize= (default: 200)
Avatar size in pixels (applies to both width and height).
d= ordefault= (default: 404)
Fallback shown when the requested email has no Gravatar image. Use a URL or any fallback option supported by Gravatar.
initials= (requires default=initials)
Fallback image using the initials you provide. Only applies when the default option is set to initials.
name= (requires default=initials)
Fallback image using initials extracted from the provided name. Only applies when the default option is set to initials.

Format Negotiation

Avatars are automatically converted to AVIF or WebP based on the browser’s Accept header, including quality values such as q=0.9. The original image format is used as a fallback if neither is supported or the requested image is too large to safely transform at the edge.

Accept: image/avif,image/webp, image/*, */*

Caching

200 OK: Cached at the edge for 7 days, browser cache for 3 days, with 7 days stale-while-revalidate for seamless background updates.
404 fallback: Cached at the edge for 1 hour, browser cache for 5 minutes, with 1 hour stale-while-revalidate to support retry on new accounts.
Vary: Accept: Ensures proper caching per image format (AVIF/WebP/JPEG).
ETag: Uses avatar hash for efficient cache validation and conditional requests.

Example Requests

Request with MD5 hash and size 128:

GET /avatar/205e460b479e2e5b48aec07710c08d50?s=128

Raw email request with size 256 (requires ALLOW_RAW_EMAIL=true):
```
GET /avatar?email=email@example.com&size=256
```
Raw email request with size 500 and fallback initial 'A' (requires ALLOW_RAW_EMAIL=true):
```
GET /avatar?email=email@example.com&size=500&d=initials&initials=A
```