Spotify profile picture or artwork API

Put a Spotify Handle in the URL and the response is the profile picture or artwork as image bytes, ready for an <img src>. avatarapi fetches it from Spotify, checks it is a real image, and caches it at the edge.

<img src="https://avatarsapi.com/spotify/artist%3A06HL4z0CvFAxyc27GXpf02" alt="">

What goes in the URL

https://avatarsapi.com/spotify/<handle>

A user id (default), or artist:, album:, playlist:, or show: plus a Spotify id.

Currently failing. Spotify lookups are failing right now while we fix this Source. Ship a fallback.

Percent-encode the Handle if it contains a /, a space, or other reserved characters.

Options

?size=16..1000 sets the square size in pixels (default 400): https://avatarsapi.com/spotify/artist%3A06HL4z0CvFAxyc27GXpf02?size=64
?json returns the resolved image URL instead of the bytes:

{ "version": 1, "data": { "url": "https://…", "source": "spotify", "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 profile picture or 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/spotify/artist%3A06HL4z0CvFAxyc27GXpf02"
  onerror="this.onerror=null; this.src='/default-avatar.svg'"
  alt="">

EUPSTREAM (502) means Spotify itself failed or changed; it is usually transient. All codes are in the error table.

What goes in the URL

Options

When there is no picture

Related