# Universal Video Downloader (`raushan2288/universal-video-downloader`) Actor

Download videos from hundreds of websites using a single API. Extract videos in high quality with metadata, thumbnails, captions (when available), and direct download links. Ideal for automation, AI workflows, archiving, research, and content processing.

- **URL**: https://apify.com/raushan2288/universal-video-downloader.md
- **Developed by:** [Raushan Kumar](https://apify.com/raushan2288) (community)
- **Categories:** Videos
- **Stats:** 1 total users, 1 monthly users, 90.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $10.00 / 1,000 video scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Universal Video & Audio Downloader (Multi-Platform)

A powerful, anti-blocking Apify Actor to download videos or extract audio in **bulk or single mode** from **1000+ platforms** without getting blocked or rate-limited.

Supported platforms include: **YouTube**, **TikTok**, **Instagram**, **Twitter/X**, **Facebook**, **Reddit**, **Pinterest**, **Twitch**, **Vimeo**, **Rumble**, **Dailymotion**, and over 1,000 other sites supported by `yt-dlp`.

***

### Key Features

- 🌐 **1,000+ Platforms**: Works seamlessly with single videos, playlists, channel feeds, and profile URLs.
- 🛡️ **Anti-Blocking System**: Integrates Apify Proxy (Residential / Datacenter), header impersonation, user-agent rotation, client spoofing, and customizable request delays.
- 🔑 **Cookies Support**: Pass Netscape or JSON cookies to download private, age-restricted, or logged-in content (Instagram, TikTok, Twitter).
- 🎬 **Quality Control**: Select video resolutions (`best`, `1080p`, `720p`, `480p`, `360p`) or convert videos directly to audio (`mp3`, `m4a`, `wav`).
- ⚡ **Metadata or Full Binary Mode**:
  - `metadata_only`: Fast mode extracting JSON metadata and direct high-speed video stream URLs.
  - `download_to_kvs`: Full mode downloading video files directly into Apify Key-Value Store.
- 📦 **Bulk Processing**: Supply dozens or hundreds of URLs simultaneously with parallel worker concurrency.

***

### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `urls` | Array | `["https://..."]` | **Required**. List of video, playlist, or channel URLs. |
| `downloadMode` | String | `metadata_only` | `metadata_only` (Fast) or `download_to_kvs` (Full binary download). |
| `quality` | String | `best` | `best`, `1080p`, `720p`, `480p`, `360p`, or `audio_only`. |
| `audioFormat` | String | `mp3` | `mp3`, `m4a`, `wav` (when `quality` is `audio_only`). |
| `outputFormat` | String | `mp4` | `mp4`, `webm`, `mkv` container format. |
| `proxyConfiguration` | Object | Residential | Apify Proxy configuration to bypass IP rate limits. |
| `cookies` | String | `""` | Optional Netscape or JSON cookie string for authenticated pages. |
| `maxVideosPerUrl` | Integer | `50` | Maximum items to extract per playlist/channel URL. |
| `maxConcurrency` | Integer | `3` | Concurrent download workers (1 to 10). |
| `downloadDelaySeconds` | Float | `1.0` | Delay between downloads to prevent anti-bot bans. |
| `enableAntiBot` | Boolean | `true` | Enables client impersonation and header spoofing. |

***

### Input Example (JSON)

```json
{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://www.instagram.com/p/C-example/",
    "https://www.tiktok.com/@user/video/71234567890"
  ],
  "downloadMode": "metadata_only",
  "quality": "1080p",
  "outputFormat": "mp4",
  "maxConcurrency": 3,
  "downloadDelaySeconds": 1.5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

***

### Output Example (Apify Dataset)

```json
{
  "inputUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "video_id": "dQw4w9WgXcQ",
  "extractor": "youtube",
  "platform": "youtube",
  "uploader": "Rick Astley",
  "durationSeconds": 213,
  "viewCount": 1500000000,
  "likeCount": 17000000,
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "directStreamUrl": "https://rr3---sn-npv7en76.googlevideo.com/videoplayback?...",
  "downloadStatus": "extracted",
  "error": null
}
```

If `downloadMode` is set to `download_to_kvs`, output items will also include `kvsKey` and `kvsRecordUrl` linking directly to the stored media file.

***

### Deployment & Usage

Run locally using Apify CLI:

```bash
apify run
```

Push to Apify Console:

```bash
apify push
```

# Actor input Schema

## `urls` (type: `array`):

List of video URLs, playlist links, or profile URLs to process (e.g. YouTube, TikTok, Instagram, Twitter/X, Facebook, Pinterest, Vimeo, etc.).

## `downloadMode` (type: `string`):

Choose whether to extract JSON metadata with stream links, or download full video binary files.

## `saveToLocal` (type: `boolean`):

Save downloaded video/audio files directly to your local computer folder.

## `outputDir` (type: `string`):

Directory path on local disk where downloaded files will be saved.

## `quality` (type: `string`):

Select target video resolution or audio-only extraction.

## `audioFormat` (type: `string`):

Format for extracted audio when Quality is set to 'Audio Only'.

## `outputFormat` (type: `string`):

Preferred video file format.

## `proxyConfiguration` (type: `object`):

Apify Proxy or custom proxies. Recommended to prevent anti-bot blocking (especially Residential Proxies for Instagram/TikTok/YouTube).

## `cookies` (type: `string`):

Optional HTTP cookies to bypass login walls, age restrictions, or private account content (e.g. for Instagram, TikTok, or Twitter).

## `maxVideosPerUrl` (type: `integer`):

Maximum number of items to extract if a URL is a playlist or channel/profile page.

## `maxConcurrency` (type: `integer`):

Number of concurrent downloading threads.

## `downloadDelaySeconds` (type: `number`):

Delay in seconds between requests to avoid rate-limiting / blocking.

## `enableAntiBot` (type: `boolean`):

Enables client impersonation, user-agent rotation, and fallback extractors.

## Actor input object example

```json
{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "downloadMode": "download_binary",
  "saveToLocal": true,
  "outputDir": "./downloads",
  "quality": "best",
  "audioFormat": "mp3",
  "outputFormat": "mp4",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "maxVideosPerUrl": 50,
  "maxConcurrency": 3,
  "downloadDelaySeconds": 1,
  "enableAntiBot": true
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("raushan2288/universal-video-downloader").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"] }

# Run the Actor and wait for it to finish
run = client.actor("raushan2288/universal-video-downloader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ]
}' |
apify call raushan2288/universal-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=raushan2288/universal-video-downloader",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/b7T9E4GsAZJB1DO9G/builds/WIpomvJVjAcKeiVxt/openapi.json