YouTube Video Downloader

The Actor resolves public YouTube videos and Shorts into normalized direct media formats, or saves one playable MP4, WebM, or MKV file with compatible video and audio combined.

Each input is handled independently. A run can return temporary direct media URLs for downstream processing without transferring the whole file, or saveMedia can retain a playable file in the run's key-value store. Optional transcript and subtitle enrichment can be attached to the same video record.

Accepted video references

urls is required and accepts request-list entries or bare strings in JSON input. Supported public references include:

• youtube.com/watch?v=... URLs
• music.youtube.com/watch?v=... URLs
• youtu.be/... URLs
• /shorts/, /embed/, and /live/ URLs
• bare 11-character video IDs

Recognized URLs are reduced to their stable video ID before media resolution. Extra playlist context on a watch URL does not change which video is processed.

Input fields

Field	Type	Default	Behaviour
urls	array	required	Public YouTube URLs or bare video IDs. Duplicate entries are removed.
region	string	US	Two-letter country code used to resolve and transfer the media, such as US, IN, or DE.
saveMedia	boolean	false	Saves one playable file instead of returning only direct media formats.
quality	enum	best	Maximum saved resolution: 144 through 4320, or best.
format	enum	default	Saved container: default, mp4, webm, or mkv. default produces MP4.
includeTranscript	boolean	false	Adds timed transcript segments and combined text when a transcript exists.
subtitleLanguage	string	empty	Adds one available VTT subtitle track matching the supplied language code.

{
  "urls": [
    { "url": "https://www.youtube.com/watch?v=arj7oStGLkU" },
    { "url": "https://youtu.be/Gef1KePPRoI" }
  ],
  "region": "US",
  "saveMedia": true,
  "quality": "1080",
  "format": "mp4",
  "includeTranscript": false
}

Direct-format records

With saveMedia: false, one dataset row contains video metadata and every usable combined, video-only, and audio-only format returned for that video.

Field	Contents
id, url	Video ID and canonical watch URL.
title, description	Public video text.
accessCountry	Country used to resolve the media.
durationSeconds, viewCount, isLive	Duration, reported views, and live-content state.
channel	Channel ID, title, and canonical channel URL.
thumbnails	Available thumbnail URLs and dimensions.
availableSubtitles	Language metadata for available caption tracks.
formats	Normalized media streams with container, codecs, dimensions, bitrate, size, duration, and directUrl.
directUrlsExpireAt	Approximate shared expiry time for the signed direct URLs, when reported.
transcript	Optional combined text and timed segments.
subtitle	Optional language metadata and VTT content.

{
  "id": "abc123def45",
  "url": "https://www.youtube.com/watch?v=abc123def45",
  "title": "Example video",
  "accessCountry": "US",
  "durationSeconds": 60,
  "viewCount": 1234,
  "isLive": false,
  "formats": [
    {
      "itag": 18,
      "streamType": "video+audio",
      "container": "mp4",
      "qualityLabel": "360p",
      "width": 640,
      "height": 360,
      "contentLengthBytes": 1048576,
      "sizeMb": 1,
      "directUrl": "https://..."
    }
  ]
}

Direct URLs are signed and temporary. directUrlsExpireAt records the approximate expiry when the source reports enough timing information; a retained file is the appropriate output when a stable run artifact is required.

Playable saved files

With saveMedia: true, the Actor selects the best compatible stream at or below quality. Higher YouTube resolutions commonly separate video and audio; the Actor downloads both and remuxes them into the selected container without re-encoding the media streams.

A successful savedFile contains:

• key and public url
• contentType and container
• qualityLabel, width, and height
• bytes, sizeMb, and billedMb

{
  "savedFile": {
    "key": "abc123def45-1080p.mp4",
    "url": "https://api.apify.com/v2/key-value-stores/...",
    "contentType": "video/mp4",
    "container": "mp4",
    "qualityLabel": "1080p",
    "width": 1920,
    "height": 1080,
    "bytes": 52428800,
    "sizeMb": 50,
    "billedMb": 50
  }
}

After a playable file is saved, the verbose formats, thumbnails, availableSubtitles, and directUrlsExpireAt fields are removed from that row. The retained file, basic video metadata, and any requested transcript or subtitle remain.

Partial results and billing

An input that does not resolve to a public video is skipped, and processing continues with the remaining entries. If playable-file transfer or merging fails, the video row is still returned with its direct formats and without savedFile.

Billing follows successful output:

• one result event for each dataset row;
• one saved-file event per billed MB, rounded up to the next whole MB, only after the file is stored;
• one transcript-or-subtitle event when a transcript, a subtitle, or both are successfully attached.

Missing transcripts and unavailable subtitle languages do not prevent the video result. They are logged, omitted from the row, and not billed as enrichment.

Choosing the related YouTube Actor

• YouTube Music Downloader saves audio-only MP3, M4A, or WebM files.
• YouTube Video Scraper returns public metadata and optional enrichments without downloading media.
• YouTube Transcript Scraper is the narrower choice when only transcript text and subtitle files are required.
• YouTube Playlist Scraper expands playlist URLs into their video entries.

Only public media that may lawfully be downloaded should be processed.