YouTube Video Downloader — Save Videos to Cloud Storage

YouTube video downloader for Apify. Download YouTube videos or Shorts to Key-Value Store as MP4 — no server setup. Powered by yt-dlp with proxy support and format fallbacks. Billing is 1 credit per 30 seconds of video length. Long videos download in 30-second chunks and merge automatically. Each run writes a Dataset manifest with storageKey, duration, billing units, and file size.

Built for media archival, ML preprocessing, transcription pipelines, and automations that need video in cloud storage.

---

Features

Capability	Detail
URL validation	Accepts youtube.com/watch, youtu.be, YouTube Shorts, and common URL shapes
First-available format	No quality input — yt-dlp tries worst → mp4 → auto → merge → best → sectioned fallbacks
Duration-based billing	ceil(durationSeconds / 30) blocks via video-thirty-seconds pay-per-event
Chunked long downloads	Videos longer than one block use --download-sections (30s slices) and ffmpeg merge
Built-in proxy	DataImpulse residential proxy is used automatically (no proxy input on the form)
No playlist downloads	--no-playlist enforced; processes single videos only
Binary in KV	Content-type inferred from extension; stored in Apify Key-Value Store
Machine-readable manifest	Dataset row with storageKey, durationSeconds, billingUnitsCharged, fileSizeBytes
Billing summary	billing object with PPE model, units charged, and estimated event cost

---

Use Cases

Automated Transcription Pipelines

Download media 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/video object in cloud storage.

AI & ML Preprocessing

Stage video clips before vision model analysis, multimodal LLM pipelines, or video classification training. 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 → transcribe → chunk transcript → embed → index in vector database with youtubeUrl as citation metadata.

---

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
• Duration-based pricing — predictable billing tied to video length, not resolution
• Resilient fallbacks — multiple player clients, format selectors, and sectioned downloads reduce failure rates

---

Quick Start

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

Tip: Billing is based on video duration from YouTube metadata — a 2-minute Short costs 4×30s blocks regardless of format picked.

---

Input Schema

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

Field	Type	Default	Description
youtubeUrl	string	Demo Shorts URL	YouTube video or Shorts URL. Required.

Legacy quality input is ignored if present — the actor always picks the first working format.

---

Output Schema

Dataset Row (download manifest)

There is no separate OUTPUT key-value record. The run summary lives in the Dataset (one row per run).

{
  "success": true,
  "videoId": "dQw4w9WgXcQ",
  "videoTitle": "Rick Astley — Never Gonna Give You Up (Official Music Video)",
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "durationSeconds": 213,
  "durationSource": "youtube_metadata_yt_dlp",
  "downloadedSeconds": 213,
  "billingUnitsNeeded": 8,
  "billingUnitsCharged": 8,
  "downloadStrategy": "worst",
  "formatSelector": "worst",
  "sectionCount": null,
  "playerClient": "android,web",
  "usedApifyProxy": true,
  "filePath": null,
  "fileSizeBytes": 11754321,
  "fileSizeGB": 0.0109,
  "storageKey": "video_dQw4w9WgXcQ_1717234567890",
  "billing": {
    "model": "PAY_PER_EVENT",
    "secondsPerUnit": 30,
    "durationSeconds": 213,
    "unitsNeeded": 8,
    "chargedUnits": 8,
    "maxDownloadSeconds": 213,
    "eventName": "video-thirty-seconds",
    "unitPriceUsd": 0.01,
    "estimatedEventCostUsd": 0.08,
    "fileSizeBytes": 11754321
  }
}

Field	Type	Description
success	boolean	true if download and KV write completed
videoId	string	YouTube video ID from metadata
videoTitle	string	Title from yt-dlp --dump-json
durationSeconds	number	Length from YouTube metadata (used for billing)
durationSource	string	Always youtube_metadata_yt_dlp
downloadedSeconds	number	Seconds actually downloaded (may be less if budget capped)
billingUnitsNeeded	integer	ceil(durationSeconds / 30), minimum 1
billingUnitsCharged	integer	30s blocks charged after successful download
downloadStrategy	string	Which yt-dlp path succeeded: worst, mp4_or_worst, auto, bv_ba_merge, best, or sectioned
formatSelector	string	yt-dlp -f value used
sectionCount	integer/null	Number of 30s slices when sectioned download was used
storageKey	string	Key-Value Store key for binary retrieval
fileSizeBytes	integer	Binary size in bytes
billing	object	Pay-per-event breakdown when PPE is enabled

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

How duration is identified

Before any bytes are downloaded, yt-dlp resolves the URL with --dump-json and reads the duration field (seconds). That value drives billing (ceil(duration/30)) and chunk planning. Duration is not measured from the downloaded file.

---

API Examples

cURL

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

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",
    }
)

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}")
    print(f"Billed: {manifest['billingUnitsCharged']}×30s blocks")

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",
});

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

if (success) {
  console.log(`Ready: ${storageKey} (${(fileSizeBytes / 1e6).toFixed(1)} MB, ${billingUnitsCharged}×30s)`);
}

---

Integration Examples

Transcription Pipelines (Whisper / AssemblyAI)

run = client.actor("scrapeify/youtube-video-downloader").call(
    run_input={"youtubeUrl": url}
)
manifest = client.dataset(run["defaultDatasetId"]).list_items().items[0]
store_id = run["defaultKeyValueStoreId"]
media = client.key_value_store(store_id).get_record(manifest["storageKey"])
transcript = whisper_client.transcribe(media["value"])

n8n

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

---

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. Can I choose video quality? No. The actor picks the first format that works (worst → mp4 → auto → merge → best → sectioned). Legacy quality input is ignored.

3. How is billing calculated? 1 pay-per-event credit per 30 seconds of video length, rounded up. Duration comes from YouTube metadata before download. Event name: video-thirty-seconds.

4. 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.

5. What output formats are supported? yt-dlp selects the container based on what works. Typical outputs: mp4, webm, mkv for video; m4a, mp3 for audio.

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

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

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

9. How is proxy handled? A built-in DataImpulse residential proxy is used automatically. Override with the PROXY_URL environment variable on the Actor if needed.

10. What happens with very long videos? The actor downloads in 30-second sections and merges with ffmpeg. Billing scales with total duration. Budget caps may truncate downloadedSeconds.

11. What yt-dlp client arguments are used? Android/Web/iOS/mweb/tv_embedded player clients tried in order with Chrome-class User-Agent.

12. How do I handle YouTube bot detection errors? Ensure Apify Residential Proxy is enabled. The actor retries with multiple player clients and format selectors.

13. Are subtitles or captions included? Not in the primary output.

14. Can I batch downloads across multiple videos? Launch parallel Apify actor runs at the orchestration layer — one video per run.

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

---

Best Practices

• Enable Residential Apify Proxy — required for reliable YouTube access on Apify
• Poll run status before reading KV — avoid race conditions in fast orchestrators
• Check billingUnitsNeeded before running long videos to estimate cost
• Validate success: true before passing storageKey to downstream steps
• Clean up KV storage after processing to manage costs on high-volume batch workflows
• Parallelize at orchestration layer — one video per Apify run

---

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 use sectioned downloads — account for merge time in orchestrator timeouts
Billing	Duration from metadata, not file size — Shorts and 4K cost the same per second

---

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	Warning logged; direct egress may fail on YouTube
Insufficient billing budget	Error before download if zero blocks allowed; partial download if budget < full duration
Format unavailable	Actor tries next strategy in fallback chain

---

Trust & Reliability

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

• Metadata probe before download for accurate duration billing
• Multiple player clients and format selectors for resilience
• Sectioned downloads for long videos with ffmpeg merge
• Explicit success flag and typed billing breakdown for autonomous pipeline operation
• Apify KV Store as the canonical binary artifact location

---

Related Scrapeify Actors

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.

---

Built by Scrapeify on Apify.

Powered by AdScrape.