# YouTube Video Downloader — Cloud Save to Apify KV Store (`scrapeio/youtube-downloader`) Actor

Download YouTube videos or Shorts to Apify Key-Value Store. Quality selection (best, 720p, 1080p, 4K, audio-only). yt-dlp plus proxy. Apify AI, MCP, and Cursor ready.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 – Download Videos & Audio to Cloud Storage | Apify Actor

Part of **[Shop Intel](https://apify.com/scrapeio)** by **ScrapeIO** on Apify — programmatic media pipelines alongside our **[YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper)**, **[YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder)**, and **[LinkedIn Ad Library Scraper](https://apify.com/scrapeio/linkedin-ad-library-scraper)**.

**YouTube Video Downloader** downloads any [YouTube](https://www.youtube.com) video or Short with yt‑dlp, lets you pick quality (720p, 1080p, 1440p, 2160p, or audio‑only), and stores the file in Apify key‑value storage with a ready‑to‑use download URL.

### Use with Apify AI

[Apify AI](https://docs.apify.com/account/apify-ai) is live in Apify Console. Describe the job in plain English and it **finds this Actor, fills the input form, runs it, and returns the dataset**. The same ranking powers Store search and the [Apify MCP server](https://docs.apify.com/integrations/mcp) `search-actors` tool used by **Cursor**, Claude, ChatGPT, and other agents.

Use this Actor to **download a YouTube video or Short** to Apify Key-Value Store (MP4 or audio). Open [YouTube Video Downloader](https://apify.com/scrapeio/youtube-downloader) or ask Apify AI with the prompts below.

#### Prompts that match this Actor

Type these in the **Apify Store search bar** (long, intent-heavy queries route to Apify AI) or the dashboard **Ask Apify AI** widget:

- "Download this YouTube video to cloud storage as MP4"
- "Save a YouTube Short to Apify Key-Value Store"
- "Download YouTube audio only from a video URL"
- "Get a YouTube video file at 1080p into Apify storage"
- "Archive a YouTube URL for offline review"

#### How Apify AI fills the input

| You say | This Actor sets |
|---|---|
| YouTube watch or Shorts URL | `youtubeUrl` |
| quality if offered (best, 720p, 1080p, 4K, audio) | `quality / format` |

Apify AI always asks for confirmation before it runs. Nothing is charged until you approve.

#### Cursor, Claude, ChatGPT (Apify MCP)

Pin this Actor as a **default Cursor / MCP tool** so agents call `scrapeio/youtube-downloader` instead of a random Store result. Keep `actors` + `docs` so Apify AI search still works, and list your suite so Cursor prefers these Actors.

**Cursor MCP URL (this Actor first):**

```text
https://mcp.apify.com?tools=actors,docs,scrapeio/youtube-downloader,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper
```

`.cursor/mcp.json` / Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=actors,docs,scrapeio/youtube-downloader,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper"
    }
  }
}
```

Then: `search-actors` → `fetch-actor-details` → `call-actor` with `scrapeio/youtube-downloader`. Example:

```text
Use scrapeio/youtube-downloader to do this: scrape the data I described. Fill the input from my description and return the dataset.
```

### How to download YouTube videos on Apify

Use this **YouTube video downloader** to save a video or Short into Apify cloud storage as MP4 or audio.

### YouTube downloader API for Cursor

Call `scrapeio/youtube-downloader` from **Cursor** (Apify MCP), Claude, ChatGPT, the [Apify API](https://docs.apify.com/api/v2), Python (`apify-client`), or JavaScript. Apify AI uses the same ranking as Store search: title, description, README, and input/output schemas. This Actor is documented for that ranker — limited permissions, pay-per-event or compute (not rental), and a filled example input.

### 🧠 Overview

This **YouTube Video Downloader** is an Apify Actor for developers, data engineers, AI researchers, and content ops teams who need **programmatic access to YouTube video files**. Drop in a YouTube or `youtu.be` URL, choose a quality preset (or `bestaudio` for audio‑only), and the Actor downloads the file with **yt‑dlp**, uploads it to the run's **key‑value store** under a stable `storageKey`, and writes a Dataset row with full metadata — video ID, title, file size in GB, requested vs delivered quality, and a structured **billing cost breakdown** for internal chargeback. Perfect for **AI training data pipelines**, **archival and compliance**, **video‑to‑text workflows**, **podcast re‑use**, and **lawful creator backups** — all in one Apify run.

### ✨ Features

- **Download** any single YouTube video or Short with a direct URL input.
- **Select** quality from `best`, `720p`, `1080p`, `1440p`, `2160p` (4K), or audio‑only modes.
- **Extract** audio‑only files (`bestaudio`, `highestaudio`, `worstaudio`) for podcasts, transcripts, or ML datasets.
- **Store** media in the Apify key‑value store with a stable `storageKey` — download from the run's Storage tab.
- **Generate** a Dataset row with `videoTitle`, `videoId`, `fileSizeGB`, and quality metadata.
- **Track** usage costs via a configurable **billing** object (`costPerActorStart`, `costPerGBDownloaded`, `costPerGBStorage`) for chargeback reporting.
- **Handle** YouTube's modern extractor options out of the box via yt‑dlp.
- **Automate** bulk video harvesting with the Apify scheduler, webhooks, and REST API.
- **Integrate** directly into **AI/ML pipelines, transcription services, and video archives**.
- **Clean up** temp files automatically after successful upload to storage.

### 🎯 Use Cases

- **AI & LLM Training Data:** Download videos or audio to feed transcription, speech‑to‑text, and multimodal training pipelines.
- **Podcast & Transcription Workflows:** Pull `bestaudio` into Whisper, Deepgram, or AssemblyAI for searchable transcripts.
- **Video Archival & Compliance:** Preserve your own channel's content, licensed material, or public‑domain uploads in cloud storage.
- **Content Repurposing:** Download your own long‑form videos to re‑edit into Shorts, Reels, or TikTok clips.
- **Academic & Journalism Research:** Archive public‑interest videos for longitudinal study, fact‑checking, or citation.
- **Internal Chargeback Reporting:** Track download volume and storage cost per department using the built‑in `billing` object.

### ⚙️ Input Parameters

| Name | Type | Required | Description | Example |
|------|------|----------|-------------|---------|
| `youtubeUrl` | string | Yes | Full YouTube or `youtu.be` video URL. | `"https://www.youtube.com/watch?v=dQw4w9WgXcQ"` |
| `quality` | string | No | `best`, `720p`, `1080p`, `1440p`, `2160p`, `bestaudio`, `worstaudio`. | `"1080p"` |
| `costPerActorStart` | number | No | USD per run — used only for `billing` math in output. | `0.10` |
| `costPerGBDownloaded` | number | No | USD per GB downloaded for billing math. | `1.00` |
| `costPerGBStorage` | number | No | USD per GB stored for billing math. | `0.50` |

### 📤 Output Example (JSON)

```json
{
  "success": true,
  "videoId": "dQw4w9WgXcQ",
  "videoTitle": "Rick Astley - Never Gonna Give You Up (Official Video)",
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "requestedQuality": "1080p",
  "downloadedQuality": "1080p",
  "filePath": null,
  "fileSizeBytes": 104857600,
  "fileSizeGB": 0.0977,
  "storageKey": "video_dQw4w9WgXcQ_1730000000000",
  "storageSizeGB": 0.0977,
  "billing": {
    "events": [
      {
        "eventName": "actor_start",
        "eventType": "fixed",
        "description": "Cost per actor execution/start",
        "cost": 0.1,
        "quantity": 1,
        "unit": "event",
        "rate": 0.1,
        "rateUnit": "USD per event"
      },
      {
        "eventName": "download",
        "eventType": "usage",
        "description": "Cost per GB of media downloaded",
        "cost": 0.0977,
        "quantity": 0.0977,
        "unit": "GB",
        "rate": 1,
        "rateUnit": "USD per GB"
      },
      {
        "eventName": "storage",
        "eventType": "usage",
        "description": "Cost per GB stored in Apify KeyValueStore",
        "cost": 0.0488,
        "quantity": 0.0977,
        "unit": "GB",
        "rate": 0.5,
        "rateUnit": "USD per GB"
      }
    ],
    "totalCost": 0.2465,
    "dataDownloadedGB": 0.0977,
    "storageGB": 0.0977
  }
}
```

### 📋 Output Data Schema

Every successful run writes one Dataset row with these fields:

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` on download + upload success. |
| `videoId` | string | YouTube video ID (e.g. `dQw4w9WgXcQ`). |
| `videoTitle` | string | Full video title. |
| `youtubeUrl` | string | The original URL you passed in. |
| `requestedQuality` | string | Quality preset you requested (e.g. `1080p`). |
| `downloadedQuality` | string | Closest quality actually delivered. |
| `fileSizeBytes` | integer | File size in bytes. |
| `fileSizeGB` | number | File size in gigabytes (useful for billing math). |
| `storageKey` | string | Key in the run's default key‑value store holding the binary file. |
| `storageSizeGB` | number | Storage footprint in GB (= `fileSizeGB`). |
| `billing.events` | array | Cost rows with `eventName` (`actor_start`, `download`, `storage`), `quantity`, `rate`, and `cost`. |
| `billing.totalCost` | number | Sum of billing events (configurable rates in input). |
| `error` | string | Present only when `success: false` — human‑readable error message. |
| `errorStack` | string | Present only on failure — full stack trace. |

The binary video/audio file itself lives in the run's **default key‑value store** under `storageKey`.

### ▶️ How to Use

1. **Run on Apify Console:** Open the [YouTube Video Downloader Actor page](https://apify.com/scrapeio/youtube-downloader), click **Try for free**, paste a `youtubeUrl`, select `quality`, and press **Start**. Download the file from **Storage → default key‑value store → `storageKey`**.
2. **Via API:** Trigger runs with the [Apify REST API](https://docs.apify.com/api/v2) or `ApifyClient`, then fetch the file via the key‑value store API.
3. **Via CLI:** Run with the [Apify CLI](https://docs.apify.com/cli):
   ```bash
   apify call scrapeio/youtube-downloader \
     --input='{"youtubeUrl":"https://youtu.be/dQw4w9WgXcQ","quality":"1080p"}'
   ```

### 🔗 API Example (JavaScript)

```js
const { ApifyClient } = require('apify-client');

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('scrapeio/youtube-downloader').call({
  youtubeUrl: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  quality: '1080p',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const result = items[0];
console.log(`Downloaded ${result.videoTitle} (${result.fileSizeGB.toFixed(2)} GB)`);

const store = client.keyValueStore(run.defaultKeyValueStoreId);
const fileBuffer = await store.getRecord(result.storageKey);
console.log(`File available via storage key: ${result.storageKey}`);
```

### 📈 Why Use This YouTube Video Downloader?

- **Speed & Automation:** Download any video to cloud storage in seconds with one API call — perfect for unattended pipelines.
- **Quality Flexibility:** Pick `1080p`, `4K`, or `bestaudio` per run; the Actor intelligently falls back to the closest available format.
- **Cloud‑Native Storage:** Files land directly in Apify's key‑value store — no local disk required and accessible via URL.
- **Structured Billing:** Unique cost breakdown object makes it trivial to chargeback usage by team, project, or client.
- **yt‑dlp Powered:** Built on the industry‑standard `yt-dlp` engine, tuned for YouTube's current extractor behavior and DASH streams.
- **Developer Integrations:** Apify REST API, webhooks, scheduler, and SDKs in JavaScript and Python — plug into any ML or media pipeline.

### ❓ FAQ

**Q: Does the Actor use a proxy for YouTube?**\
If you set **`PROXY_URL`** on the Actor (recommended for strict networks), `yt-dlp` uses it. Do not hardcode credentials in the repo; use Apify **Environment variables** for the full proxy URL.

**Q: Is it legal to download YouTube videos?**
YouTube's [Terms of Service](https://www.youtube.com/t/terms) restrict downloads except via YouTube's own features unless the content is licensed (e.g., Creative Commons, public domain, or your own uploads). You are responsible for compliance with copyright, DMCA, and local law.

**Q: Does this support playlists?**
No — this Actor is oriented toward **single videos** (yt‑dlp's `--no-playlist` flag is enabled). Loop over URLs to process a playlist.

**Q: Where does the downloaded file end up?**
In the run's default key‑value store, under the `storageKey` returned in the Dataset row. Download from the Storage tab or via the Apify API.

**Q: Can I download only the audio?**
Yes — set `quality` to `bestaudio`, `highestaudio`, `worstaudio`, or `lowestaudio`. The output is typically an `m4a` or `webm` audio file.

**Q: What happens if my chosen quality is unavailable?**
The Actor falls back to the **closest available format** provided by yt‑dlp's format matcher.

**Q: Does it support YouTube Shorts?**
Yes — pass a `youtube.com/shorts/...` URL. The Actor downloads Shorts the same way as standard videos.

**Q: What is the `billing` object — does it charge my card?**
**No.** `billing` is a **structured cost estimate** based on your configurable rates and measured GB usage. It is purely for internal chargeback math and does not trigger any real payment.

**Q: Are there file‑size limits?**
Apify key‑value store records have per‑file limits (check the [current docs](https://docs.apify.com/platform/storage/key-value-store)). Very large files (e.g., long 4K videos) may need chunked storage or a custom pipeline.

### 📣 Start Downloading YouTube Videos on Apify

**[Run the YouTube Video Downloader on Apify now →](https://apify.com/scrapeio/youtube-downloader)** and integrate cloud‑native video downloads into your AI, archival, or media workflows.

***

### 🔗 Related Shop Intel / ScrapeIO actors on Apify

Combine with these Apify Actors to build full media, paid social, and e‑commerce pipelines:

- **[YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper)** — transparency-style YouTube ads by brand or keyword.
- **[YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder)** — resolve brand names to `brandId` for the ad scraper.
- **[LinkedIn Ad Library Scraper](https://apify.com/scrapeio/linkedin-ad-library-scraper)** — B2B ads: keyword, advertiser, payer, or pasted Library URL.
- **[Google News Scraper](https://apify.com/scrapeio/google-news-scraper)** — headlines, sources, and publisher links by keyword.
- **[Google Maps Scraper](https://apify.com/scrapeio/google-maps-scraper-advance)** — local businesses, reviews, and contacts.
- **[Amazon Scraper](https://apify.com/scrapeio/amazon-scraper)** — ASINs, prices, and search rankings across marketplaces.
- **[Facebook Ad Library Scraper](https://apify.com/scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium)** — Meta ads by keyword, Page ID, or URL.
- **[Instagram Ads Scraper](https://apify.com/scrapeio/instagram-scraper-premium)** — Instagram‑only ads with creative and copy.
- **[WhatsApp Ads Scraper](https://apify.com/scrapeio/whatsapp-scraper-premium)** — Click‑to‑WhatsApp ad intelligence.
- **[Facebook Ad Library Brand Finder](https://apify.com/scrapeio/facebook-ad-library-suggestions)** — resolve brand names to verified Page IDs.

***

Built by **[ScrapeIO](https://apify.com/scrapeio)** on Apify.

### FAQ

**How do I download YouTube videos with Apify?**
Pass youtubeUrl to scrapeio/youtube-downloader. Pin it in Cursor MCP.

**Can I run this Actor with Apify AI?**
Yes. In [Apify Console](https://console.apify.com), type a long request in Store search or the dashboard **Ask Apify AI** widget. Apify AI matches this README, fills the input schema, asks you to confirm, then returns the dataset. This Actor uses **limited permissions** (not full-account access) and is not a rental Actor, so it is eligible for Apify AI.

**Does this work from Cursor, Claude, or ChatGPT?**
Yes. Connect the [Apify MCP server](https://mcp.apify.com). Agents call `search-actors`, `fetch-actor-details`, and `call-actor`. Ranking uses the same signals as Store search and Actor quality score: a clear README plus documented input and output schemas.

Powered by **[AdScrape](https://www.adscrape.in/)**.

# Actor input Schema

## `youtubeUrl` (type: `string`):

The URL of the YouTube video, Short, or live recording to download. Playlist URLs will only download the first video (yt-dlp --no-playlist is enforced).

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

Desired video quality. If the requested quality is not available, the closest available format is used (yt-dlp resolves automatically).

## Actor input object example

```json
{
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "quality": "best"
}
```

# Actor output Schema

## `manifest` (type: `string`):

JSON record: videoId, title, durationSeconds, billingUnitsCharged, storageKey, file size, and errors if any.

## `keyValueStore` (type: `string`):

Open the default store for this run. Download the binary using the storageKey field from the dataset row (e.g. GET .../records/{storageKey}).

## `runInput` (type: `string`):

The youtubeUrl and proxy settings used for this run.

# 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 = {
    "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeio/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 = { "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }

# Run the Actor and wait for it to finish
run = client.actor("scrapeio/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 '{
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}' |
apify call scrapeio/youtube-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapeio/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/qXgCwMYooJZ8H1PYO/builds/OyuUoo2c4Uca9ECAM/openapi.json