Music API

Track search and download from Spotify, Deezer, YouTube, and SoundCloud, with cached streaming and artwork.

Music API#

The Hep.gg Music API (MusicPrime) resolves tracks by ISRC or by Spotify/Deezer URL and returns audio you can download or stream. It searches Spotify (default) or Deezer live, fetches HQ audio through Deezer, pulls audio from YouTube and SoundCloud, and serves cover artwork. Every call is authenticated with an API key you mint in the dashboard.

Authentication#

There is no public "create a key" endpoint. Keys are minted in the hep.gg dashboard under the Music app (after your account is approved for it). Once you have a key, send it on each request using whichever of the three methods is convenient:

# query param
GET /search?q=...&key=<your-key>

# Authorization header — RAW key, NOT "Bearer <key>"
Authorization: <your-key>

# X-API-Key header
X-API-Key: <your-key>

Precedence, if you somehow send more than one, is: key query param, then Authorization, then X-API-Key. Two endpoints are public and need no key at all: GET / (global stats) and GET /artwork/:isrc (cover art). The desktop client download GET /client is also unauthenticated. Everything else requires a key.

Auth errors#

Quickstart#

Download a single track by ISRC. The default quality is 128; pass quality=320 for HQ.

curl -L "https://music.jakeypri.me/download?isrc=USRC17607839&quality=320&key=YOUR_KEY" \
  -o track.mp3

const res = await fetch(
  "https://music.jakeypri.me/download?isrc=USRC17607839&quality=320",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
if (!res.ok) throw new Error(`Download failed: ${res.status}`);
 
const buf = Buffer.from(await res.arrayBuffer());
await require("fs/promises").writeFile("track.mp3", buf);

Endpoints#

Error model#

Errors are returned as a JSON envelope with an error string. Some routes add a hint or details field when it helps you fix the request.

{ "error": "Invalid ISRC. Must be 12 characters." }

Upstream 4xx errors from Spotify on the search routes are passed through with their original status code and message rather than masked as 500.

Rate limits and quotas#

There is no published public rate limit or quota. Hep.gg keeps per-key usage counters (downloads, YouTube, SoundCloud, and search) which are visible in the dashboard. Spotify upstream errors are passed through, so a burst of search calls that trips Spotify's own limits will surface as a 4xx from /search or /searchfull. Be a good neighbor: cache results you reuse, and note that HQ downloads are already cached server-side for 24 hours.