YouTube Video/Audio Downloader (Optimized)

A professional, high-performance Apify Actor to download videos or audio from YouTube. Built for speed and reliability, it utilizes software for accelerated downloads and dedicated residential proxies to minimize bot detection and bypass geographical restrictions.

🚀 Features

• Reliable Transfers: Uses one media connection per video so YouTube's IP-bound stream URLs remain valid.
• Bot Protection: Gives each video attempt its own residential exit IP and rotates to a different one only on retry.
• Flexible Formats: Download as high-quality video (MP4) or audio (MP3).
• Resolution Control: Supports qualities from 360p up to 4K (2160p).
• Robustness: Advanced retry logic with exponential backoff and automatic proxy rotation on failure.
• Metadata Aware: Automatically sanitizes filenames and handles Shorts, Live streams, and regular videos.
• Free Apify plans get 360p video. Audio is unaffected, and any paid plan removes the limit — the What you pay for section explains why.

📥 Input Parameters

Field	Type	Description	Default
startUrls	Array	List of YouTube video URLs to download.	Required
downloadType	String	Choose between video or audio.	video
quality	String	Preferred video quality (e.g., 720p, 1080p, 2160p).	720p

📊 Output Data Structure

The Actor produces a dataset where each item represents a download result:

{
  "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "downloadUrl": "https://api.apify.com/v2/key-value-stores/...",
  "format": "VIDEO",
  "resolution": "720p",
  "status": "SUCCESS"
}

• downloadUrl: A public link to the file stored in the Actor's Key-Value Store.
• resolution: The height of the file you actually received, which can be lower than the quality you asked for when YouTube does not publish that video at that height.
• status: Either SUCCESS or FAILED.
• notice: Only present when something needs explaining — for example a video limited to 360p because the run is on a free Apify plan.

⚙️ How it Works

1. Proxy Rotation: Each video attempt gets its own residential proxy session, behind a local byte counter that measures exactly what the attempt costs. A failed attempt is discarded and the retry gets a fresh IP.
2. Download Execution: The Actor uses youtube download mechanism more faster then normal.
3. Storage: Files are temporarily saved, then uploaded to the default Key-Value Store and made publicly accessible.
4. Error Handling: The Actor detects common blocks (like "Sign in to confirm you're not a bot") and network issues, triggering an immediate proxy switch and retry.

💰 What you pay for

Three charges, and nothing on top of them. Residential proxies, compute and storage are the Actor's cost to carry, not a separate line on your bill.

What	Price	Charged
Downloaded data	$17.00 per 1,000, one per MB — 1.7¢ per MB, or $17 per GB	Per megabyte of traffic the run pulls
Result	$5.00 per 1,000 — $0.005 each	Per row written to the dataset
Actor start	$0.005 per GB of memory — $0.01 on the default 2 GB	Once, when the run starts

Apify's volume tiers lower two of them: Bronze, Silver and Gold pay $16.00, $16.00 and $15.00 per 1,000 for downloaded data, and $0.0049, $0.0047 and $0.0045 per Actor start unit. Prices apply from 2 September 2026; the Actor's Store page always shows what is live today.

It is measured traffic, not file size

Every request a run makes passes through a byte counter on its way out, so the bill covers the whole job: looking the video up, fetching YouTube's player, the transfer itself, and any attempt that was blocked part way after already pulling megabytes down the wire. Expect a megabyte or two of lookup traffic on top of the file you receive, and more than that when an attempt had to be retried.

Job	Traffic	You pay
A 45 MB video, first attempt works	~47 MB	≈ $0.81
The same video after one attempt stalled at 12 MB	~59 MB	≈ $1.02
Metadata only (skipDownload: true)	~0.4 MB	≈ $0.03

A few more things worth knowing:

• An MP3 bills for the audio track that was fetched, not the smaller file that comes out of the re-encode.
• A URL that never delivers is still billed for the traffic its attempts used. Those bytes crossed the proxy whether or not a file came back.
• One URL is one video. A playlist link downloads the video it points at, not the whole list, so a link with &list=... in it is never billed as fifty files.

Every run prints its own figure, and the log above it shows each attempt and where it stopped, so a bill can always be traced back to what happened:

Data usage: 57.30 MB of proxy traffic, 58 billable unit(s), 58 charged

Set Max total charge in Run options for a hard ceiling — the Actor stops downloading when it is reached rather than running past it.

⚠️ On Apify's free plan, video is limited to 360p

If you are on a free Apify plan, video comes back at 360p — asking for 720p or higher will not change that. Audio is not affected, and any paid plan removes the limit.

Everything else works the same: metadata, MP3 audio, playlists, retries, the lot. Only the video height changes.

The reason is bandwidth. Every megabyte this Actor delivers is pulled through residential proxies it pays for by the gigabyte, and the same minute of footage costs roughly four times as much at 720p as at 360p. Limiting the free tier is what keeps it open rather than closed.

• Any paid Apify plan removes the limit and gives you the quality you asked for, up to 2160p.
• MP3 downloads are never limited — an audio file is a few megabytes whatever the source resolution, so there is nothing to save.
• You are told, on every row. A limited result carries a notice field saying so, and resolution always reports the height you actually received.

Spending limits

Every run has a maximum charge — either the Max total charge you set, or one the platform applies automatically. The Actor stops downloading as soon as that budget is spent instead of quietly continuing. URLs it did not get to come back as rows with status: "SKIPPED", and everything already finished is kept — each result is written the moment its video is done, not in one batch at the end.

If a run returns fewer results than you asked for, check the log for Charge limit reached: raising Max total charge lets the remaining URLs through.

⏱️ Give the run enough time

Downloads go through residential proxies, which are slower than a direct connection, and a blocked attempt costs a retry on a fresh IP. A run that is cut short by its Timeout setting delivers nothing — the file is not finished, so there is nothing to hand over — while the traffic it pulled getting there is still billed. Giving a run enough time is the cheapest setting on this page.

• Leave Timeout in Run options at a few thousand seconds; a couple of minutes is not enough for anything but the smallest clip.
• The Actor watches the clock: when time runs out it stops the download itself and writes a row with status: "FAILED" and a message saying the run timed out, rather than being killed with an empty dataset.
• The start of every log says how much time the run has, and warns when that is too little.
• A download that stops moving is dropped and retried on a fresh proxy session rather than waited out, so a dead session costs you a couple of minutes, not the whole run.

📦 How big a file can it hand over?

The file is written to disk and then uploaded in one piece, so it has to fit the memory the run was given: with the default 2 GB that is about 716 MB. A video above that is refused before the download starts, and the row says so — raise Memory in Run options (8 GB allows roughly 2.8 GB) and run it again. The limit for the current run is printed near the top of every log.

💡 Notes

• Connection policy: Each video uses one aria2c connection through its assigned proxy session. This is slower than parallel connections but avoids invalidating YouTube's IP-bound media URLs.
• Quality: The Actor takes the best rendition at or below the quality you chose, whatever container YouTube publishes it in, and merges the result into MP4. A video that only exists below your chosen quality comes back at its own height, reported in resolution.
• Residential Proxies: Every request goes through one, always. There is no unproxied path.
• Key-Value Store: Results are kept in the Actor's storage. You can access them via the provided downloadUrl.
• Failed lookups: If YouTube blocks every attempt for a URL, that row comes back with status: "FAILED" and an error message rather than an empty SUCCESS row. Those attempts still crossed the proxy, so their traffic is still billed.
• Row statuses: SUCCESS (file ready), FAILED (YouTube blocked every attempt), SKIPPED (the run's spending limit was reached before this URL).

---

Developed with focus on performance and reliability.