{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Video Downloader — MP4, MP3, Shorts, Playlists",
    "description": "Download YouTube videos, Shorts, playlists and channels as MP4, MKV, WebM, AVI, MOV or audio (MP3, M4A, WAV, FLAC) in 360p to 4K. Get subtitles, transcript and metadata, plus direct download links in Apify, S3 or Azure storage. Repeat downloads are skipped.",
    "version": "1.0",
    "x-build-id": "xUlYgLg9xK0QQvPYy"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/confidential_gnat~youtube-video-downloader/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-confidential_gnat-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/confidential_gnat~youtube-video-downloader/runs": {
      "post": {
        "operationId": "runs-sync-confidential_gnat-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/confidential_gnat~youtube-video-downloader/run-sync": {
      "post": {
        "operationId": "run-sync-confidential_gnat-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": {
          "startUrls": {
            "title": "YouTube URLs",
            "type": "array",
            "description": "Video links (youtube.com/watch, youtu.be, Shorts, embed), playlists (youtube.com/playlist?list=...) or channels (youtube.com/@name). Playlists and channels download their newest videos, up to the limit below.",
            "default": [
              {
                "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
              }
            ],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "videoIds": {
            "title": "Video IDs",
            "type": "array",
            "description": "Optional. YouTube video IDs (the 11 characters after v=), for example jNQXAC9IVRw. Added to the URLs above.",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Max videos per playlist or channel",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "How many of the newest videos to download from each playlist or channel URL. Single video links are always downloaded.",
            "default": 3
          },
          "format": {
            "title": "Format",
            "enum": [
              "mp4",
              "mkv",
              "webm",
              "avi",
              "mov",
              "mp3",
              "m4a",
              "opus",
              "wav",
              "flac"
            ],
            "type": "string",
            "description": "File type. MP4, MKV and WebM only combine the video and audio streams, which is fast. AVI and MOV convert the video, which takes longer. MP3, M4A, Opus, WAV and FLAC download audio only.",
            "default": "mp4"
          },
          "quality": {
            "title": "Video quality",
            "enum": [
              "360",
              "480",
              "720",
              "1080",
              "1440",
              "2160"
            ],
            "type": "string",
            "description": "The highest video height to download, in pixels. If the video is smaller you get its best quality. Ignored for audio formats.",
            "default": "720"
          },
          "audioLanguage": {
            "title": "Audio language",
            "type": "string",
            "description": "Optional. Two-letter language code (for example en, es, fr) to pick that audio track when a video has several. Falls back to the default track."
          },
          "subtitleLanguages": {
            "title": "Subtitle languages",
            "type": "array",
            "description": "Optional. Language codes of subtitles to download as .srt files, for example [\"en\", \"es\"]. Leave empty for no subtitles.",
            "items": {
              "type": "string"
            }
          },
          "includeAutoCaptions": {
            "title": "Include automatic captions",
            "type": "boolean",
            "description": "Also download YouTube's auto-generated captions when a video has no uploaded subtitles in the languages above.",
            "default": false
          },
          "includeTranscript": {
            "title": "Include transcript text",
            "type": "boolean",
            "description": "Adds the subtitles of the first language as plain text in the output (needs a subtitle language above). Uses YouTube's own captions, not speech-to-text.",
            "default": false
          },
          "includeAllFormats": {
            "title": "Include all available formats",
            "type": "boolean",
            "description": "Adds the full list of streams YouTube offers for each video (resolution, codecs, bitrate, size, language) to the output. The download itself is not affected.",
            "default": false
          },
          "filenameParts": {
            "title": "File name parts",
            "type": "array",
            "description": "Which details go into the file name, in order. The video ID is always added at the end. Allowed: title, uploader, uploadDate, quality.",
            "default": [
              "title"
            ],
            "items": {
              "type": "string"
            }
          },
          "storageType": {
            "title": "Storage",
            "enum": [
              "apify",
              "s3",
              "azure"
            ],
            "type": "string",
            "description": "Where the files are saved. Apify storage needs no setup and gives a download link (files of a normal run are kept for the retention time of your Apify plan; files in a cache project are kept until you delete them or the retention days pass).",
            "default": "apify"
          },
          "s3Bucket": {
            "title": "S3 bucket",
            "type": "string",
            "description": "Needed for S3-compatible storage."
          },
          "s3AccessKeyId": {
            "title": "S3 access key ID",
            "type": "string",
            "description": "Needed for S3-compatible storage."
          },
          "s3SecretAccessKey": {
            "title": "S3 secret access key",
            "type": "string",
            "description": "Needed for S3-compatible storage."
          },
          "s3Region": {
            "title": "S3 region",
            "type": "string",
            "description": "Optional. For example us-east-1 (the default)."
          },
          "s3Endpoint": {
            "title": "S3 endpoint",
            "type": "string",
            "description": "Optional. Only for services other than AWS, for example https://nyc3.digitaloceanspaces.com, https://storage.googleapis.com or your Cloudflare R2 address."
          },
          "s3PathPrefix": {
            "title": "S3 folder",
            "type": "string",
            "description": "Optional. Folder inside the bucket, ending with a slash, for example youtube/."
          },
          "s3PublicBaseUrl": {
            "title": "S3 public base URL",
            "type": "string",
            "description": "Optional. If the bucket is public (or behind a CDN), links are built from this address. Otherwise links are private signed links valid for 7 days."
          },
          "azureConnectionString": {
            "title": "Azure connection string",
            "type": "string",
            "description": "Needed for Azure Blob Storage."
          },
          "azureContainer": {
            "title": "Azure container",
            "type": "string",
            "description": "Needed for Azure Blob Storage. Created if it does not exist."
          },
          "cacheProjectName": {
            "title": "Cache project name",
            "type": "string",
            "description": "Optional. Downloads are kept in a named storage under this name. When the same video is requested again with the same format, quality and options, the saved file is returned at once and you are not charged again. Use the same name on each run. Leave empty to download everything fresh."
          },
          "retentionDays": {
            "title": "Cache retention (days)",
            "minimum": 0,
            "maximum": 1825,
            "type": "integer",
            "description": "With a cache project: files older than this many days are deleted at the start of the next run. 0 keeps them until you delete them.",
            "default": 0
          },
          "maxFileSizeMb": {
            "title": "Max file size (MB)",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Videos whose file would be larger are skipped without charge.",
            "default": 500
          },
          "maxDurationMinutes": {
            "title": "Max video length (minutes)",
            "minimum": 1,
            "maximum": 600,
            "type": "integer",
            "description": "Longer videos and live streams are skipped without charge.",
            "default": 120
          },
          "maxConcurrency": {
            "title": "Parallel downloads",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many videos are downloaded at the same time. Raise it with more memory.",
            "default": 3
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "YouTube blocks most server addresses, so residential Apify proxy is the default. Proxy traffic is billed by Apify per GB.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "customProxyUrl": {
            "title": "Custom proxy URL",
            "type": "string",
            "description": "Optional. Use your own proxy instead of Apify proxy, for example http://user:password@host:port."
          },
          "youtubeCookies": {
            "title": "YouTube cookies",
            "type": "string",
            "description": "Optional. Cookies in Netscape cookies.txt format, for videos that need a signed-in account (for example age-restricted videos). Use a throwaway account: YouTube may restrict accounts used for downloading."
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}