YouTube Video Downloader - Apify Actor

Advanced YouTube video downloader that uses direct YouTube API interaction (InnerTube) instead of yt-dlp. Designed for reliable extraction with residential proxy support.

📚 Documentation

• ./API.md - Complete API documentation with examples
• ./openapi.yaml - OpenAPI 3.0 specification for integration

Features

• Multiple Extraction Methods: InnerTube API (ANDROID, iOS, WEB, TV clients)
• Residential Proxy Support: Full support for Apify residential proxies with country selection
• Quality Selection: Choose from 144p to 1080p or best available
• Format Options: MP4, WebM, or Audio-only extraction
• Automatic Retry: Configurable retry attempts with exponential backoff
• Direct Download: Downloads to Apify Key-Value Store with public URLs
• Portable URLs: Android client extraction provides IP-independent video URLs

Why Not yt-dlp?

yt-dlp is blocked by YouTube's policies on many cloud platforms. This actor uses direct YouTube API interaction through the InnerTube API, which is the same API used by YouTube's own applications.

Quick Start

Using Apify CLI

apify call barksdale04/youtube-downloader --memory 4096 --input '{
  "youtubeUrls": ["https://www.youtube.com/watch?v=VIDEO_ID"],
  "quality": "720p",
  "useResidentialProxies": true
}'

Using API

curl -X POST "https://api.apify.com/v2/acts/barksdale04~youtube-downloader/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "youtubeUrls": ["https://www.youtube.com/watch?v=VIDEO_ID"],
    "quality": "720p"
  }'

Input Configuration

{
  "youtubeUrls": ["https://www.youtube.com/watch?v=VIDEO_ID"],
  "quality": "720p",
  "format": "mp4",
  "useResidentialProxies": true,
  "proxyCountry": "US",
  "maxRetries": 5,
  "extractionMethod": "auto",
  "downloadToStorage": true,
  "debugMode": false
}

Parameters

Parameter	Type	Default	Description
youtubeUrls	array	required	List of YouTube URLs to download
quality	string	"720p"	Video quality (144p, 240p, 360p, 480p, 720p, 1080p, best)
format	string	"mp4"	Output format (mp4, webm, audio)
useResidentialProxies	boolean	true	Use residential proxies for better success
proxyCountry	string	"US"	Country code for proxies
maxRetries	number	5	Max retry attempts per video
extractionMethod	string	"auto"	Extraction method (auto, innertube, player, embed)
downloadToStorage	boolean	true	Download files to Key-Value Store
debugMode	boolean	false	Enable verbose logging

Extraction Methods

The actor uses YouTube's InnerTube API with multiple client types. By default, it prioritizes clients that provide portable (non-IP-locked) URLs:

1. ANDROID (Default/Recommended): Mobile app client - provides portable URLs
2. iOS: iOS app client - also provides portable URLs
3. TV_EMBED: Smart TV embedded player
4. WEB: Standard web client (URLs may be IP-locked)
5. Embed: Parses YouTube embed pages

The auto mode tries these in order until one succeeds.

Output

Each video produces a result object:

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "videoId": "VIDEO_ID",
  "title": "Video Title",
  "author": "Channel Name",
  "duration": 300,
  "quality": "720p",
  "format": "video/mp4",
  "fileSize": "45.2 MB",
  "directUrl": "https://...",
  "downloadUrl": "https://api.apify.com/v2/key-value-stores/.../records/...?token=YOUR_TOKEN",
  "directStreamUrl": "https://rr5---sn-xxx.googlevideo.com/...",
  "status": "success"
}

Accessing Downloaded Files

There are three ways to access your downloaded videos:

1. Authenticated URL (downloadUrl) - Includes your API token, works immediately:

   $curl -L -o video.mp4 "https://api.apify.com/v2/key-value-stores/STORE_ID/records/VIDEO_ID_720p.mp4?token=YOUR_APIFY_TOKEN"
   

2. Direct YouTube Stream (directStreamUrl) - Direct from YouTube, expires in ~6 hours:

   $curl -L -o video.mp4 "DIRECT_STREAM_URL"
   

3. Apify Console - Download manually from:

   • Go to https://console.apify.com/storage/key-value-stores
   • Find the "youtube-downloads" store
   • Click on your video file to download

Making the Store Public (Optional)

To create publicly accessible URLs without tokens:

1. Go to https://console.apify.com/storage/key-value-stores
2. Find "youtube-downloads" store
3. Click Settings → Set "Access rights" to "Public"
4. Now you can use URLs without token:

   $curl -L -o video.mp4 "https://api.apify.com/v2/key-value-stores/youtube-downloads/records/VIDEO_ID_720p.mp4"
   

Troubleshooting

ERR_PROXY_CONNECTION_FAILED

If you see this error:

1. Ensure you have residential proxy credits available
2. Try a different proxy country
3. Run without proxies to test: useResidentialProxies: false

No formats found

YouTube may be blocking the extraction:

1. Try extractionMethod: "innertube_android" for mobile client
2. Enable residential proxies
3. Some videos may have regional restrictions

Slow downloads

Large files take time. Consider:

1. Use lower quality for faster downloads
2. Download only metadata by setting downloadToStorage: false

Usage Example

apify call youtube-downloader --memory 4096 --input '{
  "youtubeUrls": ["https://www.youtube.com/watch?v=VIDEO_ID"],
  "quality": "720p",
  "useResidentialProxies": true
}'

Technical Details

• Uses got-scraping for HTTP requests with fingerprint randomization
• Playwright for browser-based extraction fallback
• Supports both signed and unsigned video URLs
• Handles age-restricted content through mobile clients
• Automatic format selection based on availability

Limitations

• Cannot download DRM-protected content
• Live streams require HLS/DASH handling (partial support)
• Premium-only content requires authentication (not supported)
• Download speed depends on Apify's bandwidth and video size

License

ISC License - Built by ReelForgeAI