ydl_api_ng

A no-frills look at the tool that turns yt-dlp into a proper server-side service. No marketing, just what actually ships.

TL;DR

• What it is: A REST API layer on top of yt-dlp (the actively maintained youtube-dl fork), giving you an HTTP endpoint to trigger downloads from any of the 1,000+ sites yt-dlp supports [README].
• Who it’s for: Self-hosters who want to queue media downloads from a browser, mobile app, or home automation without SSH-ing into a server and typing commands [README].
• Cost savings: yt-dlp is free. The API wrapper is free (GPL-3.0). You pay for a VPS or run it on a home server — that’s it. No subscription to any “download manager” SaaS [README].
• Key strength: Full pass-through of yt-dlp options. You’re not limited to what the developer exposed — every yt-dlp flag is a first-class citizen in the parameter file system [README].
• Key weakness: 229 GitHub stars, minimal documentation beyond the README, no third-party reviews, no active community visible. This is a one-person project that works but comes with all the support risks that implies [GitHub].
• Honest note: The third-party articles provided for this review cover 123movies streaming alternatives — none of them mention ydl_api_ng. This review is based primarily on the README and general knowledge of the yt-dlp ecosystem. Take the depth of analysis accordingly.

---

What is ydl_api_ng

ydl_api_ng (the “ng” stands for “next generation”) is the second version of ydl_api, a small Flask-based REST API that wraps yt-dlp and exposes download operations over HTTP. You send a POST request with a URL and some parameters, and the server downloads the media into a folder you mapped [README].

The practical use case is simple: you’re watching a video in your browser, you want to save it to your NAS or home server, and you don’t want to open a terminal. Instead, a browser userscript catches the URL and sends it to your ydl_api_ng instance with a click. The download runs server-side, and the file lands wherever you configured [README].

The original ydl_api had a fixed set of exposed parameters — if yt-dlp added a new option, you had to wait for the developer to wire it up. ydl_api_ng replaces that with a parameter file system (params.ini plus params_metadata.ini) where you define presets. Any yt-dlp option you can name in a config file works. That means format selection, subtitle embedding, cookies for paywalled content, SponsorBlock integration — whatever yt-dlp supports, you can expose through the API without touching the application code [README].

The project sits at 229 GitHub stars and is licensed GPL-3.0 [GitHub]. It is a small, focused tool by one developer (Totonyus), not a commercial product or a funded startup.

---

Why People Choose It

There’s no pile of Trustpilot reviews or Hacker News threads to synthesize here — ydl_api_ng is a niche tool with a niche audience. But the use case is real, and the design choices reflect real pain points:

The yt-dlp CLI is not a daemon. yt-dlp is one of the most capable media download tools in existence — over 1,000 supported sites, active maintenance, regular updates. But it’s a command-line tool. Running it on a remote server means SSH, typing full commands, then checking back later. For anything you want to run routinely or trigger from a phone, that workflow breaks down [README].

Browser-to-server download pipelines exist, but most are overbuilt. Tools like Tube Archivist or TubeSync are full-featured archivist systems with their own databases, web UIs, and opinionated workflows. If you want to save a single video to a folder without managing a collection, those tools are more than you need. ydl_api_ng is just an API — no database, no web UI, no subscriptions, no watching channels. Send URL, get file [README].

The original ydl_api hit a ceiling. The README explicitly explains the motivation: ydl_api was limited to a few parameters, adding new ones required code changes, and it wasn’t suitable for advanced yt-dlp users. ydl_api_ng rewrites the parameter system so it’s file-driven, not hardcoded [README]. This is a small-scale but principled architectural decision.

Redis queue for reliability. Downloads can take time, especially for large video files or when yt-dlp has to process playlists. The default Docker image ships with Redis enabled for queue management, so you’re not at the mercy of an HTTP timeout [README]. This separates it from simpler “just exec yt-dlp” wrappers.

---

Features

Based on the README and Docker image:

Core download engine:

• Wraps yt-dlp — supports every site yt-dlp supports (1,000+) [README]
• REST API interface for triggering downloads programmatically [README]
• Parameter preset system via params.ini and params_metadata.ini — define named download profiles [README]
• Pass any yt-dlp option through the parameter file system without modifying application code [README]
• Progress hooks via progress_hooks.py — hook into download progress events with custom Python logic [README]
• Custom Python scripts importable via the hooks_utils/ volume [README]

Queue management:

• Optional Redis integration for download queue management [README]
• Redis is enabled by default in the Docker image [README]
• Can be disabled if you prefer a simpler stateless setup [README]

Browser integration:

• Ships a userscript.js compatible with Greasemonkey (Firefox) and Tampermonkey (Chrome) [README]
• The userscript adds download buttons to pages across any matched site [README]
• Configurable presets in the userscript map to server-side parameter profiles [README]

Deployment options:

• Docker image on Docker Hub: totonyus/ydl_api_ng [README]
• docker-compose file included [README]
• Bare-metal installation with systemd service file included [README]
• FORCE_YTDLP_VERSION environment variable lets you pin a specific yt-dlp release [README]
• UID/GID configuration so downloaded files are owned by the right user [README]

Volumes (Docker):

• /app/downloads/ — where files land [README]
• /app/params/ — parameter configuration files [README]
• /app/params/hooks_utils/ — custom Python hook scripts [README]
• /app/logs — application logs [README]

What it doesn’t have:

• No web UI — this is purely a REST API
• No built-in authentication (you’d add that at the reverse proxy layer)
• No subscription/channel watching features
• No built-in media organization or renaming beyond what yt-dlp’s own --output template supports

---

Pricing: SaaS vs Self-Hosted Math

ydl_api_ng is free software under GPL-3.0. There is no commercial version, no hosted SaaS, and no pricing page. Your costs are infrastructure only.

What you’re replacing: There are a handful of commercial download tools and browser extensions that do similar things — Downie on macOS ($19.99 one-time), various browser plugins with subscription tiers ($3–10/mo), or upload-to-a-service approaches that charge per download. If you’re currently paying for any of those and you have a server already, ydl_api_ng costs nothing to add [README].

Infrastructure cost:

• Running on an existing home server or NAS: $0 additional
• Cheapest Hetzner VPS (2GB RAM, enough for queue downloads): ~$4/mo
• A Raspberry Pi on your home network: one-time hardware cost, ~$0/mo ongoing

The real cost is maintenance: yt-dlp updates frequently to keep up with site changes — YouTube especially likes to break extractors. The FORCE_YTDLP_VERSION variable lets you pin a version, but the flip side is you’ll want to update regularly to keep downloads working. This isn’t unique to ydl_api_ng — it’s the reality of any yt-dlp wrapper [README]. Budget periodic attention, not just a one-time setup.

---

Deployment Reality Check

The Docker path is the documented and easiest route. You pull the image, configure your volumes, map port 5011 (or whatever you choose) to internal port 80, and start the container [README].

What you actually need:

• Docker and docker-compose
• A directory for downloads with correct permissions (configure UID/GID to match your user) [README]
• Optional: a domain + reverse proxy (nginx, Caddy) if you want to hit it from outside your network
• Optional: authentication at the proxy layer if you expose it externally — the API itself has no auth

What the README doesn’t tell you:

• There’s no documented API schema beyond what you infer from the parameter files
• Error handling behavior is undocumented — you’ll need to check logs when things go wrong
• The userscript setup requires you to edit the host URL manually and match your server’s preset names [README]
• Cookie handling for authenticated sites (Patreon, YouTube members-only, etc.) isn’t covered — but yt-dlp supports it, so you’d configure it through the parameter file system

UID/GID permissions are the most common trip-up. Downloads land as user 1000:1000 by default [README]. If your server runs a different user, or your NAS has different ownership expectations, you’ll see permission errors on the downloaded files. The fix is straightforward — set UID and GID in your docker-compose — but it’s easy to miss.

Realistic time estimates:

• Technical user who has Docker already: 15–30 minutes to a working instance
• Adding the browser userscript: another 10 minutes
• Tuning parameter presets for your preferred quality/format: 30–60 minutes depending on how specific you want to get

For a non-technical user, this is not the right tool. There’s no setup wizard, no UI, and debugging requires reading logs.

---

Pros and Cons

Pros

• Full yt-dlp pass-through. The parameter file system is genuinely well-designed — you’re not limited to what the developer bothered to expose. If yt-dlp can do it, you can configure it [README].
• Redis queue included. Downloads don’t block the HTTP response. The queue handles concurrent requests and long-running jobs without configuration [README].
• Browser userscript integration. The userscript + server combo is genuinely useful — one click from a page, download runs server-side [README].
• Progress hooks. The Python hook system lets you extend download behavior (notifications, post-processing, moving files) without modifying the application [README].
• Lightweight. No database beyond Redis for queue state, no UI server, no background scrapers. Minimal resource footprint.
• Free, GPL-3.0. No licensing complications for personal use.
• Pinnable yt-dlp version. FORCE_YTDLP_VERSION is a small but practical feature for stability [README].

Cons

• 229 stars, one developer. This is a hobby project. There’s no issue SLA, no community forum, no documentation site beyond the README. If the developer moves on, the project stagnates [GitHub].
• No authentication. The API has no built-in auth. If you expose this to the internet without a reverse proxy with auth, anyone can trigger downloads on your server [README].
• No web UI. You interact with this through the API or the userscript. There’s no dashboard to see queue status, cancel downloads, or browse history.
• Sparse documentation. The README covers installation. The parameter file system is self-documenting via params_metadata.ini, but figuring out advanced configurations requires reading yt-dlp’s own docs and experimenting.
• yt-dlp churn. Sites break yt-dlp extractors regularly. The wrapper itself is stable, but the underlying tool requires attention. Not unique to ydl_api_ng, but worth knowing before you set it up and forget it.
• No API schema. There’s no OpenAPI spec, no documented endpoints with typed request/response examples. You reverse-engineer from the parameter files and trial-and-error.
• GPL-3.0 copyleft. For personal use, irrelevant. For anyone building a product on top of this, the GPL-3.0 license means your product must also be GPL-3.0. That’s a hard no for most commercial applications.

---

Who Should Use This / Who Shouldn’t

Use ydl_api_ng if:

• You already self-host other services and want to add a download endpoint to your stack.
• You want to trigger yt-dlp downloads from a browser or mobile device without touching the command line.
• You’re comfortable with Docker, volume permissions, and reading log files when something breaks.
• You want fine-grained control over yt-dlp options (format selection, subtitle languages, cookies, SponsorBlock) via named presets.
• You understand you’re maintaining this yourself with minimal external support.

Skip it (use Tube Archivist instead) if:

• You want to archive entire YouTube channels with organized libraries, metadata, and a web UI to browse your collection.
• You need a polished UX with clear status feedback beyond log files.

Skip it (use Jellyfin + Sonarr/Radarr + yt-dlp scripts instead) if:

• You want downloads integrated into a media server workflow with proper metadata.

Skip it (just use yt-dlp directly) if:

• You only occasionally download something and don’t mind running a command. Adding a server just adds complexity you don’t need.

Skip it entirely if:

• You’re not comfortable with Docker and self-hosting basics. There’s no supported path to making this work without that foundation.

---

Alternatives Worth Considering

• Tube Archivist — Full-featured YouTube archival system with its own web UI, Elasticsearch backend, and channel subscription support. Much heavier, much more capable for collection management. Same yt-dlp foundation.
• TubeSync — Similar to Tube Archivist, Django-based, focused on keeping local copies of YouTube channels in sync.
• yt-dlp directly — The underlying tool. If you want downloads from the command line or scheduled via cron, yt-dlp alone is simpler. ydl_api_ng adds value specifically for the REST API / userscript workflow.
• Alltube — Another web front-end for yt-dlp, but focused on streaming video in the browser rather than queued server-side downloads. Different use case.
• MeTube — A web UI for yt-dlp with a queue, progress display, and format selection. More polished UX than ydl_api_ng, but less programmable (no REST API for external triggers). If you want a UI instead of an API, MeTube is the obvious comparison.

For the specific use case of “I want to click a button in my browser and have a video download to my server in the background,” the realistic shortlist is ydl_api_ng vs MeTube. Choose ydl_api_ng if you want API-driven automation and full yt-dlp option control. Choose MeTube if you want a visual queue you can manage in a browser tab.

---

Bottom Line

ydl_api_ng does one thing: it puts a REST API in front of yt-dlp so you can trigger downloads remotely without touching the command line. The parameter file system is a genuine improvement over its predecessor — you’re not stuck with whatever the developer chose to expose, you just configure presets in an ini file. The Redis queue and Python hook system are practical additions that separate it from simpler exec-and-pray wrappers.

The limitations are the predictable ones for a 229-star hobby project: no UI, no authentication, sparse documentation, and a single-developer support story. If you know what you’re doing with Docker and yt-dlp, this is a clean 20-minute addition to your self-hosted stack. If you need hand-holding, look at MeTube instead. If you need channel archiving, look at Tube Archivist. ydl_api_ng is exactly what it says it is — no less, but also no more.

If you want ydl_api_ng (or any other self-hosted tool) deployed and configured without spending your afternoon reading Docker logs, that’s precisely what upready.dev does.

---

Sources

Primary sources used in this review:

1. ydl_api_ng README — GitHub repository, Totonyus. https://github.com/totonyus/ydl_api_ng
2. GitHub repository metadata — Stars (229), license (GPL-3.0). https://github.com/totonyus/ydl_api_ng

Note on third-party sources: The four third-party articles provided as inputs for this review cover 123movies streaming alternatives and free legal streaming platforms. None of them mention ydl_api_ng or yt-dlp wrapper tooling. They were not used as sources in this article. Claims in this review are derived from the project README and general knowledge of the yt-dlp ecosystem.