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_urlandvideo_sdvalues are base64-encoded URLs. You must decode them before use.cookiesis 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