unavatar.io: Unified Avatars Across 99 Platforms

Why unavatar.io consolidates provider-specific avatar lookups

unavatar.io addresses a repetitive integration problem. A product displaying user images may need to recognize GitHub usernames, Instagram handles, X/Twitter usernames, YouTube channel identifiers, email addresses, and website domains. Handling each source separately means maintaining provider pages, parsing conventions, avatar URLs, and failure behavior.

The service moves that variation behind an endpoint structure. A caller selects the source type in the path and supplies the relevant identifier. The README gives three forms: `unavatar.io/email/[email protected]` for email, `unavatar.io/github/kikobeats` for a GitHub username, and `unavatar.io/domain/reddit.com` for a domain. The project describes support for 99 platforms and services, including Instagram, SoundCloud, Telegram, X/Twitter, YouTube, Gravatar, GitLab, npm, Spotify, Reddit, and Mastodon.

That makes the project most relevant to web applications, documentation systems, community directories, comment interfaces, and internal tools that display avatars from heterogeneous identities. It is less suitable when the caller must control every network request or retain a provider-independent local identity record. The central value is the common HTTP interface, not a new avatar data format.

The README says images are compressed and optimized on the fly. It also identifies Microlink as the headless browser service behind the lookup process. Based on the repository layout, the npm package named `@unavatar/core` contains the implementation in `src/`, tests in `test/`, documentation in `docs/`, and command-line entry points in `bin/`. The hosted service and package therefore belong to one project, although the README documents hosted endpoints rather than a complete local installation procedure.

How unavatar.io routes identity requests

The visible routing model is endpoint-driven. The first path segment identifies the provider or identifier class, while the remaining path content supplies the username, email address, domain, or provider-specific parameter. The README explicitly warns that providers can accept different parameters, so clients should not assume that one identifier convention works everywhere.

This design keeps the basic client integration small. An `<img>` element can point at a complete unavatar.io URL, while applications needing structured metadata can use the JSON behavior advertised in the README's query parameters section. The documented controls include TTL, fallback, token, and JSON. The README excerpt does not include their detailed syntax, accepted values, response schema, or failure codes, so those details cannot be assumed.

The service also documents response formats, response headers, response errors, authentication, cache behavior, and provider-specific sections. Those headings indicate that this is more than an undocumented redirect endpoint, but they are not enough to claim exact implementation details that are not shown. In particular, the README does not document a rollback procedure, local cache invalidation mechanism, retry policy, or the complete mapping of HTTP errors.

Authentication is optional at the documented introductory level. The README says the hosted service requires no API keys or SDKs to start. It later describes secret keys, publishable keys, and domain restrictions, indicating that hosted authentication and production controls can become more involved. The exact configuration syntax is absent from the README, so a self-hosted evaluator would need to inspect `docs/`, configuration files, or the package exports before choosing a deployment model.

First web use, attribution, and the missing installation guide

The README does not provide npm installation, self-hosting, environment setup, or service-start commands. It directs readers to the hosted endpoint at `https://unavatar.io` and says to consult the provider documentation for accepted parameters. For that reason, there is no repository-backed installation command to reproduce here.

A first hosted use can be placed in an HTML page. The README presents this example, although the cleaned source has lost spacing inside several tags:

<imgsrc="https://unavatar.io/github/kikobeats"alt="Kiko"/>

The URL path contains `github` followed by `kikobeats`. When a browser requests that resource, the GitHub provider endpoint is expected to return the corresponding avatar image. The README presents similar links for `unavatar.io/x/josebaseba` and `unavatar.io/domain/reddit.com`.

Free plans require attribution. The README's documented link is:

<ahref="https://unavatar.io">Avatars provided by Unavatar</a>

The attribution must be publicly visible on a production website or another accepted surface. It must not use `rel="nofollow"`, redirects, URL shorteners, or obfuscation. For mobile applications, desktop applications, browser extensions, email, and other non-web products, the README says to place the attribution on the product's marketing site, app store listing description, or credits screen. Paid plans can remove the attribution requirement according to the README.

This policy has a direct product-design consequence. A visually minimal interface cannot simply hide the credit in inaccessible markup or direct it through a tracking redirect. Teams using the free service need to budget space for a visible link on a production surface or confirm paid-plan terms.

Cache controls and image delivery affect application design

Avatar requests are commonly repeated because the same profile appears in many places in an interface. The README includes a dedicated cache section and a TTL query parameter, confirming that cache lifetime can be controlled at the request level. The exact TTL syntax and permitted range are not included in the README.

Caching matters because unavatar.io resolves upstream profile information and processes the resulting image. The README says the hosted service serves avatars at scale and states a 70% cache hit rate. That figure is a project claim, but it indicates why cache behavior is part of the public interface.

Applications should not infer that a cached response means a real-time view of a social profile. A recently changed upstream avatar may remain visible until the relevant cache entry expires or another documented invalidation route is used. The README does not state whether purge requests exist or whether changing the TTL forces an immediate upstream lookup.

The fallback query parameter is another documented control. Its presence suggests that callers can request a fallback avatar, but the README does not identify the accepted value, resolution order, or behavior when every candidate fails. An engineer should therefore avoid promising guaranteed non-empty output in an interface until the detailed query parameter documentation and response error contract have been checked.

Image optimization is useful because avatars can be displayed at several sizes. Still, the README does not document negotiated formats, explicit dimensions, quality controls, or cache-control headers. The safest integration is to use the returned image as an ordinary remote asset and inspect the documented response headers before adding assumptions about content negotiation or storage behavior.

Provider coverage is broad, but identifier rules remain uneven

Provider breadth is unavatar.io's clearest feature. Its documentation lists services spanning developer platforms, media services, creator networks, payment pages, games, forums, and domain-based avatar systems. This allows an application to standardize its interface around `https://unavatar.io/<provider>/<identifier>`, provided that each provider's path semantics are respected.

The breadth also creates the main technical constraint. GitHub usernames, domain names, email addresses, and music-service identifiers are not interchangeable. Some providers may require a username, while others use a channel name, account identifier, or custom URL. The README's repeated statement that providers accept different parameters is a meaningful warning: a syntactically valid unavatar.io URL can still be invalid if its identifier does not match the selected service.

Provider changes also sit outside the client's control. The hosted service depends on upstream sites and, according to the README, Microlink's browser API. The documentation lists X/Twitter as `X/Twitter`, but its example uses the `x` path prefix. That is a concrete reminder to use the documented endpoint spelling rather than infer one from a provider's current brand name.

For applications that already store provider-specific avatar URLs, unavatar.io can simplify rendering and fallback policy. For applications that require provider-specific privacy controls, it may expose more network behavior than desired because the documented hosted flow resolves identity data through a centralized service. The README does not specify retention, upstream request logging, or privacy guarantees, so those points require separate review.

Microlink differs from per-provider avatar URL construction

A real alternative is to store or derive each provider's avatar URL directly. This approach avoids a common unavatar.io endpoint and gives the application direct control over provider requests, caches, and credentials.

The trade-off is integration work. Direct resolution requires the application to understand each provider's identifier rules and failure cases. It may also need provider-specific libraries or scraping logic, followed by maintenance when upstream pages change. unavatar.io moves that variation behind one hosted interface and documents a broad provider catalog, but it introduces a dependency on the hosted service and its operational rules.

Self-hosting the npm package could be an alternative path, based on the presence of `@unavatar/core`, CLI binaries, source files, and documentation in the repository. However, the README does not document how to configure or start a local instance, so it would be inaccurate to present self-hosting as a confirmed turnkey alternative. The repository structure supports further investigation, not a specific deployment claim.

Maintenance releases and MIT package adoption

The repository is not archived. Its last push was on 2026-10-15, and releases `v3.71.1`, `v3.71.2`, and `v3.71.3` were published on October 14 and October 15, 2026. This supports the conclusion that the project is receiving current repository changes at the recorded point, although frequent releases alone do not establish the stability of every hosted provider.

The package version in `package.json` is `3.71.3`, matching the newest listed release. Its published entry points include `@unavatar/core`, utility exports such as `./util` and `./http-status`, and the `unavatar` and `unavatar-dev` binaries. The README does not document those CLI commands, so their exact behavior should not be inferred from their names.

The repository uses the MIT license. That permits use, modification, distribution, and sublicensing under the license's conditions, while preserving the copyright and license notice. This is a technical summary rather than legal advice. An organization should also review the hosted service's pricing terms, acceptable-use requirements, and provider-specific obligations separately, because the MIT license covers the repository code rather than automatically defining every aspect of service operation.

Upgrade cost appears concentrated in dependency and API compatibility rather than a documented migration framework. The repository includes `CHANGELOG.md`, but its contents are not present in the README. Before pinning `@unavatar/core`, an adopter should read that file for behavioral changes and inspect the exact exports used by the application.

Editorial conclusion

Adopt unavatar.io when a web product can depend on its hosted provider endpoints and free-plan attribution rules fit the interface. Do not adopt it when provider-specific resolution, offline operation, or guaranteed migration-free access is mandatory. Verify the exact provider identifiers, fallback behavior, pricing terms, and attribution placement before production use.

Frequently asked questions

Official sources

1. License: MIT
2. microlinkhq/unavatar on GitHub
3. Project website
4. README
5. Releases