YouTube Video Downloader - MP4, MP3 & Shorts

Download YouTube videos and Shorts as MP4 or MP3 files and get a direct download link for each one. Paste one URL or a hundred, pick a quality from 360p to 1080p, and every file lands in Apify storage with a link that opens on any phone, laptop or server. Pay per minute of media, at the quality that was actually delivered, and nothing when a download on the standard path fails.

Typical cost: a 4-minute music video at 720p is $0.08. A 1-minute Short at 1080p is $0.03. A 60-minute podcast as MP3 is $0.60. Full table under Pricing.

What it does

• Downloads any public YouTube video, Short, or youtu.be link as an MP4 with audio, or extracts the MP3 audio track
• Lets you cap the resolution at 360p, 480p, 720p or 1080p and picks the best stream below that cap
• Processes a batch of URLs in one run, one row per URL, and keeps going when a single video fails
• Returns video metadata with every file: title, channel, duration, view count, delivered quality, file size
• Stores files up to about 200 MB in the run's key-value store and larger files, up to 1.6 GB at 1080p, in Cloudflare R2, both behind a direct download link
• Accepts your own YouTube cookies for age-restricted or members-only videos you can watch, and your own proxy if you already have one
• Runs on yt-dlp and ffmpeg, kept current, with a PO-token server and a client fallback ladder so a blocked first attempt does not end the run

Why this downloader

There are several YouTube downloaders on Apify Store. This one is built around predictable cost and honest failure reporting:

	This Actor	Common alternatives
Billing unit	Per started minute, at the quality actually delivered (a 1080p request on a 720p-only video bills 720p)	Per second at the requested quality, per MB stored, or per file plus platform usage
Proxy cost on the standard path	None. YouTube is reached through a free Cloudflare WARP tunnel	Often bundled into a higher per-unit price, or billed as platform usage
Failed downloads	Free on the standard path. Only residential proxy bandwidth is billed when you opt into the fallback	Varies; per-usage Actors bill compute whether or not the file arrives
Output on failure	A dataset row with status: "failed", an errorCode and a plain-language error	Empty dataset or a crashed run
Bring your own proxy or cookies	Yes, both, with no surcharge	Rare
Large files	Up to 1.6 GB at 1080p via R2, 900 MB at 720p, 300 MB MP3	Usually capped at the 256 MB key-value store record limit

Where other Actors are a better fit: if you need 4K, playlist expansion, or upload to your own S3 bucket, look at the Actors that advertise those features. This Actor does not do them.

Use cases

• Content archiving. Keep a local copy of videos, interviews or public statements before they are edited or removed.
• Podcast and audio workflows. Pull the MP3 of a talk or interview into an editing or transcription pipeline.
• Social media teams. Batch-download reference clips and Shorts for review, without a browser extension on every machine.
• Research and journalism. Preserve source material at a known quality with a timestamp of when it was fetched.
• Offline learning. Save lectures and tutorials for travel or low-bandwidth locations.
• AI and automation pipelines. Chain this Actor with a transcriber, a vision model or a Make/n8n scenario: start a run, receive a webhook, read the downloadUrl.

Respect the rights of the people who made the video. Download content you own, content you have permission to use, or content whose licence allows it.

How to use

1. Add URLs. Paste one or more YouTube links into the urls field. Watch pages, Shorts, youtu.be and embed links all work.
2. Choose quality and format. Leave 1080p MP4 for the best available video, or pick 720p for Shorts, 360p for long lectures, or MP3 for audio only.
3. Run. Each URL produces one dataset row with a downloadUrl. Click it in Console or read it from the API. A run summary is saved to the key-value store as OUTPUT.

Videos longer than about 20 minutes at 720p or above need more than the default 5-minute run timeout. Raise Run options > Timeout to 15 to 30 minutes for those, or choose a lower quality.

Input

Field	Type	Default	Description
urls	array	one demo video	List of { "url": "..." } objects. Video, Shorts, youtu.be and embed links. Playlists and channels are not expanded.
quality	string	"1080"	Maximum resolution: "360", "480", "720" or "1080". Billing uses the resolution that was delivered.
format	string	"default"	"default" for MP4 video, "mp3" for audio only.
residentialProxyMode	string	"disabled"	"fallback" enables a paid residential proxy that is only used after every free attempt is blocked. See Pricing.
proxyCountry	string	auto	Residential exit country, used only with the fallback.
customProxyUrl	string	none	Your own proxy as http://user:pass@host:port. Replaces the Apify residential fallback and is never surcharged. Stored as a secret.
youtubeCookies	string	none	Netscape cookies.txt contents from a logged-in YouTube session. Stored as a secret, deleted after the run.

Minimal input:

{
    "urls": [
        { "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw" }
    ]
}

Batch of Shorts at 720p:

{
    "urls": [
        { "url": "https://www.youtube.com/shorts/8wst-04IuWI" },
        { "url": "https://www.youtube.com/shorts/L4m91rVHD24" }
    ],
    "quality": "720"
}

Audio only:

{
    "urls": [
        { "url": "https://www.youtube.com/watch?v=Y1Z3Q3O7IRE" }
    ],
    "format": "mp3"
}

Blocked video, paid fallback enabled with a spend cap set in Run options:

{
    "urls": [
        { "url": "https://www.youtube.com/watch?v=VIDEO_ID" }
    ],
    "residentialProxyMode": "fallback",
    "proxyCountry": "US"
}

Output

One dataset row per URL. A real success row from a 4:49 video downloaded as MP3:

{
    "videoId": "Y1Z3Q3O7IRE",
    "title": "Tobu - Hope (Original Mix)",
    "originalUrl": "https://www.youtube.com/watch?v=Y1Z3Q3O7IRE",
    "duration": "4:49",
    "uploader": "Tobu",
    "viewCount": 13774849,
    "quality": "1080p",
    "deliveredQuality": "1080p",
    "format": "MP3",
    "fileSize": "6.5 MB",
    "fileSizeBytes": 6786045,
    "downloadUrl": "https://api.apify.com/v2/key-value-stores/Z6Fdr6LB8d70RfCPM/records/Y1Z3Q3O7IRE.mp3?signature=...",
    "kvStoreKey": "Y1Z3Q3O7IRE.mp3",
    "contentType": "audio/mpeg",
    "storageBackend": "apify_kv",
    "status": "success",
    "residentialProxyEnabled": false,
    "residentialProxyUsed": false,
    "residentialProxyAttempted": false,
    "downloadedAt": "2026-09-01T20:24:12.300Z"
}

A failed row keeps the run alive and tells you why:

{
    "videoId": "VIDEO_ID",
    "title": "Unknown",
    "originalUrl": "https://www.youtube.com/watch?v=VIDEO_ID",
    "duration": "0:00",
    "quality": "1080p",
    "format": "MP4",
    "fileSize": "0 B",
    "fileSizeBytes": 0,
    "downloadUrl": "",
    "status": "failed",
    "error": "YouTube rejected the media download request with HTTP 403. Failed during phase1. Last client tried: web_creator,mweb.",
    "errorCode": "HTTP_403",
    "failurePhase": "phase1",
    "residentialProxyEnabled": false,
    "residentialProxyUsed": false,
    "downloadedAt": "2026-09-01T20:24:41.561Z"
}

Field	Description
videoId, title, uploader, viewCount, duration	Metadata from YouTube. duration is M:SS or H:MM:SS.
quality	What you asked for.
deliveredQuality	What YouTube served and what you were billed at. Never above quality.
format	MP4 or MP3.
fileSize, fileSizeBytes	Size of the delivered file.
downloadUrl	Direct link to the file. Key-value store links stay valid as long as the run's storage is retained; R2 links are presigned for 7 days.
kvStoreKey, storageBackend	Where the file lives: apify_kv or cloudflare_r2.
status	success or failed.
error, errorCode, failurePhase	Present on failure. Codes include VIDEO_UNAVAILABLE, PRIVATE_VIDEO, AGE_RESTRICTED, LOGIN_REQUIRED, BOT_DETECTION, HTTP_403, LIVE_STREAM, PREMIERE_NOT_STARTED, COPYRIGHT_BLOCKED, FILE_TOO_LARGE, DOWNLOAD_TIMEOUT, CONFIG_TIMEOUT_TOO_LOW, QUALITY_UNAVAILABLE.
residentialProxyEnabled, residentialProxyAttempted, residentialProxyUsed	Whether the paid fallback was allowed, tried, and used for the delivered file.

The key-value store also holds every file under {videoId}.mp4 or {videoId}.mp3, plus OUTPUT, a JSON summary with totalUrls, successCount, failedCount, totalFileSize, processingTimeMs and a downloads list of title, status, link and size per video.

Pricing

Pay per event. No subscription, no platform usage bill on top, and the same price on every Apify plan.

Event	Price	When it is charged
minute-360p	$0.010 per minute	MP4 delivered at up to 360p
minute-480p	$0.015 per minute	MP4 delivered at up to 480p
minute-720p	$0.020 per minute	MP4 delivered at up to 720p
minute-1080p	$0.030 per minute	MP4 delivered at up to 1080p
minute-mp3	$0.010 per minute	MP3 audio
residential-megabyte	$0.05 per MB	Only with residentialProxyMode: "fallback", and only for bandwidth that actually went through the residential proxy. 5 MB minimum per video.

Rules that decide what you pay:

• Every started minute counts, one minute minimum. A 15-second Short bills as 1 minute. A 4:49 video bills as 5 minutes.
• You are billed at the delivered quality, never above the requested one. Requesting 1080p is safe on videos that only exist in 720p.
• A failed download on the standard path costs nothing. No file, no minute charge.
• The residential fallback bills bandwidth, not outcomes. If you enable it, bandwidth spent on residential attempts is charged even when the final attempt fails, because the proxy provider charges for those bytes. It is off by default so that this can never surprise you.
• The two platform-managed events, Actor start ($0.00005) and dataset row ($0.00001), are a rounding error and are listed for completeness.

What typical runs cost:

Run	Billed	Cost
1 Short (0:45) at 1080p	1 min	$0.03
1 music video (4:49) at 720p	5 min	$0.10
10 Shorts at 720p	10 min	$0.20
1 lecture (30:00) at 480p	30 min	$0.45
1 podcast episode (60:00) as MP3	60 min	$0.60
1 film (1:45:00) at 1080p, run timeout raised to 30 min	105 min	$3.15
1 blocked Short (25 MB) rescued by the residential fallback	1 min + 25 MB	$1.28
1 blocked 30-minute video (600 MB) rescued by the residential fallback	30 min + 600 MB	$30.90

Capping a run. Set Max total charge (USD) in Run options (or maxTotalChargeUsd on the API call). The platform stops charging at that limit and the Actor stops starting new downloads once it is reached. Set it whenever you enable the residential fallback on long videos.

Free-plan users get every feature at the same prices. There is no plan-based limit inside the Actor.

Integrations

API

Start a run and wait for the dataset in one call:

curl -X POST "https://api.apify.com/v2/acts/marielise.dev~youtube-video-downloader/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "urls": [ { "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw" } ], "quality": "720" }'

run-sync-get-dataset-items returns after at most 5 minutes. For long videos or big batches start the run with /runs, then poll or attach a webhook.

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('marielise.dev/youtube-video-downloader').call({
    urls: [
        { url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw' },
        { url: 'https://www.youtube.com/shorts/8wst-04IuWI' },
    ],
    quality: '720',
}, { timeout: 900 });

const { items } = await client.dataset(run.defaultDatasetId).listItems();

for (const item of items) {
    if (item.status === 'success') {
        console.log(item.title, item.downloadUrl, item.fileSize);
    } else {
        console.log('Failed:', item.originalUrl, item.errorCode, item.error);
    }
}

Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_TOKEN')

run = client.actor('marielise.dev/youtube-video-downloader').call(
    run_input={
        'urls': [{'url': 'https://www.youtube.com/watch?v=jNQXAC9IVRw'}],
        'format': 'mp3',
    },
    timeout_secs=900,
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    if item['status'] == 'success':
        print(item['title'], item['downloadUrl'])
    else:
        print('Failed:', item['originalUrl'], item['errorCode'])

AI agents and MCP

The Actor is callable from any MCP client through the Apify MCP server. Point the client at https://mcp.apify.com?tools=marielise.dev/youtube-video-downloader and ask the agent to download a YouTube video; it receives the dataset rows with the downloadUrl fields.

Make, Zapier, n8n and webhooks

Use the Apify app in Make, Zapier or n8n to run this Actor as a step and read downloadUrl from the dataset items. For anything longer than a few minutes, run the Actor asynchronously and let an ACTOR.RUN.SUCCEEDED webhook trigger the next step. Schedules work the same way: save the input as a task and put the task on a schedule.

Performance and limits

Scenario	Typical run time
1 Short, 720p	15 to 40 seconds
1 video under 5 minutes, 1080p	30 to 90 seconds
1 video, MP3	15 to 40 seconds
1 video of 20 minutes or more, 720p	2 to 6 minutes, raise the run timeout
5 videos of mixed length, 720p	3 to 8 minutes

• Videos are downloaded one after another so YouTube rate limits are not tripped. Run several Actor runs in parallel for large batches.
• Default memory is 2 GB. 4 GB helps on long 1080p files.
• File size ceilings by quality: 500 MB at 360p and 480p, 900 MB at 720p, 1.6 GB at 1080p, 300 MB for MP3. Anything larger is refused before download with FILE_TOO_LARGE. Pick a lower quality.
• Playlists, channels, live streams in progress, premieres that have not started and DRM content are not supported. Each of these returns a failed row, not a crashed run.
• 1440p and 2160p are not available at the moment.

Troubleshooting

HTTP_403, BOT_DETECTION or LOGIN_REQUIRED on the standard path. YouTube refused the anonymous request. Try 720p first for Shorts. If that fails, paste cookies from a logged-in throwaway account into youtubeCookies, or enable the residential fallback with a Max total charge set.

AGE_RESTRICTED or PRIVATE_VIDEO. The video needs a signed-in account that can watch it. Export that account's cookies into youtubeCookies.

FILE_TOO_LARGE. Choose a lower quality or MP3.

CONFIG_TIMEOUT_TOO_LOW or the run timed out. Raise Run options > Timeout. Long 1080p files need 15 to 30 minutes.

VIDEO_UNAVAILABLE. The video was removed, is region-locked, or the URL is wrong. Open it in a private browser window to confirm.

Download link stopped working. Key-value store files follow your plan's data retention (7 days on the free plan). R2 links expire after 7 days. Download promptly or copy the file to your own storage in the same workflow.

FAQ

Which quality will I get? The best stream up to your cap. YouTube serves many videos at a lower resolution than uploaded; you are billed for what arrives.

Can I download a whole playlist? Not directly. Paste the individual video URLs. A YouTube channel scraper Actor can produce the list for you.

Does it work with Shorts? Yes. Shorts are small even at 1080p, but 720p is the more reliable choice on the free path.

Is anything charged when a download fails? Not on the standard path. With the residential fallback enabled, the proxy bandwidth consumed by failed attempts is charged, as described under Pricing.

Can I use my own proxy? Yes. Set customProxyUrl. The Apify residential fallback is skipped and there is no surcharge.

Do free-plan users get the same features? Yes. Same features, same prices, no cap other than the Max total charge you choose per run.

Where are the files stored? In the run's key-value store, or in Cloudflare R2 for files above roughly 200 MB. Both give you a direct HTTPS link.

Is this legal? Downloading is a tool. Whether a specific download is allowed depends on the video's licence, your relationship to the owner and local law. Use it for content you have the right to keep.

Support

• Open an issue on the Actor's Issues tab for bugs and feature requests. Include the run ID so the logs can be checked.
• Leave a review if the Actor saved you time; it helps other people find it.

Issues are answered within one working day.