Deezer metadata block

The deezer block attaches Deezer’s own metadata for the recognized recording to the match. It mirrors a Deezer API track object, so you get the Deezer track link, an MP3 preview, a nested album with cover-art URLs, and numeric IDs without a second call. It is present only when you request it — and only when Deezer has a match for the recording.

How to request it

In the SDKs, list the provider in the return_metadata option (Python) / returnMetadata (Node):

from audd import AudD

audd = AudD("your-api-token")  # dashboard.audd.io
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["deezer"],
)

import { AudD } from "@audd/sdk";

const audd = new AudD({ apiToken: "your-api-token" }); // dashboard.audd.io
const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["deezer"],
});

In raw curl, the form field is named return (the SDK option above is the SDK name for the same thing):

curl https://api.audd.io/ \
  -F api_token=your-api-token \
  -F url=https://audd.tech/example.mp3 \
  -F return=deezer

How to access it

The block is the typed deezer property on the result, and its sub-fields are typed attributes on that model — attribute access, not dict subscripts. Fields beyond the typed ones — preview, the nested album with cover-art URLs, artist — round-trip through Pydantic’s model_extra in Python / extras in Node.

result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["deezer"],
)
dz = result.deezer                      # None if not requested / no Deezer match
if dz:
    page = dz.link                      # Deezer page for the track
    title = dz.title
    extra = dz.model_extra or {}
    preview = extra.get("preview")      # 30s MP3 preview
    album = extra.get("album") or {}
    cover = album.get("cover_big")      # album cover-art URL

const dz = result.deezer;               // undefined if not requested / no match
if (dz) {
  const page = dz.link;
  const preview = dz.preview;           // via extras
  const cover = dz.album?.cover_big;
}

The preview is a 30-second MP3 you can play directly — use it subject to Deezer’s terms.

Fields

The typed fields on the Deezer block:

Field	Type	Description
id	int | null	Deezer track ID.
title	string | null	Track title.
link	string | null	Deezer page for the track.
duration	int | null	Track length in seconds.

A Deezer track object carries more — preview (MP3), artist, and a nested album with cover/cover_small/cover_medium/cover_big/cover_xl URLs. These aren’t typed properties; read them through the block’s model_extra (Python) / extras (Node). For the authoritative field list see the Deezer track object reference and album object reference.

The block and every field can be absent or null — request did not include deezer, no Deezer match for the recording, or the provider omitted a field. Always null-check before reading.

Without requesting the block: song_link

You don’t need the deezer block just to send a user to Deezer. Every match carries a song_link (a lis.tn URL such as https://lis.tn/NbkVb), and the streaming_url("deezer") SDK helper (streamingUrl("deezer") in Node) returns an “open in Deezer” redirect built from it — no provider block, no added latency:

result.streaming_url("deezer")   # lis.tn ?deezer redirect

Request the deezer block when you need the structured metadata — the direct Deezer link, track ID, preview, cover art — in your own UI. See the lis.tn song link concept for the redirect convention.

---

Related

• Apple Music metadata block
• Spotify metadata block
• MusicBrainz metadata block
• The lis.tn song link
• Provider metadata overview