# YouTube Video & Audio Downloader (`dami_studio/youtube-video-downloader`) Actor Download YouTube videos or extract audio (MP3) at your chosen quality, with metadata and optional subtitles. Powered by yt-dlp with residential-proxy support and bot-detection workarounds. For archiving, repurposing, datasets, and pipelines. - **URL**: https://apify.com/dami\_studio/youtube-video-downloader.md - **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community) - **Categories:** Videos, For creators, Developer tools - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $20.00 / 1,000 video downloadeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## YouTube Video & Audio Downloader Download YouTube videos, or pull just the audio as MP3, at a quality you choose. Each result comes back with metadata (title, channel, duration, views, resolution) and, if you ask for them, subtitles. It's meant for archiving, repurposing clips, and building video or audio datasets without hand-saving files one at a time. ### How it works The actor runs yt-dlp behind an Apify residential proxy, fetches the best stream at or below your quality cap, and stores each file in the run's key-value store with a public URL. YouTube bot-blocks most datacenter IPs, so residential proxy is the default and is the part that actually keeps downloads from failing. ### Input Pass either an array of `urls` or a single `videoUrl`. Everything else has a sensible default, so a list of links is enough to get going. | Field | Required | Notes | | --- | --- | --- | | `urls` | one of urls/videoUrl | Array of YouTube watch or Shorts links. | | `videoUrl` | one of urls/videoUrl | A single link, if you'd rather not use an array. | | `quality` | no | Caps video height: `2160`, `1440`, `1080` (default), `720`, `480`, `360`, or `audio` for audio-only. Picks the best stream at or below the cap. | | `audioOnly` | no | Extract MP3 instead of video. Same effect as setting quality to `audio`. Default `false`. | | `subtitles` | no | Also fetch subtitles/auto-captions as SRT. Default `false`. | | `subLangs` | no | Comma-separated language codes, e.g. `en,es`. Only used when `subtitles` is on. Default `en`. | | `includeMetadata` | no | Return title, channel, duration, views, upload date, resolution. Default `true`. | | `proxyConfiguration` | no | Apify proxy. Defaults to RESIDENTIAL, which is what you want here. | ### Output One dataset record per URL. A successful record has `ok: true` plus `title`, `channel`, `durationSeconds`, `viewCount`, `uploadDate`, `resolution`, `format`, and `fileSizeBytes`. The download itself lives in the key-value store. `mediaKey` is the store key and `mediaUrl` is a direct link to the file. When subtitles are requested, `subtitles` holds an array of `{ key, url }` per language. If a single URL fails, you get `ok: false` with an `error` message and the run keeps going on the rest. ### Example ```json { "urls": [ "https://www.youtube.com/watch?v=aqz-KE-bpKQ" ], "quality": "1080", "subtitles": true, "subLangs": "en" } ```` ### Pricing $0.05 per successful download, pay per result, no subscription. Failed URLs aren't charged. ### Notes Residential proxy is on by default for a reason. If you switch to datacenter IPs, expect YouTube to bot-block a lot of requests. Some videos (age-restricted, region-locked, or private) won't download regardless of proxy. Subtitle availability depends on what the channel uploaded; auto-captions exist for most videos but accuracy varies. If any step uses an AI model, that runs on your own OpenAI key. # Actor input Schema ## `urls` (type: `array`): One or more YouTube video URLs (or Shorts URLs). ## `videoUrl` (type: `string`): A single YouTube URL (alternative to the array). ## `quality` (type: `string`): Cap the video height (best available ≤ this). Or 'audio' for audio-only. 1080p is the max (4K/1440p downloads are very large and slow). ## `audioOnly` (type: `boolean`): Extract audio as MP3 instead of video. ## `subtitles` (type: `boolean`): Also fetch subtitles/auto-captions as SRT. ## `subLangs` (type: `string`): Comma-separated subtitle language codes (e.g. en,es). Used when subtitles are on. ## `includeMetadata` (type: `boolean`): Return title, channel, duration, views, etc. ## `proxyConfiguration` (type: `object`): Apify proxy. RESIDENTIAL strongly recommended (datacenter IPs are often bot-blocked by YouTube). ## Actor input object example ```json { "urls": [ "https://www.youtube.com/watch?v=aqz-KE-bpKQ" ], "quality": "720", "audioOnly": false, "subtitles": false, "subLangs": "en", "includeMetadata": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): Result rows / metadata are stored in the default dataset (one row per item). ## `files` (type: `string`): Generated media/files (video, audio, images, captions) are stored in the default key-value store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "urls": [ "https://www.youtube.com/watch?v=aqz-KE-bpKQ" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("dami_studio/youtube-video-downloader").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "urls": ["https://www.youtube.com/watch?v=aqz-KE-bpKQ"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("dami_studio/youtube-video-downloader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "urls": [ "https://www.youtube.com/watch?v=aqz-KE-bpKQ" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call dami_studio/youtube-video-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dami_studio/youtube-video-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Video & Audio Downloader", "description": "Download YouTube videos or extract audio (MP3) at your chosen quality, with metadata and optional subtitles. Powered by yt-dlp with residential-proxy support and bot-detection workarounds. For archiving, repurposing, datasets, and pipelines.", "version": "0.1", "x-build-id": "XTJdcfTTosJeezcWk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dami_studio~youtube-video-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dami_studio-youtube-video-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dami_studio~youtube-video-downloader/runs": { "post": { "operationId": "runs-sync-dami_studio-youtube-video-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dami_studio~youtube-video-downloader/run-sync": { "post": { "operationId": "run-sync-dami_studio-youtube-video-downloader", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "urls": { "title": "YouTube URLs", "type": "array", "description": "One or more YouTube video URLs (or Shorts URLs).", "items": { "type": "string" } }, "videoUrl": { "title": "Single URL", "type": "string", "description": "A single YouTube URL (alternative to the array)." }, "quality": { "title": "Max quality", "enum": [ "1080", "720", "480", "360", "audio" ], "type": "string", "description": "Cap the video height (best available ≤ this). Or 'audio' for audio-only. 1080p is the max (4K/1440p downloads are very large and slow).", "default": "720" }, "audioOnly": { "title": "Audio only (MP3)", "type": "boolean", "description": "Extract audio as MP3 instead of video.", "default": false }, "subtitles": { "title": "Download subtitles", "type": "boolean", "description": "Also fetch subtitles/auto-captions as SRT.", "default": false }, "subLangs": { "title": "Subtitle languages", "type": "string", "description": "Comma-separated subtitle language codes (e.g. en,es). Used when subtitles are on.", "default": "en" }, "includeMetadata": { "title": "Include metadata", "type": "boolean", "description": "Return title, channel, duration, views, etc.", "default": true }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify proxy. RESIDENTIAL strongly recommended (datacenter IPs are often bot-blocked by YouTube).", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```