all posts

yt-dlp vs a Hosted Download API for Agents

A practical comparison of running yt-dlp yourself and calling a hosted download API: install cost, updates, storage, metering, privacy, and failure modes.

Videodownload team

The short answer

Use yt-dlp directly when you control the machine, want local files, and can keep the binary current. Use a hosted API when the caller is an agent acting for someone else, when you need metering and a stable contract, or when the user cannot install Python and ffmpeg.

Both options use the same extractor family. The difference is operational, not magical.

What yt-dlp gives you

yt-dlp is the strongest public extractor. It is Unlicense, updates often, and covers more sites than any hosted service. Running it yourself gives you:

  • Full control over format selection and postprocessing.
  • Local files with no upload or TTL.
  • No per-request fee.
  • The ability to add cookies for content you are authorized to access.

The costs are real:

  • Every machine needs Python, yt-dlp, and ffmpeg.
  • Every user can drift to a different version.
  • A broken extractor is your incident, at the moment a user asks for a file.
  • A long download can fill a disk or a container.
  • There is no account, key, credit, or rate limit unless you build one.

For a single technical user, those costs are easy. For a product, they become a queue, a worker pool, a cleanup job, and a billing system.

What a hosted API adds

A hosted download API is a thin product layer around the same extractor:

  1. A stable contract. Resolve returns normalized metadata and formats. Download returns a job id. Poll returns a signed URL. The agent does not care which extractor version ran.
  2. Metering. API keys, credits, per-key minute limits, and a usage endpoint.
  3. Resource caps. Duration, file size, concurrency, and a short file TTL are enforced before a worker starts.
  4. A queue. Jobs survive a slow platform and do not hold an HTTP connection open.
  5. Abuse controls. Host allowlists, DNS checks, private IP rejection, and structured error codes.

The costs are also real:

  • The URL and job metadata leave your infrastructure.
  • You depend on the provider's uptime and platform coverage.
  • You pay per finished job.
  • A provider can change its policy or price.

The decision in one table

  • Solo developer, local files: yt-dlp. Do not pay for a wrapper.
  • Agent product, many users, no install step: hosted API plus MCP.
  • Privacy-critical, air-gapped: self-host yt-dlp and build the queue and billing yourself.
  • Prototype this week: hosted API, then revisit self-hosting when volume justifies it.

What to check before you pick

Failure reporting. Does the tool tell you PRIVATE_CONTENT and DRM_PROTECTED, or does it retry forever? A stable error code is more useful than a generic 500.

File lifecycle. Where is the file stored, for how long, and who can fetch it? A signed URL with a 15 minute TTL is a reasonable default for a download tool.

Concurrency limits. A shared worker with two slots behaves differently from a per-user queue. Know what happens when ten agents ask at once.

Terms and licensing. yt-dlp is Unlicense. cobalt is AGPL-3.0, which has obligations when you run a modified version as a network service. Read the license before you build a business on it.

Content policy. A hosted service should refuse private, paid, DRM, and login-walled content by default. If it silently accepts cookies from a user, you have a different risk profile.

A migration path that does not hurt

Start with the hosted API and keep the calls behind one module in your code. The surface is small: resolve, create, poll, cancel. If you later move to yt-dlp, replace the module and keep the job model. Your agent prompts and your UI do not change.

If you start with yt-dlp, add a queue and a cleanup job before you expose it to other people. The extractor is the easy part. The lifecycle is the product.

Try both

The Videodownload API has a free tier with 20 credits and a free web downloader. Resolve is free, so you can compare the metadata and format list against your local yt-dlp output without spending a credit.

more posts