Single lookup

GET/api/v1/metadata/album-cover

Album cover art + album/recording metadata for one asset, looked up by identifier.

Query parameters#

Provide at least one identifier, or title and writer, or title and artist with allow_title_fallback=true.

Send everything you have. When you send both isrc and iswc, they cross-check each other. See matched.confirmed and identifier_conflict. A title and artist let us tell you when a bad statement ISRC resolved to the wrong asset.

Verification (recommended for catching bad ISRCs). Pass the title and artist from your statement alongside the identifier. We resolve by identifier as usual, then compare our resolved metadata to what you sent and return a verification block. When both your title and artist disagree with the resolved asset, we add a metadata_mismatch warning, the strong signal that the statement ISRC is wrong. We only warn when both disagree, so a writer-vs-performer name difference or a formatting quirk will not false-alarm.

Title and writer, for rows with no identifier. You pass a title and one or more writer names, and no identifier resolves. We then resolve the composition by title corroborated by a writer, never by title alone. We return the cover from that work's recordings.

We flag such a result via: "title_writer" and confidence: "low". It suits a source like ASCAP that carries a composer and a title, but no ISRC, ISWC or performing artist.

Title-search fallback. Opt-in, low confidence, covers only. By default this endpoint uses identifiers only. A closest match by title is exactly the failure that produces a wrong cover.

Pass allow_title_fallback=true with a title and artist, and we search by artist and title when no identifier resolves. We return a cover only when the match is unambiguous, meaning exactly one recording matches. Anything ambiguous returns a 404 rather than a guess.

We flag such a result via: "title_search" and confidence: "low", with a title_search_fallback warning. Treat it as best effort, not as authority.

Response (200)#

{
  "schema_version": "1.0",
  "cover": {
    "url": "https://...mzstatic.com/.../1400x1400bb.jpg",
    "url_template": "https://...mzstatic.com/.../{w}x{h}bb.jpg",
    "source": "apple"
  },
  "song": {
    "title": "Black Sheep",
    "duration_ms": 183000,
    "track_number": 3,
    "preview_url": "https://...",
    "apple_music_url": "https://music.apple.com/..."
  },
  "album": {
    "name": "Original Album",
    "release_date": "2021-03-19",
    "artist_name": "Kng Ego",
    "genres": ["Hip-Hop/Rap"],
    "label": "Label Records",
    "upc": "0001112223334",
    "album_type": "Album"
  },
  "matched": {
    "via": "isrc",
    "isrc": "USRC12345678",
    "iswc": "T-123.456.789-0",
    "apple_album_id": "1440857781",
    "confirmed": true,
    "confidence": "high"
  },
  "verification": {
    "supplied_title": "Black Sheep",
    "supplied_artist": "Kng Ego",
    "supplied_album": null,
    "resolved_title": "Black Sheep",
    "resolved_artist": "Kng Ego",
    "resolved_album": "Original Album",
    "title_match": true,
    "artist_match": true,
    "verdict": "match"
  },
  "warnings": []
}

Field notes:

• cover.url is a public Apple CDN link (1400x1400). cover.url_template contains literal {w}x{h} placeholders; substitute any size you need. Fetch and store on your side; we serve links, not image bytes.
• Cover choice is deterministic: the song's own album, preferring the earliest artwork-bearing release (the original release). This replaces the "latest released" heuristic that picks re-releases and compilations.
• song carries recording-level extras Apple gives us on the same lookup (duration, track number, a short audio preview URL, the Apple Music page).
• matched tells you how the asset was identified. via is the identifier that anchored the result (title_writer for a title + writer resolution, or title_search for the opt-in fallback). confirmed: true means two independent identifiers (ISRC and ISWC) agreed. confidence is high for an identifier resolution and low for a title_writer or title_search result.
• verification appears only when you pass title/artist/album. verdict reflects the fields you supplied: match (all agree), mismatch (all disagree), partial (mixed, only when you supply both title and artist). The actionable signal is the metadata_mismatch warning, raised only when you supplied both a title and an artist and both disagree, so a title-only or artist-only request can read verdict: mismatch without the warning.
• warnings surface degraded-but-servable outcomes instead of hiding them:
  • identifier_conflict: your ISRC and ISWC point at different works, or an unconfirmed ISRC result conflicts with the title evidence you supplied. We anchor on the ISWC (work-level identity is the trustworthy one when statements carry bad ISRCs) and tell you, so you can flag the statement row.
  • metadata_mismatch: your supplied title AND artist both disagree with the resolved asset, a likely wrong statement ISRC. The cover is still returned; treat it as suspect.
  • title_search_fallback: the result came from the opt-in low-confidence artist+title search, not an identifier. Best-effort, not authoritative.
  • artwork_unavailable: the asset resolved but we hold no cover; metadata fields are still populated where known.
  • isrc_invalid_ignored / iswc_invalid_ignored: one identifier was malformed; we proceeded on the valid one.
  • iswc_unmatched: the ISWC is unknown to us; the result is ISRC-anchored.
• Missing values are explicit nulls, never invented. "Unknown Artist" will never appear.
• Identifier-only 200 responses are publicly cacheable for a day: Cache-Control: public, max-age=86400. Responses that include supplied verification or fallback fields are private-cacheable for a day: Cache-Control: private, max-age=86400.

Error responses#

Quickstart#

# By ISRC
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/album-cover?isrc=USRC12345678"

# By ISWC only (no ISRC needed: this is the lookup ACRCloud could not do)
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/album-cover?iswc=T-123.456.789-0"

# Both: the identifiers cross-check each other; watch matched.confirmed / warnings
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/album-cover?isrc=USRC12345678&iswc=T-123.456.789-0"