YouTube Video Downloader API

A REST API that provides endpoints for searching, extracting metadata, and downloading YouTube videos in mp4, webm, m4a, and mp3 formats across multiple quality levels. It is built on FastAPI and powered by yt-dlp under the hood, making it suitable for both local use and production deployment.

Prerequisites

Before getting started, ensure the following are installed on your system:

• Python 3.10 or higher - the runtime environment
• Git - for cloning the repository

Installation Guide

Step 1: Clone the Repository

Clone the project and navigate into the project directory:

git clone https://github.com/Simatwa/youtube-downloader-api.git
cd youtube-downloader

Step 2: Set Up a Virtual Environment

Create and activate a virtual environment, then install all dependencies:

pip install uv
uv venv
source .venv/bin/activate
uv sync

Tip

It is strongly recommended to keep yt-dlp updated regularly to avoid breakage caused by YouTube-side changes:

uv pip install -U yt-dlp

Step 3: Configure Settings (Optional)

By default, the app loads configuration from config.yml. Review and adjust the values to suit your environment before starting the server.

For a quick production-ready setup, a pre-tuned production.yml is included. Simply rename it to config.yml to use it:

mv production.yml config.yml

Warning

Some settings in config.yml are critical to the app's operation. Incorrect values can break functionality entirely. Make changes only when you understand their effect.

Step 4: Start the Server

Launch the development server with:

uv run python -m app run

Alternatively, use FastAPI's CLI for more control:

fastapi run app

For advanced startup options such as changing the host or port:

uv run fastapi run --help

Once running, the API documentation is available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

Serving Frontend Contents

The API can serve a static frontend alongside the backend. To enable this, set the frontend_dir key in your configuration file to the path of the directory containing your frontend build.

Note

The specified frontend directory must contain an index.html file at its root. Without it, the frontend will not be served correctly. Use YDA_CONFIG_FILE_PATH environment variable to declare path to yaml file serving as configuration file.

Optimizing Server Performance

For production deployments, offloading static file delivery (downloaded audio and video files) to a dedicated static server significantly reduces load on the main API process.

Setup steps:

1. Start the included static file server:

   python servers/static.py

2. Set the static_server_url key in config.yml to point to the static server's URL.

Important

In production, it is recommended to serve static content using uWSGI for better concurrency and stability. The included uwsgi.sh script provides a ready-to-use uWSGI configuration to get you started quickly.

Troubleshooting

Authorization Issues

YouTube actively flags and blocks requests that lack proper browser-like authorization context. This is a common cause of download failures, especially on fresh deployments or IPs with no prior request history.

Recommended workarounds:

1. Cookies + PO Token - Extract your browser cookies and a valid po_token, then pass them to the app. This is the most reliable method. See the full guide: How to extract PO Token

2. Whitelisted Proxy - Route requests through a proxy server that YouTube has not flagged.

Note

Using a proxy does not guarantee success. YouTube's detection mechanisms can flag proxy IPs as well. The cookie + PO token approach is generally more stable.

Utility Servers

Two helper servers are included for extending the API's capabilities in production:

Server	Description
Static Server	Serves downloaded media files independently from the main API process, reducing load and improving throughput
Proxy Server	Forwards requests to a non-HTTPS instance of the YouTube Downloader API hosted on a remote server

Web Interfaces

The following projects provide ready-to-use web frontends for interacting with the YouTube Downloader API:

Index	🎁 Project	⭐ Stars
0	y2mate-clone

Built a frontend that works with this API? Feel free to open a PR and add it to this list.

Additional Resources

• How to extract PO Token - Required reading if you encounter YouTube authorization errors
• yt-dlp documentation - The underlying download engine powering this API
• uWSGI documentation - Recommended for production static file serving

License

• The Unlicense