Skip to content
Klutch.sh Docs

Deploying ydl_api_ng

Introduction

ydl_api_ng (YouTube-DL API Next Generation) is a RESTful API wrapper for yt-dlp that transforms the powerful command-line video downloader into an HTTP service. Instead of running yt-dlp commands directly, you can send HTTP requests to download videos, extract metadata, and manage downloads programmatically.

Built with Python and Flask, ydl_api_ng provides a clean API interface for integration with applications, automation workflows, and custom frontends. The project is designed to be lightweight yet flexible, supporting most yt-dlp options through the API.

Key highlights of ydl_api_ng:

  • RESTful API: Clean HTTP endpoints for all downloading operations
  • yt-dlp Powered: Leverage yt-dlp’s support for thousands of websites
  • Metadata Extraction: Get video information without downloading
  • Format Selection: Choose specific quality and format options
  • Queue Management: Handle multiple downloads with queuing
  • Webhook Support: Receive notifications when downloads complete
  • Progress Tracking: Monitor download progress through the API
  • Authentication: API key authentication for secure access
  • Customizable: Configure output formats, paths, and options
  • Open Source: Community-maintained and actively developed

This guide walks through deploying ydl_api_ng on Klutch.sh using Docker, configuring the API, and integrating it with your applications.

Why Deploy ydl_api_ng on Klutch.sh

Deploying ydl_api_ng on Klutch.sh provides several advantages for programmatic video downloading:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds ydl_api_ng without manual configuration. Push to GitHub, and your API deploys automatically.

Persistent Storage: Attach persistent volumes for downloaded files and configuration. Your downloads survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on download volume and concurrent requests.

Environment Variable Management: Securely store API keys and sensitive configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your API for clean integration URLs.

Always-On Availability: Your download API remains accessible 24/7 for automated workflows.

Prerequisites

Before deploying ydl_api_ng on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and REST APIs
  • Understanding of yt-dlp options (helpful but not required)

Understanding ydl_api_ng Architecture

ydl_api_ng operates as a Flask-based web service wrapping yt-dlp:

Flask API Server: Handles HTTP requests and manages the API endpoints. Routes requests to appropriate handlers.

yt-dlp Integration: Interfaces with yt-dlp for actual download and extraction operations. Translates API parameters to yt-dlp options.

Download Queue: Manages concurrent downloads and queuing for resource management.

File Manager: Handles downloaded files, organization, and cleanup.

Configuration System: Loads settings from configuration files and environment variables.

API Endpoints Overview

EndpointMethodDescription
/downloadPOSTStart a new download
/infoPOSTGet video metadata without downloading
/statusGETCheck download status
/queueGETList queued downloads
/healthGETHealth check endpoint

Preparing Your Repository

To deploy ydl_api_ng on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

ydl-api-deploy/
├── Dockerfile
├── config.py
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.11-slim


# Install system dependencies including ffmpeg
RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*


# Create app directory
WORKDIR /app


# Clone ydl_api_ng
RUN git clone --depth 1 https://github.com/Totonyus/ydl_api_ng.git .


# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt


# Install/update yt-dlp
RUN pip install --no-cache-dir --upgrade yt-dlp


# Create directories
RUN mkdir -p /downloads /config /logs


# Copy configuration
COPY config.py /app/params.py


# Set environment variables
ENV FLASK_ENV=production
ENV DOWNLOAD_DIR=/downloads


# Expose API port
EXPOSE 5011


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -f http://localhost:5011/health || exit 1


# Start the API server
CMD ["python", "main.py"]

Configuration File

Create a config.py file (will be copied as params.py):

import os


# API Configuration
API_KEY = os.environ.get('API_KEY', '')
API_KEY_ENABLED = bool(API_KEY)


# Server Configuration
HOST = '0.0.0.0'
PORT = 5011


# Download Configuration
DOWNLOAD_DIR = os.environ.get('DOWNLOAD_DIR', '/downloads')
TEMP_DIR = '/tmp/ydl'


# yt-dlp Options
DEFAULT_OPTIONS = {
    'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best',
    'outtmpl': os.path.join(DOWNLOAD_DIR, '%(title)s.%(ext)s'),
    'restrictfilenames': True,
    'noplaylist': True,
    'nocheckcertificate': False,
    'ignoreerrors': False,
    'quiet': True,
    'no_warnings': True,
}


# Queue Configuration
MAX_CONCURRENT_DOWNLOADS = 2
QUEUE_SIZE = 100


# Logging
LOG_LEVEL = os.environ.get('LOG_LEVEL', 'INFO')
LOG_FILE = '/logs/ydl_api.log'


# Webhook Configuration
WEBHOOK_URL = os.environ.get('WEBHOOK_URL', '')
WEBHOOK_ENABLED = bool(WEBHOOK_URL)

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
__pycache__
*.pyc

Environment Variables Reference

VariableRequiredDefaultDescription
API_KEYRecommended-API key for authentication
DOWNLOAD_DIRNo/downloadsDirectory for downloaded files
LOG_LEVELNoINFOLogging verbosity (DEBUG, INFO, WARNING, ERROR)
WEBHOOK_URLNo-URL for download completion webhooks
FLASK_ENVNoproductionFlask environment setting

Deploying ydl_api_ng on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

    Generate an API Key

    Create a secure API key for authenticating requests to your API. Use a long random string for security.

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile config.py .dockerignore
    git commit -m "Initial ydl_api_ng deployment configuration"
    git remote add origin https://github.com/yourusername/ydl-api-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Name it something descriptive like “ydl-api” or “video-downloader”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your ydl_api_ng repository.

    Configure HTTP Traffic

    ydl_api_ng serves its API over HTTP:

    • Select HTTP as the traffic type
    • Set the internal port to 5011

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    API_KEYYour generated API key
    LOG_LEVELINFO (or your preferred level)
    WEBHOOK_URLYour webhook URL (optional)

    Attach Persistent Volumes

    Add persistent storage for downloads:

    Mount PathRecommended SizePurpose
    /downloads50 GBDownloaded video files
    /logs1 GBApplication logs

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Build the container image
    • Install yt-dlp and dependencies
    • Attach the persistent volumes
    • Start the API server
    • Provision an HTTPS certificate

    Test Your API

    Once deployed, test the health endpoint to verify the API is running.

Using the API

Authentication

Include your API key in requests using the X-API-Key header:

X-API-Key: your-api-key

Downloading a Video

Send a POST request to start a download:

Request:

POST /download
Content-Type: application/json
X-API-Key: your-api-key


{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "bestvideo[height<=1080]+bestaudio/best[height<=1080]"
}

Response:

{
  "status": "queued",
  "id": "abc123",
  "message": "Download queued successfully"
}

Getting Video Information

Extract metadata without downloading:

Request:

POST /info
Content-Type: application/json
X-API-Key: your-api-key


{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response:

{
  "title": "Video Title",
  "duration": 212,
  "uploader": "Channel Name",
  "formats": [...],
  "thumbnail": "https://..."
}

Checking Download Status

Query the status of a download:

Request:

GET /status?id=abc123
X-API-Key: your-api-key

Response:

{
  "id": "abc123",
  "status": "downloading",
  "progress": 45.2,
  "filename": "Video_Title.mp4"
}

Common Format Options

Format StringDescription
bestBest quality (any format)
bestvideo+bestaudioBest video and audio merged
bestvideo[height<=1080]+bestaudioMax 1080p video with best audio
bestaudioAudio only (best quality)
worstLowest quality (smallest file)

Integration Examples

Webhook Integration

Configure webhooks to receive download notifications:

# Example webhook payload
{
  "event": "download_complete",
  "id": "abc123",
  "filename": "/downloads/Video_Title.mp4",
  "url": "https://www.youtube.com/watch?v=...",
  "duration": 45.3
}

Automation Workflows

Common integration patterns:

  • Media Library: Auto-download new content for media servers
  • Archival: Scheduled archiving of specific channels or playlists
  • Podcast Conversion: Download and convert videos to audio
  • Content Aggregation: Collect videos from multiple sources

Production Best Practices

Security Recommendations

  • Strong API Key: Use a long, random API key
  • HTTPS Only: Always use HTTPS in production
  • Rate Limiting: Implement rate limiting for public-facing APIs
  • Input Validation: Validate URLs before processing
  • Access Control: Restrict API access to trusted sources

Resource Management

  • Concurrent Downloads: Limit concurrent downloads to prevent resource exhaustion
  • Storage Cleanup: Implement automatic cleanup of old downloads
  • Queue Limits: Set reasonable queue size limits
  • Timeout Settings: Configure appropriate download timeouts

Monitoring

  • Log Analysis: Monitor logs for errors and unusual activity
  • Storage Monitoring: Track disk usage and set alerts
  • Health Checks: Use the health endpoint for monitoring
  • Error Tracking: Implement error reporting for failed downloads

Troubleshooting Common Issues

Download Failures

Symptoms: Downloads fail or return errors.

Solutions:

  • Verify the URL is supported by yt-dlp
  • Check for rate limiting from the source
  • Update yt-dlp to the latest version
  • Review error messages in logs

API Authentication Issues

Symptoms: Requests return 401 or 403 errors.

Solutions:

  • Verify API key is correctly set in environment variables
  • Check API key is included in request headers
  • Ensure API key matches the configured value

Storage Issues

Symptoms: Downloads fail with disk space errors.

Solutions:

  • Check available storage on the persistent volume
  • Implement automatic cleanup of old files
  • Increase volume size if needed
  • Review and adjust retention policies

Slow Downloads

Symptoms: Downloads take longer than expected.

Solutions:

  • Check network connectivity and bandwidth
  • Reduce concurrent download limit
  • Verify source site is accessible
  • Review resource allocation

Additional Resources

Conclusion

Deploying ydl_api_ng on Klutch.sh gives you a powerful video downloading API accessible from anywhere. The combination of yt-dlp’s extensive site support and a clean REST interface enables seamless integration with your applications and automation workflows.

Whether you’re building a media archival system, content aggregation pipeline, or custom video management tool, ydl_api_ng on Klutch.sh provides the foundation for reliable, programmable video downloads without managing complex infrastructure.