Avatars, made
easy to use.
A practical guide to profile images and favicons. Start with a URL, add your API key for metered usage, and keep the implementation you already have.
Your first avatar
Use a provider slug and profile handle wherever you would normally use an image URL.
<img src="https://oneavatar.dev/github/octocat" alt="Octocat" />For email addresses, OneAvatar checks Gravatar and then BIMI. For websites, request the domain favicon.
/email/matt@mullenweg.com/domain/google.comOne endpoint for each lookup
All routes return an image by default. URL encode values that contain reserved characters.
| Route | Use it for | Example |
|---|---|---|
/{platform}/{handle} | Supported profile providers | /github/octocat |
/email/{email} | Gravatar, then BIMI lookup | /email/hello%40example.com |
/domain/{domain} | Website favicon | /domain/example.com |
One key for your requests
Create one API key in your dashboard. Use that same key in the x-api-key header for server requests, or as ?token=YOUR_API_KEY for browser image embeds. There is no separate browser credential.
curl "https://oneavatar.dev/github/octocat" -H "x-api-key: oa_live_YOUR_KEY"
Image Embeds (Not Recommended)
While standard HTML <img> elements can utilize your token via the query string parameter token, this approach is not recommended because it exposes your secret key directly in frontend source code.
<img src="https://oneavatar.dev/github/octocat?token=oa_live_YOUR_API_KEY" referrerpolicy="origin" />Security Risk & Limitations
Exposing a token in a public frontend query string means anyone can see it. This does not keep your secret key hidden; anyone with access can extract it and exploit it from a backend server by simply mimicking your origin headers.
Securing Your Embeds with Domain Allowlists
If you must use image tags, navigate to Dashboard → API keys to configure and enforce strict domain allowlists checked via browser Origin and Referer headers.
| Pattern Rule | Matching Behavior & Scope |
|---|---|
example.com | Matches exact root hostname requests only. |
*.example.com | Matches all recursive subdomains (e.g., app.example.com, docs.example.com); does not match the apex root domain. |
app.example.com | Restricts usage exclusively to that specific target subdomain. |
The Recommended Approach (Server-Side Integration)
To protect your credentials, the recommended best practice is to:
- Keep your API key safe in server-side environment variables.
- Fetch avatar URLs or JSON payloads directly on your server using the secure
x-api-keyheader. - Pass only the final public image or json down to your frontend template.
Choose your fallback style
When no profile image is found, OneAvatar creates initials with UI Avatars. These query parameters style that fallback and do not alter an image returned by a provider.
/github/octocat?background=F0EDE6&color=24251F&size=128| Parameter | Default | Description |
|---|---|---|
fallback | url | (Optional) Fallback avatar URL. If not provided, a lettermark will be shown. |
background | F0EDE6 | Fallback background color in hex, without the # sign. |
color | 24251F | Fallback initials color in hex, without the # sign. |
size | 128 | Avatar width and height in pixels. |
fontSize | Provider default | Initials text size in pixels. Defaults to the provider value. |
length | Provider default | Number of initials to display. |
rounded | true | Round the fallback avatar corners. |
bold | true | Use bold initials in the fallback. |
uppercase | true | Convert fallback initials to uppercase. |
format | string | Output file format, specify either 'svg' or 'png'. |
Color values use six-digit hex without #. For example, ?background=F0EDE6&color=24251F&size=128&rounded=true.
Resolve a URL as JSON
Append .json to a route to return the resolved image URL in a JSON object.
GET /github/octocat.json
{ "url": "https://avatars.githubusercontent.com/u/583231?v=4" }The same query parameters can be used to configure the generated fallback.
Cache friendly by default
Responses follow upstream cache headers. Cloudflare can cache the image route at the edge, keyed by the configured request headers. A response marked no-store by the upstream should not be stored.
Usage activity for authenticated API requests appears in your dashboard.
Provider types, descriptions, and identifiers
Every lookup uses the provider slug as its route type and the following path segment as its identifier: /{provider}/{id}. Below is the comprehensive index of all supported platforms, complete with their expected identifier formats and typed properties.
Route pattern and parameters for every provider
| Provider | Route Pattern | Identifier Description | :type |
|---|---|---|---|
| github | /github/:id | GitHub username | - |
/google/:id | Website hostname or URL | - | |
| bimi | /bimi/:id | Domain name | - |
| stripe | /stripe/:id | Business profile handle | - |
| npm | /npm/:id | npm username (with or without @) | - |
| discord | /discord/:id | Discord invite code or invite URL | - |
| spotify | /spotify/:type/:id | Spotify resource ID | user, artist, album, playlist, show, episode, track |
| youtube | /youtube/:id | @handle or UC… channel ID | - |
/linkedin/:type/:id | User or company slug | user, company | |
| x | /x/:id | X username | - |
/reddit/:id | Reddit username | - | |
| twitch | /twitch/:id | Twitch username | - |
| telegram | /telegram/:id | Telegram username | - |
| bluesky | /bluesky/:id | Handle or DID | - |
| stackoverflow | /stackoverflow/:id | Stack Overflow user ID | - |
| steam | /steam/:type/:id | Steam vanity name or ID (typed forms below) | id, profile, group |
| tiktok | /tiktok/:id | TikTok username | - |
/facebook/:id | Profile or page slug | - | |
/instagram/:id | Instagram username | - | |
/pinterest/:id | Pinterest username | - | |
| gitlab | /gitlab/:id | User or group slug | - |
| gravatar | /gravatar/:id | Email address or Gravatar hash | - |
| behance | /behance/:id | Behance username | - |
| dribbble | /dribbble/:id | Dribbble username | - |
| medium | /medium/:id | Medium username | - |
| substack | /substack/:id | Publication subdomain | - |
| patreon | /patreon/:id | Creator slug | - |
| paypal | /paypal/:id | PayPal.Me username | - |
| cashapp | /cashapp/:id | Cashtag (with or without $) | - |
| venmo | /venmo/:id | Venmo username | - |
| wise | /wise/:id | Wise profile username | - |
| dockerhub | /dockerhub/:id | Docker Hub username | - |
| huggingface | /huggingface/:id | Hugging Face user or organization name | - |
| codepen | /codepen/:id | CodePen username | - |
| cursor | /cursor/:id | Cursor username (with or without @) | - |
| producthunt | /producthunt/:type/:id | Product Hunt username or product slug (typed forms below) | user, product |
| mastodon | /mastodon/:id | username@instance.domain | - |
| threads | /threads/:id | Threads username | - |
| tumblr | /tumblr/:id | Tumblr blog name or hostname | - |
| snapchat | /snapchat/:id | Snapchat username | - |
/whatsapp/:type/:id | Phone number, channel ID, or invite code (typed forms below) | phone, channel, chat | |
| vimeo | /vimeo/:id | Vimeo username or ID | - |
| soundcloud | /soundcloud/:id | SoundCloud username | - |
| deezer | /deezer/:type/:id | Deezer resource ID (typed forms below) | artist, album, playlist, track |
| tidal | /tidal/:type/:id | Tidal resource ID (typed forms below) | artist, album, playlist |
| strava | /strava/:id | Athlete ID | - |
| revolut | /revolut/:id | Revolut profile username | - |
| raycast | /raycast/:id | Raycast username (with or without @) | - |
| openstreetmap | /openstreetmap/:id | OpenStreetMap username or numeric user ID | - |
| apple-music | /apple-music/:type/:id | Artist or song search text (typed forms below) | artist, album, song |
| apple-store | /apple-store/:type/:id | App Store numeric ID or app name (typed forms below) | id, name |
| google-play | /google-play/:type/:id | Package name or developer ID (typed forms below) | app, dev |
| bilibili | /bilibili/:id | Numeric Bilibili user ID | - |
| gitee | /gitee/:id | Gitee username | - |
| juejin | /juejin/:id | Juejin user ID | - |
| kick | /kick/:id | Kick channel username | - |
| ko-fi | /ko-fi/:id | Ko-fi username | - |
| netease-music | /netease-music/:id | Numeric NetEase Music user ID | - |
| onlyfans | /onlyfans/:id | OnlyFans username | - |
| printables | /printables/:id | Printables handle (with or without @) | - |
/qq/:id | Numeric QQ account ID | - | |
/weibo/:id | Numeric user ID or screen name | - | |
| xboxgamertag | /xboxgamertag/:id | Xbox gamertag | - |
| zhihu | /zhihu/:id | Zhihu member slug | - |
| cults3d | /cults3d/:id | Cults3D username (with or without @) | - |
| deviantart | /deviantart/:id | DeviantArt username | - |
| duckduckgo | /duckduckgo/:id | Website hostname | - |
| flickr | /flickr/:type/:id | Flickr user or group ID/name (typed forms below) | user, group |
| hevy | /hevy/:id | Hevy username | - |
| tieba | /tieba/:id | Tieba username | - |
| thingiverse | /thingiverse/:id | Thingiverse username | - |
| buymeacoffee | /buymeacoffee/:id | Buy Me a Coffee username | - |
| primal | /primal/:id | Primal username or public key | - |
Advanced typed selectors (type:id)
For select platforms supporting granular resource types, separate the entity type and its specific identifier using a colon.
| Provider | Default Type | Types | Example Route |
|---|---|---|---|
| Apple Music | artist | artist:term, song:term, album:term | /apple-music/song:Daft%20Punk |
| Apple Store | id | id:app-id, name:app-name (with optional country code suffix like @US) | /apple-store/name:Pages |
| Deezer | artist | artist:id, album:id, playlist:id, track:id | /deezer/artist:27 |
| Flickr | user | user:handle, group:slug | /flickr/group:explore |
| Google Play | app | app:package.name, dev:developer-id | /google-play/app:com.example.app |
user | user:slug, company:slug | /linkedin/company:openai | |
| Product Hunt | Username | product:slug or raw username string | /producthunt/product:linear |
| Spotify | user | user:id, artist:id, album:id, playlist:id, track:id | /spotify/playlist:37i9dQZF... |
| Steam | id | id:name, profile:id, group:name | /steam/group:valve |
| Tidal | artist | artist:id, album:id, playlist:id | /tidal/album:1765857 |
phone | phone:number, channel:id, chat:invite-code | /whatsapp/channel:CHANNEL_ID |
All supported provider types
These route names map directly to the provider ecosystem. Use the respective identifiers outlined above.