YouTube Video Downloader — Cloud Downloads with Quality Selection & Apify Storage

Download YouTube videos and audio directly to Apify Key-Value Store from a single URL. The Scrapeify YouTube Downloader wraps yt-dlp with Android/Web extractor arguments, Chrome-class User-Agent, optional proxy routing, and resilient info-JSON probes. Each run writes a Dataset record with video ID, title, file size, storage key, and an itemized billing breakdown — giving your automation pipeline a machine-readable manifest to retrieve the binary from cloud storage.

Built for media archival, ML preprocessing pipelines, automated transcription workflows, and any automation where you need video or audio objects in cloud storage rather than just links.

---

Features

Capability	Detail
URL validation	Accepts youtube.com/watch, youtu.be, YouTube Shorts, and common URL shapes
Quality modes	best, highest, worst, lowest, bestaudio, highestaudio, worstaudio, lowestaudio, 720p, 1080p, 1440p, 2160p (4K)
Format negotiation	yt-dlp handles merge logic — outputs mp4, webm, mkv, m4a, or mp3 depending on quality selection
No playlist downloads	--no-playlist enforced; processes single videos only
Proxy support	Pass-through to yt-dlp via PROXY_URL environment variable
Binary in KV	Content-type inferred from extension; stored in Apify Key-Value Store
Machine-readable manifest	Dataset row with storageKey, fileSizeBytes, fileSizeGB, videoId, videoTitle
Billing breakdown	Itemized billing object with per-event cost breakdown (illustrative rates)
Dual code paths	Proxy-aware execPromise path plus direct getVideoInfo probe for resilient info extraction

---

Use Cases

Automated Transcription Pipelines

Download audio tracks (bestaudio) and pass the KV storage URL to speech-to-text services (Whisper, AssemblyAI, Rev AI). The actor's storageKey gives your pipeline an unambiguous reference to the audio object in cloud storage.

AI & ML Preprocessing

Stage video clips before vision model analysis, multimodal LLM pipelines, or video classification training. Download at target resolution (720p, 1080p) and trigger downstream processing jobs using the Dataset manifest.

Media Archival

Archive video content tied to URLs for compliance, research, or content preservation purposes — subject to rights clearance. The KV storage approach keeps artifacts alongside Apify run data.

RAG & Knowledge Pipelines

Chain: download audio → transcribe → chunk transcript → embed → index in vector database with youtubeUrl as citation metadata. The structured Dataset manifest provides the handoff point between the downloader and your transcription step.

Automated Demo & Content Workflows

Fetch specific video samples for product demos, training datasets, or content libraries. Orchestrate across multiple videos at the scheduler level using parallel Apify actor runs.

Creative Intelligence

Download competitor ad creatives or branded content from YouTube for frame-level analysis, competitive benchmarking, or brand safety review (rights permitting).

---

Why Choose This Actor

• Battle-tested extractor — yt-dlp handles YouTube's format negotiation, codec selection, and stream merging
• Cloud storage native — artifacts land directly in Apify Key-Value Store where integrations expect binary objects
• Manifest-driven — storageKey + byte counts + videoId give downstream steps everything needed for retrieval and metering
• Quality flexibility — 12 quality modes from audio-only to 4K video with automatic fallback to closest available

---

Quick Start

1. Open the Scrapeify YouTube Downloader on Apify Console.
2. Paste a youtubeUrl (e.g. https://www.youtube.com/watch?v=dQw4w9WgXcQ).
3. Select a quality from the dropdown (default: best).
4. After the run: open the Dataset for the download manifest.
5. Retrieve the binary from Storage → Key-Value Store → storageKey.

Tip: Use bestaudio for transcription pipelines to avoid downloading unnecessary video streams. Use 1080p or 720p to cap storage costs for large batches.

---

Input Schema

{
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "quality": "1080p"
}

Field	Type	Default	Description
youtubeUrl	string	Demo URL	YouTube video URL. Supports youtube.com/watch, youtu.be, and Shorts.
quality	enum	best	Quality selector. See full options below.

Quality Options

Value	Description
best	Best available video + audio (auto-merge)
highest	Highest quality — alias for best
worst / lowest	Lowest quality for minimal storage
bestaudio / highestaudio	Best audio stream only — no video
worstaudio / lowestaudio	Lowest audio quality
720p	Cap at 720p height
1080p	Cap at 1080p height
1440p	Cap at 1440p height
2160p	4K — largest files

If requested quality is unavailable, yt-dlp falls back to the closest available option.

---

Output Schema

Dataset Row (download manifest)

{
  "success": true,
  "videoId": "dQw4w9WgXcQ",
  "videoTitle": "Rick Astley — Never Gonna Give You Up (Official Music Video)",
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "requestedQuality": "1080p",
  "downloadedQuality": "1080p",
  "filePath": null,
  "fileSizeBytes": 125000000,
  "fileSizeGB": 0.1164,
  "storageKey": "video_dQw4w9WgXcQ_1715000000000",
  "storageSizeGB": 0.1164,
  "billing": {
    "events": [
      {
        "eventName": "actor_start",
        "eventType": "fixed",
        "description": "Cost per actor execution",
        "cost": 0.10,
        "quantity": 1,
        "unit": "event",
        "rate": 0.10,
        "rateUnit": "USD per event"
      },
      {
        "eventName": "download",
        "eventType": "usage",
        "description": "Cost per GB downloaded",
        "cost": 0.1164,
        "quantity": 0.1164,
        "unit": "GB",
        "rate": 1.00,
        "rateUnit": "USD per GB"
      },
      {
        "eventName": "storage",
        "eventType": "usage",
        "description": "Cost per GB in Apify Key-Value Store",
        "cost": 0.0582,
        "quantity": 0.1164,
        "unit": "GB",
        "rate": 0.50,
        "rateUnit": "USD per GB"
      }
    ],
    "totalCost": 0.2746,
    "costPerActorStart": 0.10,
    "costPerGBDownloaded": 1.00,
    "costPerGBStorage": 0.50,
    "dataDownloadedGB": 0.1164,
    "storageGB": 0.1164
  }
}

Field	Type	Description
success	boolean	true if download and KV write completed
videoId	string	YouTube video ID extracted from URL
videoTitle	string	Video title from yt-dlp metadata
requestedQuality	string	Input quality parameter
downloadedQuality	string	Actual quality resolved by yt-dlp
fileSizeBytes	integer	Binary size in bytes
fileSizeGB	number	Binary size in GB (2 decimal places)
storageKey	string	Key-Value Store key for binary retrieval
billing	object	Itemized cost breakdown (illustrative rates — reconcile with Apify plan)

Binary retrieval: GET https://api.apify.com/v2/key-value-stores/{storeId}/records/{storageKey}?token={token}

---

API Examples

cURL

curl "https://api.apify.com/v2/acts/scrapeify~youtube-downloader/runs?token=$APIFY_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "quality": "1080p"
  }'

Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("scrapeify/youtube-video-downloader").call(
    run_input={
        "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "quality": "1080p",
    }
)

# Get manifest from Dataset
items = client.dataset(run["defaultDatasetId"]).list_items().items
manifest = items[0]

if manifest["success"]:
    storage_key = manifest["storageKey"]
    store_id = run["defaultKeyValueStoreId"]
    print(f"Binary at: /key-value-stores/{store_id}/records/{storage_key}")

JavaScript / Node.js

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor("scrapeify/youtube-video-downloader").call({
  youtubeUrl: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  quality: "bestaudio",
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const { storageKey, fileSizeBytes, success } = items[0];

if (success) {
  console.log(`Audio ready: ${storageKey} (${(fileSizeBytes / 1e6).toFixed(1)} MB)`);
}

---

Integration Examples

Transcription Pipelines (Whisper / AssemblyAI)

# 1. Download audio
run = client.actor("scrapeify/youtube-video-downloader").call(
    run_input={"youtubeUrl": url, "quality": "bestaudio"}
)
manifest = client.dataset(run["defaultDatasetId"]).list_items().items[0]

# 2. Retrieve binary from KV store
store_id = run["defaultKeyValueStoreId"]
audio = client.key_value_store(store_id).get_record(manifest["storageKey"])

# 3. Pass to speech-to-text service
transcript = whisper_client.transcribe(audio["value"])

n8n

HTTP node → trigger Apify run → poll run status → second HTTP node fetches KV binary via Apify API → pass to a transcription or storage node.

LangChain Tool

from langchain.tools import tool

@tool
def download_youtube_audio(url: str) -> dict:
    """Download YouTube audio to Apify KV Store and return storage manifest."""
    run = client.actor("scrapeify/youtube-video-downloader").call(
        run_input={"youtubeUrl": url, "quality": "bestaudio"}
    )
    return client.dataset(run["defaultDatasetId"]).list_items().items[0]

CrewAI

A MediaFetchAgent downloads audio via this tool. A downstream TranscriptionAgent retrieves the binary using storageKey and processes it with Whisper. An IndexingAgent chunks and embeds the transcript for RAG retrieval.

Gemini File API

Download video with this actor → retrieve binary from KV store → upload to Gemini File API for multimodal analysis using the storageKey reference.

AutoGen Multi-Agent

# UserProxyAgent passes URL list; DownloadAgent calls tool per URL;
# TranscriptAgent processes each manifest sequentially

RAG Knowledge Pipeline

Download → transcribe → chunk by sentence/paragraph → embed with youtubeUrl as citation metadata → index in Pinecone/Weaviate → enable semantic video search.

---

Frequently Asked Questions

1. Does this bypass YouTube Premium or DRM-protected content? No. The actor only downloads what yt-dlp can access without authentication — public, non-DRM-protected videos.

2. What output formats are supported? yt-dlp selects the container format based on quality and merge logic. Typical outputs: mp4, webm, mkv for video; m4a, mp3 for audio.

3. How do I retrieve the downloaded binary? Use the Apify API: GET /v2/key-value-stores/{storeId}/records/{storageKey}. The store ID is in run.defaultKeyValueStoreId.

4. What is the maximum file size? Limited by Apify Key-Value Store item size limits. Use lower quality settings for long videos to stay within limits.

5. Does it handle YouTube Shorts? Yes — Shorts URLs are supported when they validate as YouTube URLs.

6. Can I download playlists? No — --no-playlist is enforced by design. Batch across multiple videos at the orchestration layer.

7. How accurate is the billing breakdown? The billing block contains illustrative rates defined in the actor code. Reconcile actual charges with your Apify plan pricing.

8. What causes success: false in the Dataset? Invalid URL, yt-dlp subprocess errors, network failures, or KV write failures. Check run logs for the specific error.

9. How do I disable proxy routing? Clear or remove the PROXY_URL environment variable in the Actor settings.

10. What yt-dlp client arguments are used? Android/Web extractor arguments with a Chrome-class User-Agent. This reduces bot detection errors compared to naive HTTP clients.

11. How do I handle YouTube bot detection errors? Update the actor to the latest version (yt-dlp is updated regularly for extractor compatibility). Use a proxy via PROXY_URL. Check logs for the specific error code.

12. Can I download audio-only for transcription? Yes — use bestaudio or highestaudio for the smallest file size suitable for speech-to-text.

13. What happens with very long videos? Download time scales with video duration and quality. Very long videos at high quality may time out or produce large files.

14. Are subtitles or captions included? Not in the primary output. Customize yt-dlp arguments in a fork if caption tracks are required.

15. Does it support YouTube Music URLs? Primary support is for standard YouTube video URLs. YouTube Music URLs may or may not work — test before relying on production.

16. Can I check file integrity after download? Compare fileSizeBytes against expected duration × bitrate as a rough sanity check. Detailed integrity checks require reading the binary.

17. What happens to temporary files after the run? Temp directories are cleaned up after successful KV write. Check logs if cleanup warnings appear.

18. How do I batch downloads across multiple videos? Launch parallel Apify actor runs at the orchestration layer — one video per run. Apify's actor orchestration handles concurrency.

19. Is there a way to get video metadata without downloading? The info-JSON probe in the code path can surface metadata. For metadata-only workflows, omit the download step in a fork.

20. What codecs are in the output container? Depends on yt-dlp merge logic for the requested quality. Common: H.264 in mp4, VP9 in webm, AAC or Opus for audio. Ensure player/processing tool codec compatibility.

21. Can I trigger this from a webhook? Yes — use the Apify Runs API endpoint in any HTTP-capable webhook system (n8n, Zapier, Make, GitHub Actions).

22. What does downloadedQuality mean vs requestedQuality? If the exact requested quality isn't available, yt-dlp falls back to the closest option. downloadedQuality reflects what was actually downloaded.

23. Does the actor support private YouTube videos? No — only publicly accessible videos without authentication requirements.

24. How do I clean up KV storage after processing? Delete records via Apify API after downstream processing is complete to manage storage costs.

25. Is this suitable for high-volume batch transcription? Yes with orchestration. Launch parallel runs per video URL; collect manifest rows; trigger transcription pipeline per storageKey. Design for network and KV throughput limits.

---

Best Practices

• Choose quality for use case — bestaudio for transcription; 720p for general processing; 1080p for visual analysis
• Set region-appropriate proxies when Google blocks egress from Apify's datacenter IPs
• Poll run status before reading KV — avoid race conditions in fast orchestrators
• Clean up KV storage after processing to manage costs on high-volume batch workflows
• Parallelize at orchestration layer — one video per Apify run, not one massive sequential pipeline
• Validate success: true before passing storageKey to downstream steps
• Check fileSizeGB in the manifest for cost estimation before scaling to large batches

---

Performance & Scalability

Factor	Guidance
Throughput	Network-bound; download speed depends on video size and egress bandwidth
Parallelism	Orchestrate parallel actor runs per URL — each run is independent
Storage cost	Monitor cumulative fileSizeGB across runs; clean up after processing
Timeout	Long videos at high quality may take several minutes — account for this in orchestrator timeouts
Format negotiation	yt-dlp merge adds latency for combined video+audio streams; audio-only is faster

---

AI & Automation Workflows

Recommended chain for knowledge extraction:

1. Download audio with bestaudio quality
2. Retrieve binary from KV store using storageKey
3. Transcribe with Whisper or AssemblyAI
4. Chunk transcript by sentence or paragraph
5. Embed chunks with youtubeUrl as citation metadata
6. Index in vector database
7. Enable semantic search and AI-generated answers with YouTube citations

Multimodal pipeline:

1. Download video at 720p
2. Extract keyframes
3. Run vision model or multimodal LLM on frames
4. Combine with audio transcript for comprehensive video understanding

---

Error Handling

Scenario	Behavior
Invalid YouTube URL	Error thrown before download attempt
yt-dlp subprocess error	Logged; Dataset captures success: false with message
KV write failure	Logged; Dataset row reflects failure
Proxy unavailable	Falls back to direct egress if PROXY_URL is unset
Quality unavailable	yt-dlp falls back to closest available; downloadedQuality reflects actual

---

Trust & Reliability

Scrapeify maintains this actor wrapper around yt-dlp with sensible defaults for YouTube's extractor client requirements. The architecture focuses on:

• Resilient info-JSON probes for metadata extraction before download
• Proxy-aware dual code paths for format negotiation
• Explicit success flag and typed billing breakdown for autonomous pipeline operation
• Apify KV Store as the canonical binary artifact location

---

Related Scrapeify Actors

Explore the full Scrapeify suite — chain these actors together for end-to-end automation pipelines:

Actor	What it does
Amazon Scraper	ASINs, prices, sponsored flags across 23 marketplaces
Instagram Ad Library Scraper	Instagram-only ads from Meta Ad Library
Meta Ad Library Scraper	Facebook & Instagram ads with sort options
WhatsApp Ad Scraper	Click-to-WhatsApp ad creatives
Meta Brand & Page ID Finder	Resolve brand names to numeric Page IDs
Google Maps Scraper	Local business leads, reviews, emails, contacts
Google News Scraper	Headlines, sources, article URLs (up to 2K)

---

YouTube is a trademark of Google LLC. This actor is not affiliated with or endorsed by Google or YouTube.