Music Lyrics API

This API provides a high-availability lyrics fetcher. It aggregates data from open-source and metadata providers to ensure you get accurate, synced lyrics and album art.

Endpoint

POST /api/v1/lyrics

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
query	string	Yes	The song title and artist (e.g., “Mockingbird Eminem”).

Request Examples

Choose your preferred method to interact with the Lyrics API:

cURL

curl -X POST https://heavstal.com.ng/api/v1/lyrics \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"query": "Billie Eilish Bad Guy"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/lyrics', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    query: 'Billie Eilish Bad Guy'
  })
});

const res = await response.json();
console.log(res.data.lyrics);

Heavstal SDK

import { search } from '@heavstal/api';

const song = await search.lyrics("Kendrick Lamar DNA");
console.log(song.lyrics);

Python

import requests

url = "https://heavstal.com.ng/api/v1/lyrics"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "query": "Billie Eilish Bad Guy"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"]["lyrics"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "data": {
    "title": "bad guy",
    "artist": "Billie Eilish",
    "image": "https://i.scdn.co/image/...",
    "url": "https://lrclib.net/api/get/...",
    "lyrics": "White shirt now red, my bloody nose..."
  }
}

Error Response

{
  "status": "error",
  "error": "Lyrics not found for the requested song."
}