YouTube Video Downloader - 4K, MP4 & MP3

YouTube video downloader for URLs or plain 11-character video IDs: process a batch in one Gateway-backed run and receive videos up to 4K in MP4/WebM, MP3 audio, standalone .info.json metadata, or subtitle files through direct links or supported S3-compatible storage.

---

What you can download

• Four Output Modes in One Actor: outputType selects media (video or MP3 audio), metadata (standalone .info.json), or subtitles (standalone subtitle files).
• High Quality Video Downloads: Full videos in up to 4K (2160p), 2K (1440p), 1080p Full HD, 720p HD, 480p or 360p.
• Audio-Only Extraction (MP3): outputType=media + format=mp3. Current Gateway supports MP3 only (no M4A/FLAC).
• Standalone Metadata: outputType=metadata delivers <video_id>.info.json only — no media bytes.
• Standalone Subtitles: outputType=subtitles + subtitleLanguages delivers VTT/SRT/JSON3/SRV1-3/TTML subtitle files (manual + automatic), one row per video with every language in downloadFiles.
• Shorts & Standard Videos: Fully supports standard YouTube videos, YouTube Shorts, and youtu.be short links.
• Zero Memory Overhead (Ultra-Lightweight): Runs smoothly on Apify's minimal 128MB RAM tier.
• Direct High-Speed Delivery: Download links are generated as direct pre-signed URLs (retained ~24h), eliminating slow double-transfers and bandwidth bottlenecks.
• Custom Cloud Storage Integration: Pipe outputs directly into your Amazon S3, Google Cloud Storage, or DigitalOcean Spaces bucket. Azure is not supported.
• Real-time Live Progress & ETA: Transparent progress tracking via Apify Console (fetching metadata / downloading / processing / uploading).
• Bounded Concurrency + Configurable Timeout: Default 20 concurrent "submit + SSE" worker units (1-50), and per-mode task timeouts (metadata/subtitles 30 min, audio 2 h, video 4 h) — both configurable.
• One-Run Batch Grouping: All URLs in one run share the same batch_id (<APIFY_USER_ID>:<APIFY_ACTOR_RUN_ID>), which the Gateway groups into a single Titan project (one project, N tasks, parallel downloads). Duplicate video IDs are deduplicated (one Dataset row + one charge).

---

📋 Input Configuration

Parameter	Type	Required	Default	Description
startUrls	Array of strings	Yes	-	YouTube URLs (watch, Shorts, youtu.be) or plain 11-char video IDs.
outputType	String	No	"media"	media (video/audio), metadata (standalone .info.json), subtitles (standalone subtitle files). One run uses exactly one mode.
quality	String	No	"720"	Media/video only: 360, 480, 720, 1080, 1440, 2160. Ignored for audio/metadata/subtitles.
format	String	No	"mp4"	Media only: mp4, webm (video), mp3 (audio only). Ignored for metadata/subtitles.
subtitleLanguages	Array of strings	Subtitles	-	1-10 language codes (e.g. en, zh-Hans) or ["all"] for every available subtitle.
subtitleFormat	String	No	"vtt"	srt, vtt, json3, srv1, srv2, srv3, ttml.
storageType	String	No	"apify"	apify (Titan platform storage / pre-signed links), aws, gcp, digitalocean. Azure is not supported.
s3Bucket	String	External	-	Bucket/container name for aws/gcp/digitalocean.
s3Region	String	No	-	Storage region (us-east-1, auto, nyc3). Required for DigitalOcean.
s3AccessKeyId	String	External	-	Access key ID for external storage.
s3SecretAccessKey	String	External	-	Secret access key for external storage.
maxWaitSec	Integer	No	mode default	Per-task SSE timeout in seconds (metadata/subtitles 1800, audio 7200, video 14400).
maxConcurrency	Integer	No	20	Bounded concurrency (1-50) for submit + SSE worker units.

Field combination rules (sending forbidden fields returns OUTPUT_CONFIG_CONFLICT):

• Video: outputType=media, quality, format=mp4/webm — no subtitle fields.
• Audio: outputType=media, format=mp3, fixed quality=720 — no subtitle fields.
• Metadata: outputType=metadata — omit quality/format and all subtitle fields.
• Subtitles: outputType=subtitles + subtitleLanguages — omit quality and media format.

Example Input JSON

{
  "startUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/jNQXAC9IVRw",
    "9bZkp7q19f0"
  ],
  "outputType": "media",
  "quality": "1080",
  "format": "mp4"
}

Audio run:

{ "startUrls": ["dQw4w9WgXcQ"], "outputType": "media", "format": "mp3" }

Metadata run:

{ "startUrls": ["dQw4w9WgXcQ"], "outputType": "metadata" }

Subtitles run:

{
  "startUrls": ["dQw4w9WgXcQ"],
  "outputType": "subtitles",
  "subtitleLanguages": ["en", "zh-Hans"],
  "subtitleFormat": "vtt"
}

---

📊 Output Dataset Format

Each processed video produces a structured dataset record with metadata and download links. The downloadFiles array is the authoritative delivery record and is always persisted in full (audio tasks include the attached .info.json; multi-language subtitles include one entry per delivered language).

Field	Type	Description
id	String	Unique YouTube video ID.
input	String	Original input URL provided.
title	String	Video title.
durationSec	Integer	Total duration in seconds.
outputType	String	media, metadata, or subtitles.
quality / format	String	Media mode only.
subtitleLanguages / subtitleFormat	Array / String	Subtitles mode only.
fileSizeBytes / fileSizeMB	Number	Main delivered file size.
downloadedFileUrl	String	Main file's direct download link (~24h retention on platform storage; may be absent when external storage only returns an object key).
fileKey	String	Main file's storage object key.
downloadFiles	Array	Complete list of delivered files (kind, filename, fileSizeBytes, downloadedFileUrl, fileKey, status). Authoritative.
status	String	completed, failed, timeout, or skipped.
note	String	Expiration / usage instructions.

Example Output Record

{
  "id": "dQw4w9WgXcQ",
  "input": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "durationSec": 213,
  "outputType": "media",
  "format": "mp3",
  "fileSizeMB": 4.12,
  "downloadedFileUrl": "https://.../dQw4w9WgXcQ.mp3",
  "fileKey": ".../dQw4w9WgXcQ.mp3",
  "downloadFiles": [
    { "kind": "audio", "filename": "dQw4w9WgXcQ.mp3", "fileSizeBytes": 4321000, "downloadedFileUrl": "https://.../dQw4w9WgXcQ.mp3", "fileKey": ".../dQw4w9WgXcQ.mp3", "status": "available" },
    { "kind": "metadata", "filename": "dQw4w9WgXcQ.info.json", "fileSizeBytes": 245000, "downloadedFileUrl": "https://.../dQw4w9WgXcQ.info.json", "fileKey": ".../dQw4w9WgXcQ.info.json", "status": "available" }
  ],
  "status": "completed",
  "note": "Audio download link is retained for approximately 24h after delivery."
}

---

Use cases

• Archive authorized YouTube videos or Shorts for offline viewing in MP4 or WebM up to 4K.
• Extract MP3 audio and the accompanying .info.json for a batch of video URLs or IDs.
• Export standalone video metadata without downloading media bytes.
• Collect manual and automatic captions for selected languages or every available subtitle.
• Deliver completed files through temporary direct links or an AWS, GCP, or DigitalOcean bucket.

FAQ

Can I submit multiple YouTube URLs or video IDs?

Yes. Put all URLs or plain 11-character IDs in startUrls; duplicate video IDs are deduplicated within a run.

How long do platform download links remain valid?

Pre-signed links from Titan platform storage are retained for approximately 24 hours. External storage returns the configured object's delivery details instead.

Which video, audio, metadata, and subtitle formats are supported?

Video uses MP4 or WebM, audio uses MP3 only, metadata is delivered as .info.json, and subtitles support VTT, SRT, JSON3, SRV1-3, and TTML.

Related YouTube Actors

• YouTube Video Downloader
• YouTube MP3 Audio Downloader
• YouTube Video Metadata Scraper
• YouTube Transcript & Subtitles Scraper

---

💰 Pricing & Monetization (Pay-Per-Event)

This Actor uses Apify's Pay-Per-Event (PPE) model with a No Success, No Charge guarantee:

• Billing event is chosen by the delivered output:
  • video-download-success — video (media + mp4/webm)
  • audio-download-success — audio (media + mp3)
  • metadata-download-success — standalone metadata
  • subtitles-download-success — standalone subtitles
• You are only charged when all of these hold: Gateway returns completed, the requested output files exist, and the Dataset row was written successfully.
• Zero cost on failures, timeouts, cancellations, or missing output files.
• Minimal compute units: the Actor streams direct storage links without proxying raw bytes through the container.

---

⚖️ Legal & Fair Use Disclaimer

This Actor is designed solely for archiving, offline viewing of authorized content, or educational and fair-use research. Please respect the copyright of creators and YouTube's Terms of Service when using this Actor.