{ "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 } } } } } } } } } }