YouTube Download API: download YouTube video and audio files by API

The YouTube Download API turns a list of YouTube links into real files: MP4 video from 144p to 4K with sound always included, or audio as M4A, MP3 or Opus. Every link gets one row with a stable file link, file size, SHA-256 checksum, duration and channel details. Files land in the run's storage, or straight in your own Amazon S3, Google Cloud Storage or Azure bucket. You pay per minute of media actually delivered. Private, removed, blocked or skipped videos cost nothing, and no cookies or login are needed for public videos. Built for archiving your own channel, feeding transcription and AI pipelines, research datasets and MCP agents.

⚡ What you get back

• A real file, stored for you. Each download lands in the run's key-value store with a direct link you can fetch from code, a browser or the next step of a workflow. Never a temporary player link that expires in a few hours.
• Or straight into your own bucket. Point the API at Amazon S3 (or any S3-compatible storage such as Cloudflare R2, Backblaze B2 or Wasabi), Google Cloud Storage or Azure Blob Storage, and files are uploaded there directly, with no copy left behind.
• Video with sound, every time. Video and audio streams are combined into one file before delivery, so there are no silent MP4s.
• Audio in the format you need. M4A and Opus are delivered without re-encoding; MP3 is converted for you. Standard quality is compact and clear for speech; high quality is the best stream YouTube offers.
• The smallest file at the quality you asked for. By default the most efficient codec is chosen (AV1 or VP9 when YouTube offers them), which is often half the size of H.264. Ask for H.264 when you need a file that plays on every device and editor.
• One row per link, always. A file row, a metadata row, or a free error row that says exactly why: VIDEO_PRIVATE, VIDEO_UNAVAILABLE, AGE_RESTRICTED, OVER_MAX_MINUTES and so on.
• Integrity fields. fileSizeBytes and sha256 on every file row, so you can verify and deduplicate downstream.
• Free metadata. metadataOnly returns title, channel, duration, the qualities on offer and estimated file sizes without downloading anything.

🎯 Use cases

• Archive your own channel. Keep an offline copy of every upload at the quality you choose, with checksums.
• Audio for transcription and AI pipelines. Pull compact audio for speech-to-text, summarization, search indexes and RAG. Pair it with the YouTube Transcripts API when captions already exist.
• Lectures, talks and webinars for offline study. Download long-form educational video at 360p or 480p to keep files small.
• Research and media monitoring. Collect the videos behind a news story, a campaign or a topic for analysis, with a metadata row per video.
• Accessibility. Produce audio-only versions, or files that can be re-captioned, slowed down or translated.
• Video datasets for machine learning. Batch downloads with predictable naming (<videoId>_<quality>.<ext>), size limits and checksums.
• Agents that need the media itself. Any MCP client can call this API as a tool and get a file link back.

You are responsible for having the rights to the content you download. Use this API for your own content, for content you have permission to use, and for uses the law allows where you live.

🔧 Input

Field	Type	What it does
videoUrls	array, required	YouTube links or 11-character video IDs. Watch links, youtu.be links, Shorts, embed and live-replay links all work. Up to 200 per run.
format	string	audio (default) or video.
quality	string	Maximum video quality: 144p, 240p, 360p, 480p, 720p (default), 1080p, 1440p, 2160p. If the video is not offered that high, the best available quality below it is delivered and billed at its own rate.
audioFormat	string	m4a (default), mp3 or opus.
audioQuality	string	standard (default, compact, clear for speech) or high (best available).
videoCodec	string	smallest (default, most efficient codec) or h264 (plays everywhere, up to 1080p).
metadataOnly	boolean	Return details, available qualities and estimated sizes only. Free.
maxMinutes	integer	Skip videos longer than this, at no charge, before anything is downloaded.
maxMegabytes	integer	Skip files estimated to be larger than this, at no charge.
maxAgeDays	integer	Reuse cached metadata up to this many days old (default 7, 0 to always check YouTube). Media files are always downloaded fresh.
storageProvider	string	Where files go: apify (default, the run's key-value store), s3, gcs or azure.
storageBucket	string	Bucket name, for s3 and gcs.
storagePrefix	string	Optional folder inside the bucket or container, for example youtube/2026/.
storageRegion	string	Bucket region for s3 (default us-east-1; auto for Cloudflare R2).
storageEndpoint	string	https endpoint for S3-compatible storage other than Amazon.
storageAccessKeyId	string, secret	Access key ID (s3), or HMAC access ID (gcs).
storageSecretAccessKey	string, secret	Secret access key (s3), or HMAC secret (gcs).
storageSasUrl	string, secret	Container URL with a write SAS token, for azure.
cookies	string, secret	Optional. Cookies from your own signed-in session, only for age-restricted or members-only videos you have access to.

Audio for transcription

{
  "videoUrls": ["https://www.youtube.com/watch?v=aqz-KE-bpKQ"],
  "format": "audio",
  "audioFormat": "m4a"
}

720p video that plays everywhere

{
  "videoUrls": ["https://youtu.be/aqz-KE-bpKQ"],
  "format": "video",
  "quality": "720p",
  "videoCodec": "h264"
}

Check a list before you spend

{
  "videoUrls": ["aqz-KE-bpKQ", "jNQXAC9IVRw"],
  "metadataOnly": true
}

A batch with guard rails

{
  "videoUrls": ["https://www.youtube.com/watch?v=aqz-KE-bpKQ", "https://www.youtube.com/shorts/jNQXAC9IVRw"],
  "format": "video",
  "quality": "1080p",
  "maxMinutes": 60,
  "maxMegabytes": 500
}

Straight into your own S3 bucket

{
  "videoUrls": ["https://www.youtube.com/watch?v=aqz-KE-bpKQ"],
  "format": "video",
  "quality": "720p",
  "storageProvider": "s3",
  "storageBucket": "my-video-archive",
  "storageRegion": "us-east-1",
  "storagePrefix": "youtube/",
  "storageAccessKeyId": "YOUR_ACCESS_KEY_ID",
  "storageSecretAccessKey": "YOUR_SECRET_ACCESS_KEY"
}

🗄️ Send files to your own storage

By default every file is kept in the run's key-value store and the row's fileUrl links to it. Set storageProvider and the API uploads each finished file directly to your storage instead. Nothing is kept in the key-value store, and the row tells you where the object is (fileUrl, storageUri).

Destination	storageProvider	What to supply
Amazon S3	s3	storageBucket, storageRegion, storageAccessKeyId, storageSecretAccessKey
Cloudflare R2	s3	the same, plus storageEndpoint (https://<account>.r2.cloudflarestorage.com) and storageRegion: "auto"
Backblaze B2, Wasabi, DigitalOcean Spaces, MinIO	s3	the same, plus the provider's S3 storageEndpoint and its region
Google Cloud Storage	gcs	storageBucket and an HMAC key pair from Cloud Storage settings, Interoperability tab, as storageAccessKeyId and storageSecretAccessKey
Azure Blob Storage	azure	storageSasUrl: the container URL with a SAS token that allows create and write

How it works:

• Checked before anything is downloaded. The run writes and removes a tiny test object first. If the bucket, region or key is wrong you get one free STORAGE_UNAVAILABLE row and the run stops, before any media is fetched or charged.
• Least privilege is enough. The key only needs permission to put objects (and, optionally, delete the test object) in that bucket or prefix. It never needs to list or read.
• Your credentials stay secret. They are stored as secret input fields, used only to sign the upload, and never written to the log or the dataset. For Azure, the SAS token is stripped from every address in the output.
• File names. <storagePrefix><videoId>_<quality>.<ext>, for example youtube/aqz-KE-bpKQ_720p.mp4. Running the same video again overwrites the same object.
• If an upload fails part-way through a run, that file is kept in the run's key-value store instead and the row's note says so, so a finished download is never lost. The upload attempt is still billed.
• Size limit. One file can be up to 5 GB when sent to your own storage.
• Access to the object follows your bucket's own permissions; fileUrl is the object's address, not a signed link.

Google Drive, Dropbox and OneDrive are not direct destinations. Use a workflow step (n8n, Make or Zapier) to copy each fileUrl there.

📤 Example output

A delivered file:

{
  "resultType": "file",
  "videoId": "aqz-KE-bpKQ",
  "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
  "input": "https://youtu.be/aqz-KE-bpKQ",
  "title": "Big Buck Bunny 60fps 4K - Official Blender Foundation Short Film",
  "channelName": "Blender",
  "channelId": "UCSMOQeBJ2RAnuFungnQOxLg",
  "channelUrl": "https://www.youtube.com/channel/UCSMOQeBJ2RAnuFungnQOxLg",
  "durationSeconds": 635,
  "uploadDate": "2014-11-10",
  "viewCount": 23402793,
  "format": "video",
  "quality": "720p",
  "requestedQuality": "720p",
  "container": "mp4",
  "videoCodec": "h264",
  "audioCodec": "aac",
  "width": 1280,
  "height": 720,
  "fps": 60,
  "audioBitrateKbps": 129,
  "fileKey": "aqz-KE-bpKQ_720p.mp4",
  "fileUrl": "https://api.apify.com/v2/key-value-stores/<storeId>/records/aqz-KE-bpKQ_720p.mp4",
  "fileSizeBytes": 161192091,
  "sha256": "<64 hex characters>",
  "chargedEvent": "video-minute-hd",
  "chargedMinutes": 11,
  "storage": "apify",
  "fetchedAt": "2026-09-30T18:04:11Z"
}

A video that could not be delivered (never charged):

{
  "resultType": "error",
  "videoId": "xxxxxxxxxxx",
  "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
  "input": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
  "error": "VIDEO_UNAVAILABLE",
  "errorMessage": "This video is unavailable",
  "fetchedAt": "2026-09-30T18:04:12Z"
}

resultType is file, metadata, skipped or error. Only file rows are charged.

💰 Pricing

Pay per event, with no monthly rental and no minimum. The current rate for each event is on the Pricing tab of the Store page, with lower rates on higher Apify plans.

Event	Charged when
audio-minute	Per minute of audio delivered
video-minute-sd	Per minute of video delivered at 480p or lower
video-minute-hd	Per minute of video delivered at 720p
video-minute-fhd	Per minute of video delivered at 1080p
video-minute-uhd	Per minute of video delivered at 1440p or 4K
external-storage-megabyte	Per megabyte of each upload attempted to your own S3, Google Cloud or Azure storage, whether or not your storage accepts it. Not charged for files kept in the run's key-value store by default

How billing works:

• Minutes are the video's duration rounded up to a whole minute, per file. A 9 minute 20 second video is 10 minutes.
• You are billed for the quality delivered, not the quality requested. Ask for 1080p, get the 720p that is the best on offer, pay the 720p rate.
• The charge happens only after the file is stored and its checksum is computed. Private, removed, age-restricted, blocked and skipped videos are free rows.
• metadataOnly rows are free.
• Apify's standard Actor start and dataset item events apply to every run at the platform's lowest rate; they are listed on the Pricing tab.
• No surcharge for difficult videos: the per-minute rate is the whole price of a file kept in the run's storage.
• Delivery to your own storage adds the external-storage-megabyte event, on the size of the file, rounded up to a whole megabyte. It is charged for every upload attempted, including one your storage rejects or drops, so check your bucket, key and quota before a large run. The free test write at the start of each run catches most misconfiguration before anything is billed.
• The run stops cleanly at your maximum cost per run, and every link not reached gets a free NOT_PROCESSED row.

Example: 20 lecture videos of 45 minutes each as audio is 900 audio-minute events.

🚀 How to get started

1. Open the Actor: View on Apify Store.
2. Paste one or more YouTube links into YouTube video links.
3. Choose Audio only or Video with sound, and a quality.
4. Click Start. When the run finishes, open the dataset: each file row has a fileUrl.
5. Download the files from those links, or read them from the run's key-value store by fileKey.

From code, with the Apify API client:

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("johnvc/youtube-download-api").call(run_input={
    "videoUrls": ["https://www.youtube.com/watch?v=aqz-KE-bpKQ"],
    "format": "audio",
})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    if row["resultType"] == "file":
        print(row["title"], row["fileUrl"], row["sha256"])
    else:
        print(row["input"], row.get("error"), row.get("errorMessage"))

Files stay available for as long as the run's storage is retained on your Apify plan. For long-term storage, copy them out or run the Actor from a saved task and move files in the next step of your workflow.

Tips for large files: run memory sets the disk a run has (disk is twice the memory), so raise the memory for 1080p and 4K downloads of long videos, and set the run timeout to match the length of your list.

🔌 Use this API from Claude (MCP)

Add the Apify MCP server to your client and this Actor becomes a tool your assistant can call:

https://mcp.apify.com/?tools=actors,docs,johnvc/youtube-download-api

Works with Claude Code (free trial), Claude Cowork (free trial), Cursor, VS Code, ChatGPT and any other MCP client. Then ask in plain language: "Download the audio of this talk as M4A and give me the file link" or "Which of these ten videos are longer than an hour? Check without downloading."

Setup walkthrough video:

Full details in the Apify MCP documentation.

💸 Pay per run with crypto (x402)

The YouTube Download API supports agentic payments via the x402 protocol. AI agents and MCP clients can pay for runs in USDC (on Base) with no Apify account or API token needed: point your agent at the Apify MCP server and it can discover, pay for, and run this Actor autonomously. Read the Apify x402 announcement for details.

🔌 Integrations

• Schedules. Save a task with your channel's newest links and run it on a schedule to keep an archive current.
• Webhooks. Add a webhook on run success to hand the file links to your own service the moment they are ready.
• n8n, Make and Zapier. Run the Actor from the Apify integrations for each tool, read the dataset, then pass each fileUrl to a storage, transcription or messaging step.
• Cloud storage. Set storageProvider to deliver straight to Amazon S3, Cloudflare R2, Google Cloud Storage or Azure Blob Storage. For Google Drive or Dropbox, copy each fileUrl in the next step of your workflow; sha256 lets you skip files you already have.
• A data chain. Find videos with a search or listing API, read captions with the transcripts API, and download the media here. See Related Tools below.

🔗 Related Tools

Building a video or audio pipeline? These tools from the same catalog chain directly into this one:

• YouTube Transcripts API: captions, subtitles and transcripts for the same video links, and a channel listing mode that produces the links to download.
• YouTube Shorts API: list a channel's Shorts with views, likes and dates, then download the ones that matter.
• Google Short Videos API: find the Shorts that Google surfaces for a keyword and pass the YouTube links here.
• Google News API: track a story, then collect the video coverage behind it.
• All Alpha OSINT Actors on Apify: the full portfolio.

Alternatives such as YouTube Video Downloader deliver video only and bill for the full length of a video up front. This API delivers both audio and video, and charges only after a file has been stored.

🤖 Ask an AI assistant about this API

Open a ready-to-send prompt about the YouTube Download API in the AI of your choice:

• 💬 ChatGPT
• 🧠 Claude
• 🔍 Perplexity
• 🅒 Copilot

❓ FAQ

How do I download a YouTube video with an API?

Send the video link in videoUrls with format set to video and a quality. The run stores the file and returns a row with fileUrl, which you fetch like any other file. The same call works from the Apify Console, the REST API, the Python or JavaScript client, and any MCP client.

How do I download only the audio from a YouTube video?

Set format to audio and pick audioFormat: m4a, mp3 or opus. M4A and Opus come straight from YouTube's own audio streams with no re-encoding. MP3 is converted once after download.

Which video qualities are supported?

144p, 240p, 360p, 480p, 720p, 1080p, 1440p and 2160p (4K). quality is a ceiling: if a video tops out below it, you get the best quality on offer and pay that quality's rate. Run with metadataOnly first to see availableQualities for each video.

Will the video file have sound?

Yes. Above 360p YouTube serves picture and sound as separate streams. This API always fetches both and combines them into one file, without re-encoding either stream.

What is the difference between the smallest and h264 codec options?

smallest picks the most efficient stream at your quality, usually AV1 or VP9, which gives a much smaller file and works in modern browsers, VLC, ffmpeg and most AI pipelines. h264 picks H.264, the format every phone, TV and video editor plays, and is available up to 1080p. Above 1080p YouTube does not offer H.264, so the most efficient codec is delivered and the row's note says so.

Am I charged for videos that fail?

No. A charge happens only after a file is stored. Private, removed, age-restricted, region-locked, blocked and skipped videos produce a free row with an error code and a plain explanation.

How do I avoid downloading a video that is hours long by accident?

Set maxMinutes or maxMegabytes. Both are checked before any media is downloaded, and a video over the limit becomes a free skipped row. You can also run metadataOnly first to see durationSeconds and estimatedSizeBytes for your whole list at no cost.

How long do the file links work?

For files in the run's storage: as long as that storage is retained, which depends on your Apify plan. For files sent to your own bucket: as long as you keep them. The link points at a record in the run's key-value store, not at a temporary player address, so it does not expire after a few hours. Copy files out if you need them longer.

Can I save YouTube downloads directly to Amazon S3?

Yes. Set storageProvider to s3 with your bucket, region and an access key that can put objects. Each file is uploaded straight to the bucket and the row carries its storageUri (s3://bucket/key). The same setting works for Cloudflare R2, Backblaze B2, Wasabi and other S3-compatible storage with storageEndpoint.

Can I save files to Google Cloud Storage or Azure?

Yes. For Google Cloud Storage set storageProvider to gcs and supply an HMAC key pair from the Interoperability tab of Cloud Storage settings. For Azure Blob Storage set it to azure and supply a container SAS URL with write permission.

Can I save files to Google Drive?

Not directly. Deliver to the run's storage (the default) and copy each fileUrl to Drive with a workflow step in n8n, Make or Zapier.

Is it safe to put my storage keys in the input?

The key fields are secret inputs: Apify encrypts them, they are used only to sign the upload request, and they never appear in the log or the dataset. Use a key limited to writing objects in one bucket or prefix, and rotate it like any other credential.

Can I download Shorts?

Yes. A Shorts link is a normal video link to this API. To list a channel's Shorts first, use the YouTube Shorts API.

Can I download a whole playlist or channel?

Pass the individual video links. To build the list for a channel, use the channel listing mode of the YouTube Transcripts API and feed its links into videoUrls.

Can I download age-restricted or members-only videos?

Only with access. Paste cookies from your own signed-in session into cookies (stored as a secret). Without cookies those videos return a free AGE_RESTRICTED or MEMBERS_ONLY row.

Can I download a live stream?

Not while it is live: the row is LIVE_NOT_SUPPORTED. Once the stream has ended and YouTube has published the replay, the same link downloads normally.

How do I get a transcript instead of the audio?

If the video has captions, the YouTube Transcripts API returns them directly and is the fastest route. If it has none, download the audio here and run it through your own speech-to-text.

Can I use the YouTube Download API through an MCP server?

Yes. Add https://mcp.apify.com/?tools=actors,docs,johnvc/youtube-download-api to your MCP client and the Actor becomes a callable tool. See the MCP section above.

Is there a free tier?

Free Apify plans can try the API within a monthly allowance. Metadata-only runs are free on every plan.

Is it legal to download YouTube videos?

It depends on the content and on what you do with it. Downloading your own uploads, content under an open licence, or content you have permission to use is fine. YouTube's terms restrict downloading other content without permission, and copyright law applies to what you do with any file. You are responsible for the rights to what you download; this API is a tool for lawful uses such as archiving your own channel, research, accessibility and analysis.

What happens if YouTube blocks a request?

The API retries on a different path automatically. If a video still cannot be fetched, you get a free YOUTUBE_BLOCKED row and can retry later; nothing is charged for it.

🌐 About Alpha OSINT

This Actor is part of Alpha OSINT, toolset of financial and operations data sources and APIs. See the YouTube Download API source page for related tools and use cases. For support or requests for this actor, please start a ticket directly on our support page.

Last Updated: 2026.09.30