Universal Social Media Downloader API Docs

Overview

This service provides REST endpoints to resolve metadata, trigger downloads, and search media from supported social networks: Instagram, TikTok, YouTube, Facebook, X (Twitter), and SoundCloud. It processes requests asynchronously, automatically cleans up disks, and is fully optimized for rapid consumption.

Authentication & Rate Limiting

Provide your credential token inside the X-API-Key request header.

Anonymous Mode

Rate limited per client IP. Ideal for testing. Default is 5 requests per minute.

API Key Mode

Each API Key tracks individual rate limits. Keys can be customized with per-key limits at creation time.

GET

/api/info

Extracts structured metadata, duration, media type, and direct CDN URLs from a social link.

Parameter	Type	Required	Description
url	string	Yes	The social post URL (e.g. YouTube video or Instagram post).

curl -H "X-API-Key: my_key"   "http://localhost:8000/api/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

const url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
fetch(`http://localhost:8000/api/info?url=${encodeURIComponent(url)}`, {
  headers: { 'X-API-Key': 'my_key' }
})
.then(res => res.json())
.then(data => console.log(data));

import requests
url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
response = requests.get(
    'http://localhost:8000/api/info',
    params={'url': url},
    headers={'X-API-Key': 'my_key'}
)
print(response.json())

Response Sample 200 OK

{
  "success": true,
  "title": "Never Gonna Give You Up",
  "extractor": "youtube",
  "extractor_key": "Youtube",
  "thumbnail": "https://i.ytimg.com/...",
  "duration": 212,
  "webpage_url": "https://www.youtube.com/watch?v=...",
  "is_gallery": false,
  "direct_url": "https://...",
  "direct_urls": ["https://..."]
}

GET

/api/download

Instructs the scraper to pull media files to the server and returns a claim session token for direct local streaming.

Parameter	Type	Required	Description
url	string	Yes	The social media link to download.

curl -H "X-API-Key: my_key"   "http://localhost:8000/api/download?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

const url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
fetch(`http://localhost:8000/api/download?url=${encodeURIComponent(url)}`, {
  headers: { 'X-API-Key': 'my_key' }
})
.then(res => res.json())
.then(data => console.log(data));

import requests
url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
response = requests.get(
    'http://localhost:8000/api/download',
    params={'url': url},
    headers={'X-API-Key': 'my_key'}
)
print(response.json())

Response Sample 200 OK

{
  "success": true,
  "is_image": false,
  "result": "http://localhost:8000/api/download/file?id=8f6c449e-b2d9-482a-bc91-9e79b9a67448",
  "direct_url": "https://...",
  "direct_urls": ["https://..."]
}

GET

/api/download/file

Streams the resolved file binary (or zipped gallery/carousel) back to the caller. Once the transfer completes, files are instantly purged from the server disk.

Parameter	Type	Required	Description
id	string	Yes	The download UUID token returned from `/api/download`.

# Stream and save to output.mp4
curl -o output.mp4   "http://localhost:8000/api/download/file?id=8f6c449e-b2d9-482a-bc91-9e79b9a67448"

const id = '8f6c449e-b2d9-482a-bc91-9e79b9a67448';
window.location.href = `http://localhost:8000/api/download/file?id=${id}`;

import requests
file_id = '8f6c449e-b2d9-482a-bc91-9e79b9a67448'
res = requests.get(
    'http://localhost:8000/api/download/file',
    params={'id': file_id},
    stream=True
)
with open('output.mp4', 'wb') as f:
    for chunk in res.iter_content(chunk_size=8192):
        f.write(chunk)

GET

/api/search

Searches YouTube or SoundCloud and retrieves flat metadata matching the query.

Parameter	Type	Required	Description
query	string	Yes	The term to search for (max 500 characters).
platform	string	No	The platform to query: `youtube` (default) or `soundcloud`.
limit	integer	No	Maximum search result entries between 1 and 20. Defaults to `5`.

curl -H "X-API-Key: my_key"   "http://localhost:8000/api/search?query=rickroll&platform=youtube&limit=2"

fetch("http://localhost:8000/api/search?query=rickroll&platform=youtube&limit=2", {
  headers: { 'X-API-Key': 'my_key' }
})
.then(res => res.json())
.then(data => console.log(data));

import requests
response = requests.get(
    'http://localhost:8000/api/search',
    params={'query': 'rickroll', 'platform': 'youtube', 'limit': 2},
    headers={'X-API-Key': 'my_key'}
)
print(response.json())

Response Sample 200 OK

{
  "success": true,
  "results": [
    {
      "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "id": "dQw4w9WgXcQ",
      "duration": 212,
      "uploader": "Rick Astley",
      "thumbnail": "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "views": 1500000000
    }
  ]
}