# YouTube Video Downloader - Videos, Audio and Metadata (`khadinakbar/youtube-video-downloader`) Actor Download permitted YouTube videos or audio to Apify key-value storage. Accepts one or more video URLs, enforces duration and file-size caps, returns metadata plus storage keys. Perfect for SEO and AI agents. MCP optimized. - **URL**: https://apify.com/khadinakbar/youtube-video-downloader.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Videos, Social media, MCP servers - **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $15.00 / 1,000 media file saveds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Downloader - Videos, Audio and Metadata Download permitted YouTube videos or audio files into Apify key-value storage and get a clean dataset row for every URL. This actor is built for workflows where you own the video, have permission from the rights holder, or have another lawful basis to download it. It accepts one or more YouTube video URLs, probes each video with `yt-dlp`, enforces duration and file-size caps, saves the media file to the default key-value store, and returns metadata plus storage keys in the dataset. It is perfect for SEO and AI agents, and MCP optimized. ### What you get - Video downloads up to a selected maximum quality: 360p, 480p, 720p, 1080p or best available. - Audio-only downloads as M4A, MP3 or best source audio. - Metadata-only mode for cheap URL checks without media download. - Apify key-value store files with predictable keys. - Structured dataset rows with title, channel, duration, views, thumbnail, file key, metadata key and errors. - Residential proxy support and optional cookies.txt for videos that require your own logged-in session. ### Input | Field | Type | Default | Notes | |---|---|---:|---| | `videoUrls` | URL list | required | YouTube video URLs only | | `authorizationConfirmed` | boolean | false | Must be true before downloads run | | `downloadMode` | enum | video | `video`, `audio`, or `metadataOnly` | | `videoQuality` | enum | 720p | Max video quality | | `preferredContainer` | enum | mp4 | `mp4`, `webm`, or `any` | | `audioFormat` | enum | m4a | `m4a`, `mp3`, or `best` | | `maxDurationMinutes` | integer | 60 | Skip longer videos | | `maxFileSizeMb` | integer | 250 | Delete and skip files above this cap | | `includeMetadataJson` | boolean | true | Save raw yt-dlp metadata JSON | | `cookiesTxt` | string | empty | Optional Netscape cookies.txt content | ### Example input ```json { "videoUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "authorizationConfirmed": true, "downloadMode": "video", "videoQuality": "720p", "preferredContainer": "mp4", "maxDurationMinutes": 10, "maxFileSizeMb": 100 } ```` ### Output One dataset row is returned per URL: ```json { "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "canonicalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "videoId": "dQw4w9WgXcQ", "title": "Example video", "channel": "Example Channel", "durationSeconds": 213, "viewCount": 1000000, "downloadMode": "video", "fileKey": "video-dqw4w9wgxcq-example-video.mp4", "fileName": "dQw4w9WgXcQ.mp4", "fileExtension": "mp4", "fileSizeBytes": 12345678, "contentType": "video/mp4", "metadataKey": "metadata-dqw4w9wgxcq.json", "status": "success", "error": null, "scrapedAt": "2026-06-11T12:00:00Z" } ``` Downloaded files are stored in the default key-value store. Use the `fileKey` and `metadataKey` fields to fetch the exact records. ### Pricing Pay per event, no rental: - `$0.00005` actor start. - `$0.015` per video or audio file saved to key-value storage. - `$0.003` per metadata-only URL successfully probed. Failed and skipped downloads are not charged for media events. ### MCP and AI agent use Tool description draft: Download authorized YouTube videos or audio to Apify storage. Use when the user owns the video or has permission and needs a reusable media file plus metadata. Do not use for transcripts or search. Returns one row per URL with title, channel, duration, fileKey, metadataKey, status and error. Charged $0.015 per media file. The output stays flat and predictable so agents can reason over it without reading raw yt-dlp metadata unless they need to fetch the metadata JSON file. ### Legal Only download videos you own, videos you have permission to download, or videos you are otherwise legally allowed to copy. You are responsible for complying with YouTube's Terms of Service, copyright law, privacy law and any other rules that apply to your use case. This actor is not affiliated with, endorsed by, or sponsored by YouTube or Google. # Actor input Schema ## `videoUrls` (type: `array`): Full YouTube video URLs to process, for example https://www.youtube.com/watch?v=dQw4w9WgXcQ. Accepts youtube.com/watch, youtu.be, Shorts and embed URLs. Defaults to one sample URL. NOT a search query, channel URL or playlist crawler. ## `authorizationConfirmed` (type: `boolean`): Confirms that you own the videos, have permission from the rights holder, or are otherwise legally allowed to download them. The actor stops if this is false. Defaults to false so accidental runs do not download media. NOT a way to bypass YouTube rights or access controls. ## `downloadMode` (type: `string`): What to save for each URL. 'video' saves a playable video file, 'audio' saves audio only, and 'metadataOnly' probes the URL without downloading media. Defaults to video. NOT a transcript extractor. ## `videoQuality` (type: `string`): Maximum video height when downloadMode is video. Choose 360p, 480p, 720p, 1080p or best. Defaults to 720p to keep files manageable. NOT an upscaler, it cannot create higher quality than YouTube provides. ## `preferredContainer` (type: `string`): Preferred container for video downloads. mp4 is the most compatible option, webm keeps YouTube's native formats, and any lets yt-dlp choose. Defaults to mp4. NOT guaranteed if the source does not provide compatible streams. ## `audioFormat` (type: `string`): Audio output when downloadMode is audio. m4a is fast and compatible, mp3 transcodes with ffmpeg, and best keeps the best source audio. Defaults to m4a. Ignored for video and metadata-only runs. ## `maxDurationMinutes` (type: `integer`): Skip videos longer than this many minutes before downloading. Defaults to 60 minutes and accepts 1 to 720. Use this to avoid long podcasts or livestreams. NOT a clip length, the actor downloads the full video if it passes this cap. ## `maxFileSizeMb` (type: `integer`): Delete and mark a download as failed if the final media file is larger than this limit. Defaults to 250 MB and accepts 1 to 1000. Lower this for agent workflows where small files matter. NOT a compression target. ## `includeMetadataJson` (type: `boolean`): Save yt-dlp metadata JSON for each successful URL to the key-value store. Useful for audits and downstream processing. Defaults to true. NOT required for the dataset row, which always includes concise metadata. ## `cookiesTxt` (type: `string`): Optional Netscape cookies.txt content for videos that require your logged-in YouTube session. Paste only cookies you are allowed to use. Leave empty for public videos. NOT a username or password field. ## `proxyConfiguration` (type: `object`): Apify proxy used for YouTube requests. Residential proxies are enabled by default because datacenter IPs are often rate limited. Change only if you know your target videos work from another network. ## Actor input object example ```json { "videoUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "authorizationConfirmed": false, "downloadMode": "video", "videoQuality": "720p", "preferredContainer": "mp4", "audioFormat": "m4a", "maxDurationMinutes": 60, "maxFileSizeMb": 250, "includeMetadataJson": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `downloadRows` (type: `string`): Structured dataset rows with metadata, file keys, status and errors. ## `downloadedFiles` (type: `string`): Media and metadata files 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 = { "videoUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "downloadMode": "video", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/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 = { "videoUrls": [{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }], "downloadMode": "video", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/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 '{ "videoUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "downloadMode": "video", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call khadinakbar/youtube-video-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/youtube-video-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Video Downloader - Videos, Audio and Metadata", "description": "Download permitted YouTube videos or audio to Apify key-value storage. Accepts one or more video URLs, enforces duration and file-size caps, returns metadata plus storage keys. Perfect for SEO and AI agents. MCP optimized.", "version": "0.4", "x-build-id": "vavCaNsEsBNQynWCe" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~youtube-video-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~youtube-video-downloader/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~youtube-video-downloader/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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", "required": [ "videoUrls", "authorizationConfirmed" ], "properties": { "videoUrls": { "title": "YouTube video URLs", "type": "array", "description": "Full YouTube video URLs to process, for example https://www.youtube.com/watch?v=dQw4w9WgXcQ. Accepts youtube.com/watch, youtu.be, Shorts and embed URLs. Defaults to one sample URL. NOT a search query, channel URL or playlist crawler.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL", "description": "YouTube video URL" } } } }, "authorizationConfirmed": { "title": "I have permission to download these videos", "type": "boolean", "description": "Confirms that you own the videos, have permission from the rights holder, or are otherwise legally allowed to download them. The actor stops if this is false. Defaults to false so accidental runs do not download media. NOT a way to bypass YouTube rights or access controls.", "default": false }, "downloadMode": { "title": "Download mode", "enum": [ "video", "audio", "metadataOnly" ], "type": "string", "description": "What to save for each URL. 'video' saves a playable video file, 'audio' saves audio only, and 'metadataOnly' probes the URL without downloading media. Defaults to video. NOT a transcript extractor.", "default": "video" }, "videoQuality": { "title": "Maximum video quality", "enum": [ "360p", "480p", "720p", "1080p", "best" ], "type": "string", "description": "Maximum video height when downloadMode is video. Choose 360p, 480p, 720p, 1080p or best. Defaults to 720p to keep files manageable. NOT an upscaler, it cannot create higher quality than YouTube provides.", "default": "720p" }, "preferredContainer": { "title": "Preferred video container", "enum": [ "mp4", "webm", "any" ], "type": "string", "description": "Preferred container for video downloads. mp4 is the most compatible option, webm keeps YouTube's native formats, and any lets yt-dlp choose. Defaults to mp4. NOT guaranteed if the source does not provide compatible streams.", "default": "mp4" }, "audioFormat": { "title": "Audio format", "enum": [ "m4a", "mp3", "best" ], "type": "string", "description": "Audio output when downloadMode is audio. m4a is fast and compatible, mp3 transcodes with ffmpeg, and best keeps the best source audio. Defaults to m4a. Ignored for video and metadata-only runs.", "default": "m4a" }, "maxDurationMinutes": { "title": "Max duration in minutes", "minimum": 1, "maximum": 720, "type": "integer", "description": "Skip videos longer than this many minutes before downloading. Defaults to 60 minutes and accepts 1 to 720. Use this to avoid long podcasts or livestreams. NOT a clip length, the actor downloads the full video if it passes this cap.", "default": 60 }, "maxFileSizeMb": { "title": "Max file size in MB", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Delete and mark a download as failed if the final media file is larger than this limit. Defaults to 250 MB and accepts 1 to 1000. Lower this for agent workflows where small files matter. NOT a compression target.", "default": 250 }, "includeMetadataJson": { "title": "Save raw metadata JSON", "type": "boolean", "description": "Save yt-dlp metadata JSON for each successful URL to the key-value store. Useful for audits and downstream processing. Defaults to true. NOT required for the dataset row, which always includes concise metadata.", "default": true }, "cookiesTxt": { "title": "YouTube cookies.txt (optional)", "type": "string", "description": "Optional Netscape cookies.txt content for videos that require your logged-in YouTube session. Paste only cookies you are allowed to use. Leave empty for public videos. NOT a username or password field." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy used for YouTube requests. Residential proxies are enabled by default because datacenter IPs are often rate limited. Change only if you know your target videos work from another network.", "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 } } } } } } } } } } ```