# 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.

Published 2026-10-19 · https://avatarsapi.com/blog/unavatar-alternative

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](https://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](https://avatarsapi.com/sources)) | 99 providers ([docs](https://unavatar.io/docs)) |
| Key for basic use | None | None (key optional) |
| Free-tier attribution | Required; Starter removes it | Required; PRO removes it ([docs](https://unavatar.io/docs)) |
| Paid model | $19 per Project per month | Metered per request in tokens ([docs](https://unavatar.io/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](https://github.com/microlinkhq/unavatar)) |

## 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](https://avatarsapi.com/docs#validation))

**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](https://avatarsapi.com/docs#errors) 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](https://unavatar.io/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:

```diff
- <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:

- A bare username (`/torvalds`) is ambiguous, so avatarapi returns `EAMBIGUOUS` instead of guessing a platform. Name the Source.
- `?fallback=` is not accepted. Use an error handler: `onerror="this.src='/placeholder.svg'"`.
- `?size=` sets a square output from 16 to 1000 px.
- Free use on both needs an attribution link; on avatarapi it is a visible "Avatars by avatarsapi.com" link where the images appear.
- Check the [Source list](https://avatarsapi.com/sources) for the platforms you use.

## 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](https://unavatar.io/docs) as read on October 19, 2026. Pricing changes; check [unavatar's site](https://unavatar.io) before you decide.