Put a Apple Music Handle in the URL and the response is the artist, album, or song artwork as image bytes, ready for an <img src>. avatarapi fetches it from Apple Music, checks it is a real image, and caches it at the edge.
<img src="https://avatarsapi.com/apple-music/artist%3ATaylor%20Swift" alt="">
What goes in the URL
https://avatarsapi.com/apple-music/<handle>
An artist name, or artist:, album:, or song: followed by a name or numeric Apple Music id.
A bare name searches artists, then songs, then albums.
Percent-encode the Handle if it contains a /, a space, or other reserved characters.
Options
?size=16..1000sets the square size in pixels (default 400):https://avatarsapi.com/apple-music/artist%3ATaylor%20Swift?size=64?jsonreturns the resolved image URL instead of the bytes:
{ "version": 1, "data": { "url": "https://…", "source": "apple-music", "kind": "username" } }
Starter Projects can also set ?ttl=1h..28d for the cache lifetime (default 7 days).
When there is no picture
If the account does not exist or has no artist, album, or song artwork, the response is a 404 with a JSON body whose code is ENOTFOUND. That makes onerror a reliable fallback:
<img
src="https://avatarsapi.com/apple-music/artist%3ATaylor%20Swift"
onerror="this.onerror=null; this.src='/default-avatar.svg'"
alt="">
EUPSTREAM (502) means Apple Music itself failed or changed; it is usually transient. All codes are in the error table.