llms.txt
# unavatar.io
## Table of Contents
- [Introduction](#introduction)
- [Quick start](#quick-start)
- [Attribution](#attribution)
- [How to add attribution](#how-to-add-attribution)
- [Remove attribution](#remove-attribution)
- [Authentication](#authentication)
- [Secret keys](#secret-keys)
- [Publishable keys](#publishable-keys)
- [Domain restrictions](#domain-restrictions)
- [Pricing](#pricing)
- [Cache](#cache)
- [Query parameters](#query-parameters)
- [TTL](#ttl)
- [Fallback](#fallback)
- [Token](#token)
- [JSON](#json)
- [Providers](#providers)
- [Apple Music](#apple-music)
- [Apple Store](#apple-store)
- [Behance](#behance)
- [Bilibili](#bilibili)
- [BIMI](#bimi)
- [Bitbucket](#bitbucket)
- [Bluesky](#bluesky)
- [Buy Me a Coffee](#buy-me-a-coffee)
- [Cash App](#cash-app)
- [Chess.com](#chesscom)
- [Codeforces](#codeforces)
- [CodePen](#codepen)
- [Cults3D](#cults3d)
- [Cursor](#cursor)
- [Dailymotion](#dailymotion)
- [Deezer](#deezer)
- [DEV](#dev)
- [DeviantArt](#deviantart)
- [Discord](#discord)
- [Docker Hub](#docker-hub)
- [Domain](#domain)
- [Dribbble](#dribbble)
- [DuckDuckGo](#duckduckgo)
- [Duolingo](#duolingo)
- [Email](#email)
- [ENS](#ens)
- [Facebook](#facebook)
- [Farcaster](#farcaster)
- [Flickr](#flickr)
- [Gitee](#gitee)
- [GitHub](#github)
- [GitLab](#gitlab)
- [Goodreads](#goodreads)
- [Google](#google)
- [Google Play](#google-play)
- [Gravatar](#gravatar)
- [Gumroad](#gumroad)
- [Hevy](#hevy)
- [Hugging Face](#hugging-face)
- [Instagram](#instagram)
- [Juejin](#juejin)
- [Kaggle](#kaggle)
- [Keybase](#keybase)
- [Kick](#kick)
- [Ko-fi](#ko-fi)
- [Lemmy](#lemmy)
- [Libravatar](#libravatar)
- [LinkedIn](#linkedin)
- [Mastodon](#mastodon)
- [Matrix](#matrix)
- [Medium](#medium)
- [Microlink](#microlink)
- [Minecraft](#minecraft)
- [Mixcloud](#mixcloud)
- [NetEase Music](#netease-music)
- [note](#note)
- [npm](#npm)
- [OnlyFans](#onlyfans)
- [Open Collective](#open-collective)
- [OpenStreetMap](#openstreetmap)
- [osu!](#osu)
- [Patreon](#patreon)
- [PayPal](#paypal)
- [Pinterest](#pinterest)
- [Primal](#primal)
- [Printables](#printables)
- [Product Hunt](#product-hunt)
- [PSN Profiles](#psn-profiles)
- [QQ](#qq)
- [Raycast](#raycast)
- [Reddit](#reddit)
- [Revolut](#revolut)
- [Roblox](#roblox)
- [Sketchfab](#sketchfab)
- [Snapchat](#snapchat)
- [SoundCloud](#soundcloud)
- [Speedrun.com](#speedruncom)
- [Spotify](#spotify)
- [Stack Overflow](#stack-overflow)
- [Steam](#steam)
- [Strava](#strava)
- [Stripe](#stripe)
- [Substack](#substack)
- [Telegram](#telegram)
- [Thingiverse](#thingiverse)
- [Threads](#threads)
- [Tidal](#tidal)
- [Tieba](#tieba)
- [TikTok](#tiktok)
- [Tumblr](#tumblr)
- [Twitch](#twitch)
- [Venmo](#venmo)
- [Vimeo](#vimeo)
- [Wattpad](#wattpad)
- [Weibo](#weibo)
- [WhatsApp](#whatsapp)
- [Wise](#wise)
- [X/Twitter](#xtwitter)
- [Xbox Gamertag](#xbox-gamertag)
- [YouTube](#youtube)
- [Zhihu](#zhihu)
- [Response Format](#response-format)
- [Response Headers](#response-headers)
- [Response Errors](#response-errors)
- [Contact](#contact)
---
Last updated on October 5, 2026
## Introduction
**unavatar.io** retrieves anyone's avatar from a single URL — by username, email, or domain — across 99 platforms including [Instagram](https://unavatar.io/docs#instagram), [GitHub](https://unavatar.io/docs#github), [YouTube](https://unavatar.io/docs#youtube), [X/Twitter](https://unavatar.io/docs#xtwitter), and [Gravatar](https://unavatar.io/docs#gravatar). No API keys, no SDKs, free to start.
Try it: [unavatar.io/github/kikobeats](https://unavatar.io/github/kikobeats) · [unavatar.io/x/josebaseba](https://unavatar.io/x/josebaseba) · [unavatar.io/domain/reddit.com](https://unavatar.io/domain/reddit.com)
Everything you need to serve avatars at scale:
- **Versatile**: One endpoint rules 99 platforms and services — [TikTok](https://unavatar.io/docs#tiktok), [Instagram](https://unavatar.io/docs#instagram), [YouTube](https://unavatar.io/docs#youtube), [X/Twitter](https://unavatar.io/docs#xtwitter), [Gravatar](https://unavatar.io/docs#gravatar), and more — all queried the same way.
- **Battle-tested**: Already serving 2.96 TB of avatars across 226.5M requests, with a 70% cache hit rate.
- **Optimized**: Every image is compressed and optimized on-the-fly — smaller payloads at high quality, ready to drop straight into your site or app.
- **Integration**: Drops into any site or app with zero setup. Clear docs and full support make onboarding quick and painless.
It's proudly powered by [microlink.io](https://microlink.io/) , the headless browser API that handles all the heavy lifting behind the scenes to keep your avatars always ready.
## Quick start
The service is exposed in **unavatar.io** via endpoints.
An endpoint determines how the avatar is looked up and what parameters are required.
For example, you can get an avatar for:
- an **email**: [unavatar.io/email/hello@microlink.io](https://unavatar.io/email/hello@microlink.io)
- an **username**: [unavatar.io/github/kikobeats](https://unavatar.io/github/kikobeats)
- a **domain**: [unavatar.io/domain/reddit.com](https://unavatar.io/domain/reddit.com)
Read [providers](https://unavatar.io/docs#providers) to know more. Each provider can accept different parameters.
## Attribution
Free plans require attribution. Upgrade to any paid plan to remove this requirement.
Attribution ensures proper domain verification and helps us keep unavatar.io free for the community.
Your attribution link:
- Must be on your production site (not staging or localhost).
- Must be publicly accessible and viewable in browsers.
- Must not use rel="nofollow", redirects, or obfuscation.
### How to add attribution
Add this link on any page or surface displaying unavatar.io avatars:
```html
<ahref="https://unavatar.io">Avatars provided by Unavatar</a>
```
**Example**
```html
<imgsrc="https://unavatar.io/github/kikobeats"alt="Kiko"/>
<imgsrc="https://unavatar.io/x/josebaseba"alt="Joseba"/>
<pclass="attribution">
<ahref="https://unavatar.io">Avatars provided by Unavatar</a>
</p>
```
**Valid placements**
Site footer, about page, credits page, or any page that renders avatars.
**Mobile apps and non-web products**
If avatars are displayed in a mobile app, desktop app, browser extension, email, or any non-web surface, add the attribution link on your app's marketing site, app store listing description, or credits screen.
**Requirements for attribution to be valid**
We reserve the right to revoke free-tier access for any website or product that does not comply with the attribution requirements described in this document:
- Double-check the href. It must point to [https://unavatar.io](https://unavatar.io/) directly — no redirects, no URL shorteners, no tracking wrappers.
- Make sure it's crawlable. The link must be present in the rendered HTML and not blocked by robots.txt, authentication, or region gating.
- Avoid nofollow or noindex. We need a standard, followable link.
- target="\_blank" is allowed.
### Remove attribution
Attribution is only required on the free plan. [Upgrade to the PRO plan](https://unavatar.io/checkout) to remove the requirement.
## Authentication
Anonymous requests work without authentication. They are limited to 25 requests/day per IP address.
For [PRO](https://unavatar.io/checkout) users, the requests must include the API key as the `x-api-key` request header:
```html
<imgsrc="https://unavatar.io/github/kikobeats"/>
```
```bash
curl"https://unavatar.io/github/kikobeats"-H"x-api-key: YOUR_API_KEY"
```
```javascript
awaitfetch('https://unavatar.io/github/kikobeats',{
headers:{
'x-api-key':'YOUR_API_KEY'
}
})
```
```python
importrequests
response=requests.get(
'https://unavatar.io/github/kikobeats',
headers={'x-api-key':'YOUR_API_KEY'}
)
```
```golang
packagemain
import"net/http"
funcmain(){
req,_:=http.NewRequest("GET","https://unavatar.io/github/kikobeats",nil)
req.Header.Set("x-api-key","YOUR_API_KEY")
resp,_:=http.DefaultClient.Do(req)
deferresp.Body.Close()
}
```
```ruby
require'net/http'
require'uri'
uri=URI('https://unavatar.io/github/kikobeats')
request=Net::HTTP::Get.new(uri)
request['x-api-key']='YOUR_API_KEY'
response=Net::HTTP.start(uri.hostname,uri.port,use_ssl:true)do|http|
http.request(request)
end
```
```php
$ch=curl_init('https://unavatar.io/github/kikobeats');
curl_setopt($ch,CURLOPT_HTTPHEADER,[
'x-api-key: YOUR_API_KEY',
]);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
$response=curl_exec($ch);
curl_close($ch);
```
If the API key is invalid, the service returns `401` with code `EAPIKEY`.
Rate limit status can be verified using these response headers:
| Header | Description |
| ------------------------ | -------------------------------------------------------------- |
| `x-rate-limit-limit` | Maximum anonymous requests allowed in the current daily window |
| `x-rate-limit-remaining` | Requests remaining in the current window |
| `x-rate-limit-reset` | UTC epoch seconds when the current window resets |
```bash
curl-Ihttps://unavatar.io/github/kikobeats
x-rate-limit-limit:25
x-rate-limit-remaining:24
x-rate-limit-reset:1744243200
```
### Secret keys
Secret keys (`sk_`) are meant for server-side use only — never expose them publicly. They provide full access to all API operations: avatar lookups, key management, usage data, and billing.
Pass them via the `x-api-key` header:
```html
<imgsrc="https://unavatar.io/github/kikobeats"/>
```
```bash
curl"https://unavatar.io/github/kikobeats"-H"x-api-key: sk_YOUR_SECRET_KEY"
```
```javascript
awaitfetch('https://unavatar.io/github/kikobeats',{
headers:{
'x-api-key':'sk_YOUR_SECRET_KEY'
}
})
```
```python
importrequests
response=requests.get(
'https://unavatar.io/github/kikobeats',
headers={'x-api-key':'sk_YOUR_SECRET_KEY'}
)
```
```golang
packagemain
import"net/http"
funcmain(){
req,_:=http.NewRequest("GET","https://unavatar.io/github/kikobeats",nil)
req.Header.Set("x-api-key","sk_YOUR_SECRET_KEY")
resp,_:=http.DefaultClient.Do(req)
deferresp.Body.Close()
}
```
```ruby
require'net/http'
require'uri'
uri=URI('https://unavatar.io/github/kikobeats')
request=Net::HTTP::Get.new(uri)
request['x-api-key']='sk_YOUR_SECRET_KEY'
response=Net::HTTP.start(uri.hostname,uri.port,use_ssl:true)do|http|
http.request(request)
end
```
```php
$ch=curl_init('https://unavatar.io/github/kikobeats');
curl_setopt($ch,CURLOPT_HTTPHEADER,[
'x-api-key: sk_YOUR_SECRET_KEY',
]);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
$response=curl_exec($ch);
curl_close($ch);
```
### Publishable keys
Publishable keys (`pk_`) are safe to use in client-side code. They can **only** fetch avatars — any attempt to call management endpoints (key add/remove/rotate, usage, billing) returns an error.
Pass them as a `token` query parameter, which makes them easy to use directly in HTML markup:
```html
<imgsrc="https://unavatar.io/github/kikobeats?token=pk_YOUR_PUBLISHABLE_KEY"/>
```
### Domain restrictions
Publishable keys support optional domain restrictions to prevent unauthorized use. When domain restrictions are configured, requests with that publishable key are only accepted from matching `Origin` or `Referer` domains.
Domains can be managed from the [dashboard](https://unavatar.io/dashboard?tab=credentials). Valid values include:
- `example.com` — exact domain match
- `*.example.com` — all subdomains of example.com
- `app.example.com` — a specific subdomain
- `localhost` — local development, on any port
Only the hostname is compared, so ports, protocols and paths are ignored: `localhost:3000` and `http://localhost:3000` are both stored as `localhost`. `127.0.0.1` is a different hostname than `localhost`; add it as its own entry if you browse your local site that way.
`localhost` is never allowed implicitly. A key with domain restrictions rejects local requests with [`EPKDOMAIN`](https://unavatar.io/docs#response-errors) until you add it.
## Pricing
Unavatar pricing is simple: you can start on the anonymous free tier, then authenticate with `x-api-key` to get additional included usage and metered billing for higher volume.
| Scenario | Included free usage | Billing |
| -------------------------------------------- | ---------------------- | -------------------------------- |
| Anonymous (no API key) | 25 requests/day per IP | Free |
| Authenticated origin requests (`x-api-key`) | 50 origin requests/day | Metered monthly after free quota |
| Proxy requests (`datacenter`, `residential`) | None | Always metered |
For higher usage, the **[PRO](https://unavatar.io/checkout)** plan is usage-based billing that includes the 50 free daily origin requests, metered overage, and custom TTL.
Every request has a cost in tokens (**\$0.010 per token**) based on the proxy tier needed to resolve the avatar:
| Proxy tier | Tokens | Cost |
| ----------- | :----: | :-----: |
| Origin | 1 | \$0.010 |
| Datacenter | +2 | \$0.030 |
| Residential | +4 | \$0.050 |
The proxy tier used is returned in the `x-proxy-tier` response header, and the total cost in the `x-unavatar-cost` header.
```bash
curl-I-H"x-api-key: sk_YOUR_SECRET_KEY"https://unavatar.io/instagram/kikobeats
x-pricing-tier:pro
x-proxy-tier:origin
x-unavatar-cost:1
```
To upgrade, visit [unavatar.io/checkout](https://unavatar.io/checkout) . After completing the payment, you'll receive an API key.
## Cache
Unavatar caches avatar lookups to make repeated requests fast and stable:
- The first request for a resource fetches the avatar from upstream and stores it in cache
- Following requests are served from cache until the [TTL](https://unavatar.io/docs#ttl) expires.
For example, if you set `ttl=1h`, the cache behavior looks like this:
| Time | Request | Cache status | Plan impact |
| ----- | ----------------------- | ----------------------------------- | -------------------------- |
| 10:00 | `GET /github/kikobeats` | MISS (fetched from upstream) | Counts as 1 origin request |
| 10:05 | `GET /github/kikobeats` | HIT (served from cache) | No usage consumed, no cost |
| 10:40 | `GET /github/kikobeats` | HIT (served from cache) | No usage consumed, no cost |
| 11:02 | `GET /github/kikobeats` | MISS (TTL expired, cache refreshed) | Counts as 1 origin request |
| 11:10 | `GET /github/kikobeats` | HIT (served from cache) | No usage consumed, no cost |
To check the cache status in real requests, inspect these response headers:
| Header | What to look for |
| ---------------- | --------------------------------------------------------------------------------------- |
| `x-cache-status` | `HIT` means served from cache. `MISS` means fetched/refreshed from upstream. |
| `cache-control` | Shows cache policy and effective TTL (for example `public, max-age=3600` for `ttl=1h`). |
```bash
curl-I-H"x-api-key: sk_YOUR_SECRET_KEY""https://unavatar.io/github/kikobeats?ttl=1h"
cache-control:public,max-age=3600
x-cache-status:HIT
```
The same rule applies to anonymous requests: cache hits are free and do not consume the `25 requests/day` limit.
After TTL expiration, the next request refreshes the cache and is billed/rate-limited according to the request tier (`anonymous`, `origin`, `datacenter`, or `residential`).
## Query parameters
### TTL
Type: `number` or `string`\
Default: `'24h'`\
Range: from `'1h'` to `'28d'`
It determines the maximum quantity of time an avatar is considered fresh.
e.g., [unavatar.io/github/kikobeats?ttl=1h](https://unavatar.io/github/kikobeats?ttl=1h)
When you look up for a user avatar for the very first time, the service will determine it and cache it respecting TTL value.
The same resource will continue to be used until reach TTL expiration. After that, the resource will be computed, and cache as fresh, starting the cycle.
### Fallback
Type: `string` or `boolean`
When it can't be possible to get a user avatar, a fallback image is returned instead, and it can be personalized to fit better with your website or application style.
You can get one from **boringavatars.com**:
e.g., [unavatar.io/github/37t?fallback=https://source.boringavatars.com/marble/120/1337_user?colors=264653r,2a9d8f,e9c46a,f4a261,e76f51](https://unavatar.io/github/37t?fallback=https://source.boringavatars.com/marble/120/1337_user?colors=264653r,2a9d8f,e9c46a,f4a261,e76f51)
or **avatar.vercel.sh**:
e.g., [unavatar.io/github/37t?fallback=https://avatar.vercel.sh/37t?size=400](https://unavatar.io/github/37t?fallback=https://avatar.vercel.sh/37t?size=400)
or a static image:
e.g., [unavatar.io/github/37t?fallback=https://avatars.githubusercontent.com/u/66378906?v=4](https://unavatar.io/github/37t?fallback=https://avatars.githubusercontent.com/u/66378906?v=4)
or even a base64 encoded image. This allows you to return a transparent, base64 encoded 1x1 pixel GIF, which can be useful when you want to use your own background colour or image as a fallback.
e.g., [unavatar.io/github/37t?fallback=data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==](https://unavatar.io/github/37t?fallback=data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==)
You can pass `fallback=false` to explicitly disable this behavior. In this case, a *404 Not Found* HTTP status code will returned when is not possible to get the user avatar.
### Token
Type: `string`
Authenticates the request with a [publishable key](https://unavatar.io/docs#publishable-keys). This is an alternative to the `x-api-key` header, designed for contexts where headers cannot be set (e.g., `<img>` tags).
e.g., [unavatar.io/github/kikobeats?token=pk_YOUR_PUBLISHABLE_KEY](https://unavatar.io/github/kikobeats?token=pk_YOUR_PUBLISHABLE_KEY)
Secret keys (`sk_`) also work as a `token` value, but should only be passed via the `x-api-key` header to avoid exposing them in URLs.
### JSON
The service returns media content by default.
This makes the service easier to consume directly from HTML markup.
In case you want to get a JSON payload as response, just pass `json=true`:
e.g., [unavatar.io/github/kikobeats?json](https://unavatar.io/github/kikobeats?json)
## Providers
### Apple Music
Get artwork for any Apple Music artist, album, or song. Search by name or look up directly by numeric Apple Music ID.
The endpoint supports explicit type as part of the input.
If explicit type is not provided, it searches `artist` and `song` (in that order).
Available inputs:
- artist
- by artist name: [unavatar.io/apple-music/artist:daft%20punk](https://unavatar.io/apple-music/artist:daft%20punk)
- by numeric artist ID: [unavatar.io/apple-music/artist:5468295](https://unavatar.io/apple-music/artist:5468295)
- album
- by album name: [unavatar.io/apple-music/album:discovery](https://unavatar.io/apple-music/album:discovery)
- by album ID: [unavatar.io/apple-music/album:78691923](https://unavatar.io/apple-music/album:78691923)
- song
- by song name: [unavatar.io/apple-music/song:harder%20better%20faster%20stronger](https://unavatar.io/apple-music/song:harder%20better%20faster%20stronger)
- by song ID: [unavatar.io/apple-music/song:697195787](https://unavatar.io/apple-music/song:697195787)
### Apple Store
Get the icon for any iOS or macOS app on the App Store by 
