Musichoarders APIcovers.musichoarders.xyz ↗
Search album cover art from iTunes, Spotify, Deezer, and more. Returns cover URLs at custom pixel sizes with artist, album, and source metadata.
What is the Musichoarders API?
The covers.musichoarders.xyz API gives developers one endpoint — get_album_cover — to search for album artwork across multiple music platforms including iTunes, Spotify, and Deezer. A single POST request returns up to a full list of matching covers, each with a URL sized to exact pixel dimensions you specify, alongside release metadata and the source platform used to fulfill the query.
curl -X POST 'https://api.parse.bot/scraper/00786cd4-4b04-4ecd-913a-bf50eb64b49a/get_album_cover' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"album": "OK Computer",
"artist": "Radiohead",
"source": "itunes",
"country": "us",
"pixel_size": "1000"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace covers-musichoarders-xyz-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MusicHoarders SDK — find album cover art across music platforms."""
from parse_apis.Music_Hoarders_Cover_Art_API import MusicHoarders, Source, Country, InvalidInput
client = MusicHoarders()
# Search for album covers by artist + album, using iTunes Japan storefront
result = client.cover_results.search(
artist="Radiohead", album="OK Computer",
source=Source.ITUNES, country=Country.JAPAN, pixel_size=1000
)
print(f"Found {result.total} covers for '{result.artist_query} - {result.album_query}'")
# Access individual cover details
for cover in result.covers[:3]:
print(f" {cover.title} by {cover.artist} ({cover.date}) -> {cover.cover_url}")
# Search by album name only with a smaller pixel size
thriller = client.cover_results.search(album="Thriller", pixel_size=500)
print(f"\nThriller search: {thriller.total} results at {thriller.pixel_size}px")
first = thriller.covers[0]
print(f" Top result: {first.title} by {first.artist}, tracks: {first.tracks}")
# Typed error handling: catch invalid input
try:
client.cover_results.search()
except InvalidInput as exc:
print(f"\nExpected error (no artist/album): {exc}")
print("\nexercised: cover_results.search with artist+album / album-only / error handling")
Search for album cover art by artist name, album name, or both. Returns a list of matching covers with URLs sized to the requested pixel dimensions. At least one of artist or album must be provided. Results are sourced from the specified music platform and country storefront.
| Param | Type | Description |
|---|---|---|
| album | string | Album name to search for. At least one of artist or album must be provided. |
| artist | string | Artist name to search for. At least one of artist or album must be provided. |
| source | string | Music platform to search for covers. |
| country | string | Country storefront code for the search. |
| pixel_size | integer | Pixel dimensions for the cover image URL (width and height). Must be between 1 and 10000. |
{
"type": "object",
"fields": {
"total": "integer total number of covers found",
"covers": "array of cover results with URLs and release metadata",
"source": "string source platform used",
"country": "string country code used",
"pixel_size": "integer pixel size applied to cover URLs",
"album_query": "string album name that was searched",
"artist_query": "string artist name that was searched"
},
"sample": {
"data": {
"total": 16,
"covers": [
{
"date": "1997-05-21",
"title": "OK Computer",
"artist": "Radiohead",
"source": "itunes",
"tracks": 12,
"cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music116/v4/07/60/ba/0760ba0f-148c-b18f-d0ff-169ee96f3af5/634904078164.png/1000x1000w-999.jpg",
"source_url": "https://music.apple.com/jp/album/1097861387",
"original_url": "https://a1.mzstatic.com/r40/Music116/v4/07/60/ba/0760ba0f-148c-b18f-d0ff-169ee96f3af5/634904078164.png"
}
],
"source": "itunes",
"country": "jp",
"pixel_size": 1000,
"album_query": "OK Computer",
"artist_query": "Radiohead"
},
"status": "success"
}
}About the Musichoarders API
What the API Returns
The get_album_cover endpoint accepts an artist name, an album name, or both, and returns a covers array containing image URLs and release metadata. Each response also echoes back the source platform, country storefront code, pixel_size applied to the URLs, artist_query, album_query, and a total count of results found. At least one of artist or album must be provided per request.
Controlling Image Size and Source
The pixel_size parameter accepts any integer from 1 to 10000, and the returned cover URLs are sized to that exact square dimension — useful when you need artwork at a specific resolution for UI rendering, print, or archival. The source parameter lets you target a specific music platform (e.g., iTunes, Spotify, Deezer), and country accepts a storefront code to scope results to a regional catalog, which matters when releases differ by territory.
Response Shape
The response is flat and predictable: total tells you how many covers matched, covers holds the array of result objects with image URLs and metadata, and the remaining fields (source, country, pixel_size, album_query, artist_query) confirm exactly what query parameters were applied. There is no pagination parameter exposed — total reflects the full result set returned in one response.
The Musichoarders API is a managed, monitored endpoint for covers.musichoarders.xyz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when covers.musichoarders.xyz changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official covers.musichoarders.xyz API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Populate album artwork in a music library or media player app using exact-resolution cover URLs from
pixel_size. - Build a cross-platform cover art comparison tool by querying the same artist and album against different
sourcevalues. - Fetch region-specific cover variants by changing the
countrystorefront code for releases with territory-exclusive artwork. - Auto-fill missing artwork in a music tagging or metadata management tool using
artistandalbumqueries. - Display correctly sized cover images in a responsive web UI by requesting the exact
pixel_sizeyour layout needs. - Audit cover art consistency across storefronts for a label or distributor's catalog.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does covers.musichoarders.xyz have an official developer API?+
What does the `covers` array in the response actually contain?+
covers array holds result objects that include the cover image URL (sized to your requested pixel_size) and release metadata associated with the match. The response also includes total (how many covers were found), source, country, album_query, and artist_query so you can confirm what was searched and where.Does the API support pagination or fetching more than the default result set?+
get_album_cover endpoint returns all matched results in a single response — there is no page, offset, or limit parameter available. The total field reflects the full count returned in that one call. You can fork this API on Parse and revise it to add pagination parameters if you need to page through large result sets.Can I retrieve audio previews, track listings, or other album metadata beyond cover art?+
covers array — it does not expose track listings, audio previews, release dates, or genre data. You can fork it on Parse and revise it to add endpoints that surface those additional fields.Does the `country` parameter affect which covers are returned?+
country to a specific storefront code can change which releases and cover variants are returned. If omitted, the API uses a default country. For releases with territory-specific artwork or regional editions, specifying country explicitly gives more accurate results.