Video Downloader — Direct Media URL, MP4 Download & Audio Extraction

Give it a page URL (YouTube and any other site supported by yt-dlp) and get back either the direct media URLs, a ready MP4 file, an audio-only track, or just the time windows you need. Downloads run over many parallel range requests, so a full video arrives in a fraction of the usual time.

Use it for: content archiving, repurposing long videos into clips, building transcription and analysis pipelines, media research, dataset collection.

Only download content you own or have the right to use, and follow each site's terms of service.

Quick start

{
  "op": "full",
  "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX"
}

Feature-detect the build (free, a few seconds, needs no source):

{ "op": "capabilities" }

Operations

op	What it does
resolve	report the selected video/audio formats and their direct URLs — no download
full	parallel-range download of video + audio, stream-copy mux into a faststart MP4
full_multi	download one byte-range part, for fan-out across several runs
audio	audio track only, at maximum speed
window	download, then cut one or many time windows with stream copy
capabilities	report ops, features and vCPUs; needs no source

Options

Option	Default	Notes
min_height	720	lowest acceptable video height
max_height	1080	highest acceptable video height
prefer_codec	h264	h264 avoids any transcode later; any allows VP9/AV1
lanes	8	parallel chunk requests (max 64)
chunk_mb	4	size of each range request
segments	—	[{ start_sec, end_sec, name }] for op: "window"
part	—	{ start, end } byte offsets for op: "full_multi"
audio	false	also fetch the full audio track in the same run
cookies / cookies_url	—	Netscape cookie file content or URL, for age/region gated pages
proxy_ladder	["direct", "DATACENTER", "RESIDENTIAL", "RESIDENTIAL"]	network steps, cheapest first — see below
apify_proxy	—	{ country: "US" } for the proxied steps
proxy	—	your own proxy URL; used alone

Plus output.signed_upload_url, cleanup and callback, as in the other actors in this suite.

Network cost: cheap steps first

Residential proxy traffic is billed per GB and is by far the largest cost of a download; compute and datacenter traffic are an order of magnitude cheaper. The ladder runs in three tiers:

1. Own IP (direct) — the fastest and cheapest path.
2. Datacenter proxy (DATACENTER, auto mode) — when the own IP is refused.
3. Residential — opened only once every cheaper step failed, at resolve or during the download.

The media bytes always travel over exactly one step: the signed media URL is bound to the IP that resolved it. Walls no network can pass (age gate, private, members-only, not live yet, copyright) stop the ladder before any residential session opens. Every result reports meta.egress = { lane, tier, bytes }.

Examples

Resolve direct URLs only (no download, cheapest)

{ "op": "resolve", "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX" }

Audio only, for transcription

{ "op": "audio", "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX" }

Cut two windows out of a long video

{
  "op": "window",
  "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "options": {
    "segments": [
      { "start_sec": 65,   "end_sec": 118,  "name": "intro" },
      { "start_sec": 1490, "end_sec": 1552, "name": "demo" }
    ]
  }
}

720p H.264, 32 parallel lanes

{
  "op": "full",
  "source": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "options": { "min_height": 720, "max_height": 720, "prefer_codec": "h264", "lanes": 32 }
}

Output

{
  "status": "success",
  "op": "full",
  "artifacts": [
    { "name": "video", "kv_key": "video.mp4", "url": "https://api.apify.com/v2/key-value-stores/.../video.mp4", "bytes": 84213344 }
  ],
  "meta": {
    "title": "…",
    "duration_sec": 1820.5,
    "width": 1920, "height": 1080, "fps": 30,
    "video_format_id": "137", "audio_format_id": "140",
    "direct_urls": { "video": "https://…", "audio": "https://…" },
    "download_sec": 41.2
  }
}

op: "resolve" returns meta.direct_urls and format details with no artifact.

Error handling

{ "ok": false, "reason": "UPSTREAM_BLOCKED", "message": "..." }

reason	Meaning	What to do
BAD_INPUT	not a supported page URL	check the link opens in a browser
UPSTREAM_BLOCKED	bot check, age or region gate	pass cookies and/or apify_proxy
TIMEOUT	download exceeded the run timeout	lower the height, or use full_multi fan-out
OOM_LIMIT	file too large for the memory setting	run with 16 GB, or use window
INTERNAL	unexpected failure	retry; report the run ID

Performance

16 GB run (≈4 vCPU):

Job	Typical time
resolve	3–10 s
audio (1 h source)	15–40 s
full 720p (1 h source)	1–3 min
full 1080p (1 h source)	2–5 min

More lanes help until the host starts throttling; 8–32 is the useful range.

FAQ

Which sites work? Anything yt-dlp supports — the actor uses it for resolution and format selection.

Can I skip downloading entirely? Yes: op: "resolve" gives you the direct URLs, and range-capable consumers can read them straight away.

Why prefer_codec: "h264"? H.264 + AAC muxes into MP4 with a stream copy, so there is no transcode step and no quality loss.

Private or age-restricted videos? Provide cookies (Netscape format) or a cookies_url, and consider apify_proxy with a residential group.

What next in the pipeline? Feed the resulting URL to the Speech to Text, Speaker Diarization or Face Detection & Auto Reframe actors.