@unavatar/core 3.71.1 → 3.71.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -56
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -95,11 +95,12 @@
95
95
  - [Sketchfab](#sketchfab)
96
96
  - [Snapchat](#snapchat)
97
97
  - [SoundCloud](#soundcloud)
98
- - [Speedrun](#speedrun)
98
+ - [Speedrun.com](#speedruncom)
99
99
  - [Spotify](#spotify)
100
100
  - [Stack Overflow](#stack-overflow)
101
101
  - [Steam](#steam)
102
102
  - [Strava](#strava)
103
+ - [Stripe](#stripe)
103
104
  - [Substack](#substack)
104
105
  - [Telegram](#telegram)
105
106
  - [Thingiverse](#thingiverse)
@@ -126,21 +127,21 @@
126
127
 
127
128
  ---
128
129
 
129
- Last updated on August 19, 2026
130
+ Last updated on October 5, 2026
130
131
 
131
132
  ![logo](https://unavatar.io/api/og ":id=banner")
132
133
 
133
134
  ## Introduction
134
135
 
135
- **unavatar.io** retrieves anyone's avatar from a single URL — by username, email, or domain — across 74 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.
136
+ **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.
136
137
 
137
138
  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)
138
139
 
139
140
  Everything you need to serve avatars at scale:
140
141
 
141
- - **Versatile**: One endpoint rules 74 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.
142
+ - **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.
142
143
 
143
- - **Battle-tested**: Already serving 2.77 TB of avatars across 189.4M requests, with a 70% cache hit rate.
144
+ - **Battle-tested**: Already serving 2.96 TB of avatars across 226.5M requests, with a 70% cache hit rate.
144
145
 
145
146
  - **Optimized**: Every image is compressed and optimized on-the-fly — smaller payloads at high quality, ready to drop straight into your site or app.
146
147
 
@@ -437,6 +438,11 @@ Domains can be managed from the [dashboard](https://unavatar.io/dashboard?tab=cr
437
438
  - `example.com` — exact domain match
438
439
  - `*.example.com` — all subdomains of example.com
439
440
  - `app.example.com` — a specific subdomain
441
+ - `localhost` — local development, on any port
442
+
443
+ 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.
444
+
445
+ `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.
440
446
 
441
447
  ## Pricing
442
448
 
@@ -626,7 +632,7 @@ Available inputs:
626
632
 
627
633
  ### Bitbucket
628
634
 
629
- Get any Bitbucket workspace's avatar by its workspace slug. Personal accounts are covered through their personal workspace, which shares the account's username.
635
+ Get any Bitbucket workspace's avatar by its workspace slug, which matches the owner's username.
630
636
 
631
637
  e.g., [unavatar.io/bitbucket/atlassian](https://unavatar.io/bitbucket/atlassian)
632
638
 
@@ -683,7 +689,7 @@ e.g., [unavatar.io/cursor/leerob](https://unavatar.io/cursor/leerob)
683
689
 
684
690
  ### Dailymotion
685
691
 
686
- Get any Dailymotion user's profile picture by their username or user ID.
692
+ Get any Dailymotion user's or channel's avatar by their username.
687
693
 
688
694
  e.g., [unavatar.io/dailymotion/dailymotion](https://unavatar.io/dailymotion/dailymotion)
689
695
 
@@ -704,9 +710,12 @@ Available inputs:
704
710
 
705
711
  ### DEV
706
712
 
707
- Get any [DEV](https://dev.to) user's profile picture by username, or an organization's logo by its slug.
713
+ Get any DEV Community member's or organization's profile picture by their username or organization slug.
708
714
 
709
- e.g., [unavatar.io/devto/ben](https://unavatar.io/devto/ben)
715
+ Available inputs:
716
+
717
+ - Username, e.g., [unavatar.io/devto/ben](https://unavatar.io/devto/ben)
718
+ - Organization, e.g., [unavatar.io/devto/devteam](https://unavatar.io/devto/devteam)
710
719
 
711
720
  ### DeviantArt
712
721
 
@@ -749,19 +758,19 @@ e.g., [unavatar.io/duckduckgo/microsoft.com](https://unavatar.io/duckduckgo/micr
749
758
 
750
759
  ### Duolingo
751
760
 
752
- Get any Duolingo learner's profile picture by their username.
761
+ Get any Duolingo learner's avatar by their username.
753
762
 
754
763
  e.g., [unavatar.io/duolingo/luis](https://unavatar.io/duolingo/luis)
755
764
 
756
765
  ### Email
757
766
 
758
- Resolve user avatars from an email address with a single URL. The `/email/:key` route uses the same provider chain as a bare `/user@domain` path: the service tries Gravatar and GitHub, then Libravatar, then BIMI until one returns an image. No API keys and no SDK are required.
767
+ Resolve user avatars from an email address with a single URL. The `/email/:key` route uses the same provider chain as a bare `/user@domain` path: the service tries Gravatar, GitHub, Libravatar, BIMI in order until one returns an image. No API keys and no SDK are required.
759
768
 
760
769
  When the path looks like an email, unavatar walks that chain until a provider succeeds. You can also skip the chain and call a named email provider directly when you know where the avatar should come from.
761
770
 
762
771
  Automatic resolution
763
772
 
764
- Pass the address as the only path segment, or prefix it with `email/`. The API auto-detects email-shaped inputs and runs the same chain (Gravatar and GitHub, then Libravatar, then BIMI).
773
+ Pass the address as the only path segment, or prefix it with `email/`. The API auto-detects email-shaped inputs and runs the same chain (Gravatar, GitHub, Libravatar, BIMI).
765
774
 
766
775
  - Typed route `unavatar.io/email/{email}`: [unavatar.io/email/hello@microlink.io](https://unavatar.io/email/hello@microlink.io)
767
776
  - Bare path `unavatar.io/{email}`: [unavatar.io/hello@microlink.io](https://unavatar.io/hello@microlink.io)
@@ -772,18 +781,18 @@ Target a specific provider when you know where the avatar comes from.
772
781
 
773
782
  - Gravatar (`unavatar.io/gravatar/{email-or-hash}`) — email is normalized and SHA-256 hashed; 64-hex SHA-256 or 32-hex MD5 passes through. Example: [unavatar.io/gravatar/hello@microlink.io](https://unavatar.io/gravatar/hello@microlink.io)
774
783
  - GitHub (`unavatar.io/github/{email}`) — public profile email or commit history: [unavatar.io/github/sindresorhus@gmail.com](https://unavatar.io/github/sindresorhus@gmail.com)
775
- - Libravatar (`unavatar.io/libravatar/{email-or-hash}`) — federated Gravatar alternative; follows the email domain's own avatar server when it publishes one: [unavatar.io/libravatar/francois@fmarier.org](https://unavatar.io/libravatar/francois@fmarier.org)
776
784
  - BIMI (`unavatar.io/bimi/{email}`) — official brand logo from the address domain: [unavatar.io/bimi/support@ebay.com](https://unavatar.io/bimi/support@ebay.com)
777
785
 
778
786
  e.g., [unavatar.io/email/hello@microlink.io](https://unavatar.io/email/hello@microlink.io)
779
787
 
780
788
  ### ENS
781
789
 
782
- Get the avatar set on any Ethereum Name Service (ENS) name, including subnames like `jesse.base.eth`. A bare label is treated as a `.eth` name.
790
+ Get the avatar record of any ENS name, including `.base.eth` subnames. A bare label resolves as a `.eth` name, and `.eth` inputs are detected automatically without the provider prefix.
783
791
 
784
- e.g., [unavatar.io/ens/vitalik.eth](https://unavatar.io/ens/vitalik.eth)
792
+ Available inputs:
785
793
 
786
- Names ending in `.eth` are detected automatically, so [unavatar.io/vitalik.eth](https://unavatar.io/vitalik.eth) resolves through ENS too.
794
+ - ENS name, e.g., [unavatar.io/ens/vitalik.eth](https://unavatar.io/ens/vitalik.eth)
795
+ - Subname, e.g., [unavatar.io/ens/jesse.base.eth](https://unavatar.io/ens/jesse.base.eth)
787
796
 
788
797
  ### Facebook
789
798
 
@@ -796,12 +805,9 @@ Available inputs:
796
805
 
797
806
  ### Farcaster
798
807
 
799
- Get any Farcaster user's profile picture by their username (fname). ENS-style usernames are supported.
808
+ Get any Farcaster user's profile picture by their username.
800
809
 
801
- Available inputs:
802
-
803
- - Username, e.g., [unavatar.io/farcaster/dwr](https://unavatar.io/farcaster/dwr)
804
- - ENS username, e.g., [unavatar.io/farcaster/vitalik.eth](https://unavatar.io/farcaster/vitalik.eth)
810
+ e.g., [unavatar.io/farcaster/dwr](https://unavatar.io/farcaster/dwr)
805
811
 
806
812
  ### Flickr
807
813
 
@@ -843,16 +849,15 @@ Available inputs:
843
849
 
844
850
  ### Goodreads
845
851
 
846
- Get any Goodreads user's profile picture by their vanity username or numeric user ID, or an author's photo by their author ID.
852
+ Get any Goodreads reader's or author's photo by username, user ID, or author ID.
847
853
 
848
854
  The input supports a URI format `type:id`.
849
855
 
850
- When no type is provided, the input is treated as a user (`user`).
856
+ When no type is provided, it defaults to `user`.
851
857
 
852
858
  Available inputs:
853
859
 
854
- - `user` (default), by username: [unavatar.io/goodreads/otis](https://unavatar.io/goodreads/otis)
855
- - `user` (default), by user ID: [unavatar.io/goodreads/1](https://unavatar.io/goodreads/1)
860
+ - `user` (default): [unavatar.io/goodreads/otis](https://unavatar.io/goodreads/otis) or [unavatar.io/goodreads/1](https://unavatar.io/goodreads/1)
856
861
  - `author`: [unavatar.io/goodreads/author:4](https://unavatar.io/goodreads/author:4)
857
862
 
858
863
  ### Google
@@ -886,11 +891,11 @@ Available inputs:
886
891
 
887
892
  When you pass an email address directly in the URL, it is visible in plain text — both in server logs and to any intermediary that inspects the request.
888
893
 
889
- To avoid this, pass a pre-computed `MD5` or `SHA256` hash of the email instead. Unavatar detects the hash automatically and routes it to Gravatar, then Libravatar, which both natively support both hash formats.
894
+ To avoid this, pass a pre-computed `MD5` or `SHA256` hash of the email instead. Unavatar detects the hash automatically and routes it to Gravatar, which natively supports both hash formats.
890
895
 
891
896
  ### Gumroad
892
897
 
893
- Get any Gumroad creator's profile picture by their username (the subdomain of their store).
898
+ Get any Gumroad creator's profile picture by their username.
894
899
 
895
900
  e.g., [unavatar.io/gumroad/sahil](https://unavatar.io/gumroad/sahil)
896
901
 
@@ -947,23 +952,18 @@ e.g., [unavatar.io/ko-fi/geekshock](https://unavatar.io/ko-fi/geekshock)
947
952
 
948
953
  ### Lemmy
949
954
 
950
- Get any Lemmy user's profile picture from any instance using the public user API. Pass the handle as `user@instance` so the account resolves on the correct home instance.
955
+ Get any Lemmy user's avatar from their home instance by their `user@instance` handle.
951
956
 
952
957
  e.g., [unavatar.io/lemmy/ruud@lemmy.world](https://unavatar.io/lemmy/ruud@lemmy.world)
953
958
 
954
959
  ### Libravatar
955
960
 
956
- Resolve avatars via [Libravatar](https://www.libravatar.org), the federated, open source alternative to Gravatar, using a plain email or a precomputed hash. Emails are trimmed, lowercased, and hashed with SHA-256; 64-hex SHA-256 and 32-hex MD5 values are passed through (normalized to lowercase).
961
+ Resolve avatars via Libravatar, the federated open-source avatar service, using an email or a precomputed MD5 or SHA-256 hash. Emails on domains that run their own Libravatar server are resolved from that server.
957
962
 
958
963
  Available inputs:
959
964
 
960
- - Email address, e.g., [unavatar.io/libravatar/francois@fmarier.org](https://unavatar.io/libravatar/francois@fmarier.org)
961
- - SHA-256 hash, e.g., [unavatar.io/libravatar/857915e8681217376523fa2c4653a499a7dc6826197b077d35fc029d7c38bda1](https://unavatar.io/libravatar/857915e8681217376523fa2c4653a499a7dc6826197b077d35fc029d7c38bda1)
962
965
  - MD5 hash, e.g., [unavatar.io/libravatar/7cc352a2907216992f0f16d2af50b070](https://unavatar.io/libravatar/7cc352a2907216992f0f16d2af50b070)
963
-
964
- When an email domain runs its own avatar server and publishes a `_avatars-sec._tcp` SRV record, the avatar is fetched from that server. Otherwise, and always for hashes, the central `seccdn.libravatar.org` server is used.
965
-
966
- In the email chain, Libravatar runs only after Gravatar and GitHub miss, so it never overrides or slows down a Gravatar hit.
966
+ - SHA-256 hash, e.g., [unavatar.io/libravatar/857915e8681217376523fa2c4653a499a7dc6826197b077d35fc029d7c38bda1](https://unavatar.io/libravatar/857915e8681217376523fa2c4653a499a7dc6826197b077d35fc029d7c38bda1)
967
967
 
968
968
  ### LinkedIn
969
969
 
@@ -984,7 +984,7 @@ e.g., [unavatar.io/mastodon/kpwags@hachyderm.io](https://unavatar.io/mastodon/kp
984
984
 
985
985
  ### Matrix
986
986
 
987
- Get any Matrix user's profile picture from any homeserver using the public profile API. Pass the full user ID as `@user:server` (the leading `@` is optional); a bare `user` resolves on `matrix.org`. Homeservers that require authentication for profiles or media return no avatar.
987
+ Get any Matrix user's avatar by their Matrix ID, resolved from their homeserver.
988
988
 
989
989
  e.g., [unavatar.io/matrix/@matthew:matrix.org](https://unavatar.io/matrix/@matthew:matrix.org)
990
990
 
@@ -1002,12 +1002,12 @@ e.g., [unavatar.io/microlink/microlink.io](https://unavatar.io/microlink/microli
1002
1002
 
1003
1003
  ### Minecraft
1004
1004
 
1005
- Get any Minecraft Java Edition player's face by their username or UUID. The player is resolved through Mojang first, so unknown players return no avatar, and the face is rendered by [mc-heads.net](https://mc-heads.net).
1005
+ Get any Minecraft Java Edition player's face by their username or UUID.
1006
1006
 
1007
1007
  Available inputs:
1008
1008
 
1009
1009
  - Username, e.g., [unavatar.io/minecraft/notch](https://unavatar.io/minecraft/notch)
1010
- - UUID, with or without dashes, e.g., [unavatar.io/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5](https://unavatar.io/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5)
1010
+ - UUID, e.g., [unavatar.io/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5](https://unavatar.io/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5)
1011
1011
 
1012
1012
  ### Mixcloud
1013
1013
 
@@ -1023,7 +1023,7 @@ e.g., [unavatar.io/netease-music/32953014](https://unavatar.io/netease-music/329
1023
1023
 
1024
1024
  ### note
1025
1025
 
1026
- Get any note.com creator's profile picture by their username.
1026
+ Get any note creator's profile picture by their note ID.
1027
1027
 
1028
1028
  e.g., [unavatar.io/note/info](https://unavatar.io/note/info)
1029
1029
 
@@ -1041,7 +1041,7 @@ e.g., [unavatar.io/onlyfans/amandaribas](https://unavatar.io/onlyfans/amandariba
1041
1041
 
1042
1042
  ### Open Collective
1043
1043
 
1044
- Get any Open Collective account's avatar by its profile slug, for collectives, organizations, and individuals.
1044
+ Get any Open Collective account's avatar by its slug, for collectives, organizations, and individuals.
1045
1045
 
1046
1046
  e.g., [unavatar.io/opencollective/webpack](https://unavatar.io/opencollective/webpack)
1047
1047
 
@@ -1056,12 +1056,12 @@ Available inputs:
1056
1056
 
1057
1057
  ### osu!
1058
1058
 
1059
- Get any osu! player's profile picture by their username or numeric user ID.
1059
+ Get any osu! player's profile picture by their username or user ID.
1060
1060
 
1061
1061
  Available inputs:
1062
1062
 
1063
1063
  - Username, e.g., [unavatar.io/osu/peppy](https://unavatar.io/osu/peppy)
1064
- - Numeric user ID, e.g., [unavatar.io/osu/7562902](https://unavatar.io/osu/7562902)
1064
+ - User ID, e.g., [unavatar.io/osu/7562902](https://unavatar.io/osu/7562902)
1065
1065
 
1066
1066
  ### Patreon
1067
1067
 
@@ -1141,12 +1141,16 @@ e.g., [unavatar.io/revolut/midudev](https://unavatar.io/revolut/midudev)
1141
1141
 
1142
1142
  ### Roblox
1143
1143
 
1144
- Get any Roblox user's avatar headshot by their username or user ID.
1144
+ Get any Roblox player's avatar headshot by username or user ID.
1145
+
1146
+ The input supports a URI format `type:id`.
1147
+
1148
+ When no type is provided, it defaults to `username`.
1145
1149
 
1146
1150
  Available inputs:
1147
1151
 
1148
- - Username, e.g., [unavatar.io/roblox/builderman](https://unavatar.io/roblox/builderman)
1149
- - User ID, e.g., [unavatar.io/roblox/id:156](https://unavatar.io/roblox/id:156)
1152
+ - `username` (default): [unavatar.io/roblox/builderman](https://unavatar.io/roblox/builderman)
1153
+ - `id`: [unavatar.io/roblox/id:156](https://unavatar.io/roblox/id:156)
1150
1154
 
1151
1155
  ### Sketchfab
1152
1156
 
@@ -1166,9 +1170,9 @@ Get any SoundCloud artist's profile picture by their username.
1166
1170
 
1167
1171
  e.g., [unavatar.io/soundcloud/gorillaz](https://unavatar.io/soundcloud/gorillaz)
1168
1172
 
1169
- ### Speedrun
1173
+ ### Speedrun.com
1170
1174
 
1171
- Get any Speedrun.com runner's profile picture by their username or user ID.
1175
+ Get any Speedrun.com runner's profile picture by their username.
1172
1176
 
1173
1177
  e.g., [unavatar.io/speedrun/cheese](https://unavatar.io/speedrun/cheese)
1174
1178
 
@@ -1216,6 +1220,12 @@ Get any Strava athlete's profile picture by their username or athlete ID.
1216
1220
 
1217
1221
  e.g., [unavatar.io/strava/kikobeats](https://unavatar.io/strava/kikobeats)
1218
1222
 
1223
+ ### Stripe
1224
+
1225
+ Get any Stripe user's profile picture by their username.
1226
+
1227
+ e.g., [unavatar.io/stripe/levelsio](https://unavatar.io/stripe/levelsio)
1228
+
1219
1229
  ### Substack
1220
1230
 
1221
1231
  Get any Substack author's profile picture by their publication username.
@@ -1292,7 +1302,7 @@ e.g., [unavatar.io/vimeo/ladieswithlenses](https://unavatar.io/vimeo/ladieswithl
1292
1302
 
1293
1303
  ### Wattpad
1294
1304
 
1295
- Get any Wattpad user's profile picture by their username.
1305
+ Get any Wattpad writer's profile picture by their username.
1296
1306
 
1297
1307
  e.g., [unavatar.io/wattpad/Wattpad](https://unavatar.io/wattpad/Wattpad)
1298
1308
 
@@ -1364,14 +1374,14 @@ However, you can get a [json](https://unavatar.io/docs#json) as response payload
1364
1374
 
1365
1375
  When an endpoint returns JSON, the shape is predictable so you can parse it reliably in your app:
1366
1376
 
1367
- | Field | Type | Present in | Description |
1368
- | --------- | -------------- | ------------------------------- | ------------------------------------------------ |
1369
- | `status` | `string` | all JSON responses | One of: `success`, `fail`, `error`. |
1370
- | `message` | `string` | all JSON responses | Human-readable summary for display/logging. |
1371
- | `data` | `object` | `success` | Response payload for successful requests. |
1372
- | `code` | `string` | `fail`, `error` | Stable machine-readable error code. |
1373
- | `more` | `string (URL)` | most `fail` / `error` responses | Documentation URL with troubleshooting details. |
1374
- | `report` | `string` | some `error` responses | Support contact channel (for example `mailto:`). |
1377
+ | Field | Type | Present in | Description |
1378
+ | --------- | -------------- | ----------------------------- | ------------------------------------------------ |
1379
+ | `status` | `string` | all JSON responses | One of: `success`, `fail`, `error`. |
1380
+ | `message` | `string` | all JSON responses | Human-readable summary for display/logging. |
1381
+ | `data` | `object` | `success` | Response payload for successful requests. |
1382
+ | `code` | `string` | `fail`, `error` | Stable machine-readable error code. |
1383
+ | `more` | `string (URL)` | most `fail`/`error` responses | Documentation URL with troubleshooting details. |
1384
+ | `report` | `string` | some `error` responses | Support contact channel (for example `mailto:`). |
1375
1385
 
1376
1386
  ## Response Headers
1377
1387
 
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@unavatar/core",
3
3
  "description": "Get unified user avatar from social networks, including Instagram, SoundCloud, Telegram, Twitter, YouTube & more.",
4
4
  "homepage": "https://unavatar.io",
5
- "version": "3.71.1",
5
+ "version": "3.71.3",
6
6
  "main": "src/index.js",
7
7
  "exports": {
8
8
  ".": "./src/index.js",