# YouTube Video Downloader — MP4 & MP3 (`hipersoft/youtube-downloader`) Actor

Download YouTube videos as MP4 (up to 4K) or extract audio as MP3. Get the file plus title, channel, duration, views and a direct download link. Powered by yt-dlp — reliable.

- **URL**: https://apify.com/hipersoft/youtube-downloader.md
- **Developed by:** [hiper soft](https://apify.com/hipersoft) (community)
- **Categories:** Videos, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.002 / video processed

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## YouTube Video Downloader — MP4 & MP3 by URL

Download YouTube videos as MP4 or pull the audio as MP3, in bulk. Paste one or more YouTube links and get a ready-to-use download link for each video — plus the details that go with it: video title, channel/author and thumbnail. Pick the format you want (MP3 audio, or 360p / 720p / 1080p MP4) and get one tidy row per URL, ready to export as JSON, CSV or Excel.

This is the cheap, no-nonsense way to save YouTube videos and audio at scale for content creators, editors, researchers, podcasters and anyone building an automated media pipeline.

### Why use this YouTube downloader

- 🎬 **MP4 video or MP3 audio** — choose a video resolution (360p, 720p, 1080p) or extract just the audio as an MP3.
- 🏷️ **Clean metadata** — every video comes back with its title, channel/author name and thumbnail image.
- 🔗 **Any YouTube link** — full `watch?v=` URLs, short `youtu.be/…` links, `shorts/…` links, `m.youtube.com` links and bare 11-character video IDs all work.
- 📦 **Bulk in one run** — drop in a whole list of URLs and get one clean record per video.
- 💸 **Cheapest per-video pricing** — pay only for the videos you actually process, with volume discounts as you scale.
- 🧩 **Built for automation** — feed URLs from a spreadsheet, Make or n8n and get structured records with direct download links back.
- 📤 **Export anywhere** — JSON, CSV or Excel, or pull straight from the dataset into your own tools.

### What you get

Each video is one dataset record like this:

```json
{
  "source": "youtube",
  "inputUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "author": "Rick Astley",
  "authorUrl": "https://www.youtube.com/@RickAstleyYT",
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "format": "720",
  "downloadUrl": "https://.../rick-astley-720p.mp4",
  "status": "ready",
  "durationText": "3:33"
}
```

### Input

Give the downloader a list of YouTube URLs and pick a format. That's it.

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/9bZkp7q19f0"
  ],
  "format": "720",
  "maxItems": 0
}
```

| Field | Description |
| --- | --- |
| `videoUrls` | One or more YouTube video URLs or IDs (required). Full `watch?v=` links, `youtu.be/…` short links, `shorts/…` links, `m.youtube.com` links and bare 11-character video IDs all work. Plain strings or `{ "url": "..." }` objects. |
| `format` | What to download: `mp3` (audio only), or `360` / `720` / `1080` for MP4 video at that resolution. Default `720`. |
| `maxItems` | Maximum number of videos to process (0 = no limit; process every URL). |
| `proxyConfiguration` | Optional. Not needed for normal use — leave it off. |

### Output fields

| Field | Description |
| --- | --- |
| `videoId` | YouTube video ID. |
| `url` | Canonical video URL. |
| `title` | Video title. |
| `author` | Channel / author name. |
| `authorUrl` | Channel / author URL. |
| `thumbnailUrl` | Thumbnail image URL. |
| `format` | The format you requested (`mp3`, `360`, `720` or `1080`). |
| `downloadUrl` | Ready download link for the file, or `null` if it wasn't ready in time. |
| `status` | `ready` (download link populated), `timeout` (not ready in time — try again), or `failed`. |
| `durationText` | Video length, when available. |

### Use cases

- **Save videos and audio** — grab MP4 videos or MP3 audio for editing, archiving or offline use.
- **Podcast & music sourcing** — pull the audio track from talks, interviews and music videos as MP3.
- **Content research** — collect titles, authors and thumbnails across a batch of videos in one pass.
- **Editing pipelines** — hand a list of URLs to your editors with direct download links ready to go.
- **Automation** — feed a list of URLs from a spreadsheet, Make or n8n and get structured records with download links back.

### FAQ

**Can I download audio only?** Yes — set `format` to `mp3` and you get an MP3 audio link instead of a video file.

**Which resolutions can I choose?** `360`, `720` and `1080` return an MP4 at that resolution; `mp3` returns audio only.

**Can I download many videos at once?** Yes. Put as many URLs as you like in `videoUrls` and you get one record per video.

**Does it work with Shorts and short links?** Yes — `youtube.com/shorts/…`, `youtu.be/…` short links, full URLs and bare video IDs are all accepted.

**What does `status` mean?** `ready` means the `downloadUrl` is populated. `timeout` means the file wasn't ready in time — just run that URL again. `failed` means the video couldn't be processed (e.g. an invalid or private URL).

**Do I need a proxy?** No. Proxy is optional and off by default.

**How much does it cost?** Pay-per-event: a tiny charge per run plus a small charge per video processed, with tier discounts as your volume grows. See the **Pricing** tab for current rates.

### Notes

This tool retrieves media and public metadata for YouTube videos whose URLs you provide. It is an independent tool and is not affiliated with, endorsed by or connected to YouTube or Google; all names and trademarks belong to their respective owners. Only download content you own or have the right to use, and respect YouTube's terms and applicable copyright law. Public content only.

# Actor input Schema

## `videoUrls` (type: `array`):

One or more YouTube video URLs to download. Accepts full links (https://www.youtube.com/watch?v=...), short links (https://youtu.be/...), Shorts (https://www.youtube.com/shorts/...), m.youtube.com links and bare 11-character video IDs. You can paste plain strings or {"url": "..."} objects.

## `format` (type: `string`):

Choose MP3 (audio only) or an MP4 video resolution.

## `maxItems` (type: `integer`):

Maximum number of videos to download (0 = no limit; process every URL you provide).

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

Optional proxy. Not required — leave off to run on a direct connection. Enable only if you specifically want requests routed through a proxy.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/9bZkp7q19f0"
  ],
  "format": "720",
  "maxItems": 0,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

The results as dataset items.

# 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 = {
    "videoUrls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://youtu.be/9bZkp7q19f0"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("hipersoft/youtube-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 = {
    "videoUrls": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "https://youtu.be/9bZkp7q19f0",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

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

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

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

```

## CLI example

```bash
echo '{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/9bZkp7q19f0"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call hipersoft/youtube-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hipersoft/youtube-downloader"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7YjEnd7jgVUe9Vrjt/builds/JPdMx8dnEw2JwKFeT/openapi.json