YouTube Downloader

This API allows you to seamlessly search YouTube and extract direct, high-quality audio (MP3) or video (MP4) download links.

Endpoint

POST /api/v1/youtube

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
type	string	Yes	The action to perform. Valid options: search, ytmp3, ytmp4, play.
query	string	Conditional	Required if type is search or play. The search term.
url	string	Conditional	Required if type is ytmp3 or ytmp4. The target YouTube video URL.
format	string	Optional	Used only with play. The desired format: mp3 or mp4 (Default: mp3).

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/youtube \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"type": "play", "query": "Alan Walker Faded", "format": "mp3"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/youtube', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    type: 'play',
    query: 'Alan Walker Faded',
    format: 'mp3'
  })
});

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

Heavstal SDK

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

// Extract MP3 directly from Search (type: 'play')
const song = await downloader.play("Alan Walker Faded", "mp3");
console.log(song.url);

// Search YouTube (type: 'search')
const results = await search.youtube("No Copyright Sounds");

// Extract Video from URL (type: 'ytmp4')
const video = await downloader.ytmp4("https://youtu.be/...");

Python

import requests

url = "https://heavstal.com.ng/api/v1/youtube"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "type": "play",
    "query": "Alan Walker Faded",
    "format": "mp3"
}

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

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "data": {
    "author": "Heavstal Tech™",
    "title": "Alan Walker - Faded",
    "thumbnail": "https://i.ytimg.com/vi/60ItHLz5WEA/maxresdefault.jpg",
    "channel": "Alan Walker",
    "published": "2015-12-03",
    "views": 3574921000,
    "duration": 213,
    "url": "https://rr4---sn-ab5sznzl.googlevideo.com/videoplayback?..."
  }
}

Error Response

{
  "status": "error",
  "error": "Video unavailable or age-restricted."
}