API Documentation

Download YouTube Audio (MP3) and Video (MP4 up to 4K) with ease.

Authentication

Every request must include a valid API key in the x-api-key header.

bash
curl -H "x-api-key: <your_api_key>" \
  "https://api.songs.example.com/audio/dQw4w9WgXcQ"

If the key is missing, invalid, or expired, the API will respond with:

json
{
  "status": "error",
  "message": "Invalid or expired API key"
}

Get Audio (MP3)

GET /audio/<video_id>

Starts or fetches the download of a YouTube video’s audio track in MP3 (192 kbps) format.

Success Response (already downloaded):

json
{
  "status": "success",
  "audio_url": "<base64_encoded_download_url>"
}

In Progress Response:

json
{
  "status": "downloading",
  "progress": 42.7,
  "cookies": "<base64_encoded_cookie_file>",
  "video_id": "dQw4w9WgXcQ"
}

Error Response:

json
{
  "status": "error",
  "message": "Some error details"
}

Get Video (MP4)

GET /beta/<video_id>

Starts or fetches the download of a YouTube video in MP4 format (up to 4K).

Success Response (already downloaded):

json
{
  "status": "success",
  "video_sd": "<base64_encoded_download_url>"
}

In Progress Response:

json
{
  "status": "downloading",
  "progress": 65.3,
  "cookies": "<base64_encoded_cookie_file>",
  "video_id": "dQw4w9WgXcQ"
}

Error Response:

json
{
  "status": "error",
  "message": "Some error details"
}

Notes

  • audio_url and video_sd values are base64-encoded URLs. You must decode them before use.
  • cookies is a base64-encoded cookie file for client-side fallback downloads.
  • Polling an endpoint multiple times will update the progress field until the download is complete.

Client-side base64 decode example:

js
// decode base64-encoded URLs in the browser
const decoded = atob("<base64_encoded_download_url>");
console.log(decoded); // usable https://... link