avatarapi vs unavatar: comparing avatar-by-username APIs

A side-by-side look at avatarapi and unavatar.io, the two APIs that return a profile picture from a username, email, or domain in one URL.

If you need a profile picture for a username on GitHub, X, Bluesky, or Twitch, there are really two hosted APIs that do it across many platforms with one URL: unavatar.io and avatarapi. Both put the platform and handle in the path and answer with image bytes you can drop into an <img> tag. This post compares them as of October 2026, with links to each source so you can check the details yourself.

The short version

avatarapi unavatar
URL shape avatarsapi.com/:source/:handle unavatar.io/:provider/:id
Email and domain routes /email/:address, /domain/:domain /email/:address, /domain/:domain
Platforms 72 Sources (live list) 99 providers (docs)
Key for basic use None None (key optional)
Free-tier attribution Required; Starter removes it Required; PRO removes it (docs)
Paid model $19 per Project per month Metered per request in tokens (docs)
Misses 404 JSON envelope with a stable code 404 when fallback=false, otherwise a fallback image
Response Validated image bytes from the same URL Image bytes
Source code Closed MIT, self-hostable (GitHub)

Where unavatar is ahead

More providers. unavatar lists 99 providers in its docs, including ENS and Farcaster, and coverage grew a lot during 2026. If your users live on a platform avatarapi does not cover yet, check unavatar's list first.

Open source. unavatar is MIT licensed. If you want to run your own instance and own the scraping risk yourself, you can.

Fallback images on the URL. unavatar accepts ?fallback= with an image URL or data URI, so a missing avatar can render something without client code. avatarapi retired runtime fallback URLs for anonymous use; you handle a Miss with an onerror handler today, and managed Fallbacks are coming to paid Projects.

Where avatarapi is different

Every Hit is probed before it is served. Some avatar URLs are well formed even for accounts that do not exist. github.com/<user>.png and Gravatar's d=404 URLs are the classic examples. avatarapi fetches the candidate, follows at most three redirects, and only calls it a Hit when it gets a 2xx image/* response under 2 MiB from a public address. A missing account becomes a clean 404, not a default silhouette. (docs)

Typed errors. Every failure is the same JSON envelope with a code you can branch on: ENOTFOUND for an ordinary Miss, EUPSTREAM when the platform is broken, ERATELIMIT, ETIMEOUT, and so on. The error table is short and stable.

Predictable pricing. unavatar's paid plan is metered per request, and fetches that go through a proxy cost more tokens than direct ones (docs). avatarapi's Starter plan is $19 per Project per month, and cached images never count toward usage.

Attribution and cache lifetime. Both services ask free users for a link back and reserve a custom ttl for paying customers. The difference is how you pay to remove them: per request on unavatar, a fixed monthly price per Project on avatarapi.

Switching is mostly a find-and-replace

Both APIs use the same mental model, so most URLs map one to one:

- <img src="https://unavatar.io/github/torvalds">
+ <img src="https://avatarsapi.com/github/torvalds">

- <img src="https://unavatar.io/email/jane@stripe.com">
+ <img src="https://avatarsapi.com/email/jane@stripe.com">

Differences to watch:

Which should you pick?

Pick unavatar if you need a provider avatarapi lacks, want to self-host, or want fallback images on the URL today. Pick avatarapi if you want validated Hits, typed errors you can branch on, and a fixed monthly price per Project. You can also try both in a minute: put the same handle in each URL and compare.

Facts about unavatar are from its documentation as read on October 19, 2026. Pricing changes; check unavatar's site before you decide.

Try it: put https://avatarsapi.com/github/torvalds in an <img src>. No key, no signup. Read the docs or create a Project.