Gravatar CDN API

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

📌 Endpoints

GET /avatar/me

Fetch the maintainer's avatar with no param needed.

GET /avatar/:hash

Fetch avatar via precomputed MD5 or SHA-256 hash of an email address.

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

GET /avatar?email=<email>

Fetch avatar via raw email (securely hashed on the server).

<email>: The plain email address to resolve a Gravatar (if the email is invalid, we will use `email@example.com` as fallback).

⚙️ Query Parameters

s= orsize= (default: 200)
Avatar size in pixels (applies to both width and height).
d= ordefault= (default: 404)
Default fallback image when the requested email do not have a image associated with. You can put URL, or any other options that gravatar support.
initials= (Only works when you set default to initials)
Default fallback image with the given initials when the requested email do not have a image associated with. You need to put the initials you would like to have as a fallback.
name= (Only works when you set default to initials)
Default fallback image with the initials based on the given name when the requested email do not have a image associated with. You can put the full name you would like to have as a fallback. Initials will be auto extracted.

🎨 Format Negotiation

Avatars are automatically converted to AVIF or WebP based on the browser’s Accept header. JPEG is used as a fallback if neither is supported.

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

📦 Caching

200 OK: Cached at the edge for 7 days, browser cache for 3 days, with 7-day 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

Request with email and size 256:

GET /avatar?email=email@example.com&size=256

Request with email and size 500 and fallback initial 'A':

GET /avatar?email=email@example.com&size=500&d=initials&initials=A