🎵 Music API

API sederhana untuk mencari lagu, mengambil detail lagu, dan lirik bertanda waktu. Cocok untuk aplikasi, bot, atau web lain. Buka web player.

Base URL: BASE_URL

Autentikasi

Semua endpoint (kecuali /api/health) butuh API key. Kirim lewat header X-API-Key (disarankan) atau parameter ?key=. Key dibuat oleh pemilik layanan di halaman /setup.

Jangan menaruh API key di kode web publik atau aplikasi yang bisa dibongkar. Panggil API dari server/backend/bot kamu.

Batas permintaan

Default 60 permintaan per menit per key (diatur pemilik). Jika lewat, respons 429 dengan header Retry-After.

Endpoint

GET /api/search

ParameterWajibKeterangan
qyaKata kunci judul atau artis (maks 100 karakter)
limittidak1–10, default 8
curl -H "X-API-Key: KEY_KAMU" "BASE_URL/api/search?q=about%20you&limit=3"
{
  "query": "about you",
  "results": [{
    "id": "3tTz...",              // ID lagu Spotify (22 karakter)
    "uri": "spotify:track:3tTz...",
    "title": "Judul Lagu",
    "artists": ["Artis"],
    "album": "Nama Album",
    "cover": "https://i.scdn.co/image/...",
    "duration_ms": 215000,
    "explicit": false,
    "spotify_url": "https://open.spotify.com/track/...",
    "preview_url": null           // sering null; Spotify membatasi preview
  }]
}

GET /api/track/{id}

Detail satu lagu dengan format yang sama seperti satu item results.

curl -H "X-API-Key: KEY_KAMU" BASE_URL/api/track/ID_22_KARAKTER

GET /api/lyrics

Lirik bertanda waktu dari LRCLIB. Gunakan track_id, atau title + artist (opsional duration dalam detik).

curl -H "X-API-Key: KEY_KAMU" "BASE_URL/api/lyrics?track_id=ID_22_KARAKTER"
{
  "title": "Judul", "artist": "Artis",
  "found": true, "instrumental": false,
  "synced": [{ "time_ms": 12500, "text": "baris lirik" }],
  "plain": "lirik polos atau null"
}

Tidak semua lagu punya lirik. Jika found bernilai false, tampilkan pesan cadangan.

GET /api/health

Tanpa key. Mengembalikan {"ok":true} untuk cek layanan.

Kode error

StatuserrorArti
400bad_requestParameter kurang atau tidak valid
401unauthorizedAPI key tidak ada atau salah
404not_foundLagu atau endpoint tidak ada
429rate_limitedMelebihi batas permintaan
502upstream_error / spotify_authSpotify bermasalah; hubungi pemilik layanan

Contoh kode

JavaScript (Node / backend)

const r = await fetch("BASE_URL/api/search?q=" + encodeURIComponent("about you"), {
  headers: { "X-API-Key": process.env.MUSIC_API_KEY }
});
const { results } = await r.json();
console.log(results[0].title, "-", results[0].artists.join(", "));

Python

import requests
r = requests.get("BASE_URL/api/search", params={"q": "about you", "limit": 5},
                 headers={"X-API-Key": "KEY_KAMU"}, timeout=10)
for t in r.json()["results"]:
    print(t["title"], "-", ", ".join(t["artists"]), t["spotify_url"])

Bot Discord (discord.js) — perintah /lagu

const res = await fetch("BASE_URL/api/search?limit=1&q=" + encodeURIComponent(query), {
  headers: { "X-API-Key": process.env.MUSIC_API_KEY }
});
const t = (await res.json()).results[0];
if (!t) return interaction.reply("Lagu tidak ditemukan.");
await interaction.reply({ embeds: [{
  title: t.title, url: t.spotify_url, description: t.artists.join(", "),
  thumbnail: { url: t.cover }
}] });

Android (Kotlin + OkHttp)

val req = Request.Builder()
  .url("BASE_URL/api/search?q=about%20you")
  .header("X-API-Key", KEY) // sebaiknya lewat backend milikmu
  .build()
OkHttpClient().newCall(req).execute().use { println(it.body?.string()) }

Memutar lagu

Lagu diputar lewat web player, bukan lewat API. Tautkan atau sematkan (embed) halaman player:

URLFungsi
BASE_URL/?q=about youBuka player dengan pencarian terisi
BASE_URL/?track=ID_22_KARAKTERBuka player dengan lagu siap diputar (tekan ▶)
<iframe src="BASE_URL/?track=ID_22_KARAKTER" width="100%" height="520"
  allow="autoplay; encrypted-media" style="border:0"></iframe>

Batasan penting