yt-dlp_api

A high-performance, asynchronous web API and Telegram bot ecosystem for YouTube search, metadata extraction, playlist parsing, and audio/video stream URL resolution.

This repository provides a unified FastAPI backend and a Pyrogram-based Telegram bot. It features native integration with Redis for caching and rate limiting, and uses Deno for solving YouTube EJS signature challenges.

Features

⚡ High Performance & Async: Fully asynchronous API built on FastAPI, Uvicorn, and Pyrogram.
🚀 Advanced Stream Extraction: Resolves direct video and audio streams via yt-dlp using optimized player client parameters.
🇩 EJS Challenge Solver: Integrated Deno JS runtime inside the container to solve complex YouTube EJS signature challenges dynamically.
🗄️ Redis Caching: Caches stream metadata, resolving configurations, and rates to minimize latency and avoid YouTube rate limits.
🔒 Token-Based Rate Limiting: Automatic user rate limiting managed via a Redis-backed token system.
🤖 Telegram Bot Management: Simple Telegram bot for users to generate tokens, check limits, and for admins to manage users, customize rate limits, broadcast announcements, and view real-time API logs.
🐳 Docker-Compose Ready: Easy, zero-config deployment using Docker Compose.

Architecture Overview

               +-----------------------+
               |  FastAPI Web Service  | <--- REST API Clients
               +-----------------------+
                            |
                            v
 +--------------+     +-----------+     +-------------------+
 | Telegram Bot | --> |   Redis   | <-- |    utils Module   |
 +--------------+     +-----------+     +-------------------+
  (User/Token          (Rate Limits          (Search, Stream
   Management)          & Caching)            & Playlist Parsing)
                                              |
                                              v
                                        +-------------+
                                        | Deno / Yt   |
                                        +-------------+

Quick Start (Docker Deployment)

The easiest way to run the entire stack (FastAPI, Telegram Bot, Redis) is using Docker Compose.

1. Prerequisites

Ensure you have Docker and Docker Compose installed.

2. Configure Environment Variables

Create a .env file in the root directory and configure your credentials:

# Telegram Bot API Credentials
API_ID=
API_HASH=
BOT_TOKEN=your_bot_token

# Space-separated list of Telegram user IDs with administrative rights
ADMIN_IDS="6076474757 2128132096"

# Redis Configuration (Optional: default uses redis service container)
REDIS_HOST=redis
REDIS_PORT=6379

# API Rate Limits
DAILY_LIMIT=1000
ADMIN_LIMIT=10000

# Deployment Host
API_HOST=api.nubcoders.com

# Public API Base URL
BASE_URL=http://api.nubcoders.com

3. Run the Services

Start the application stack:

docker-compose up --build -d

This will spin up:

FastAPI Web API on port 8000
Telegram Bot runner
Redis Cache Database

Manual Installation (Local Development)

If you prefer to run the services locally without Docker:

1. Install System Dependencies

Install FFmpeg (required by yt-dlp for media processing).
Install Deno (required for solving signature challenges):
```
curl -fsSL https://deno.land/install.sh | sh
```

2. Install Python Dependencies

pip install -r requirements.txt

3. Run the Services

Run the Redis server locally, and then start the API and Bot:

# Start the API and Bot services concurrently
python3 main.py

Or you can run the bot separately:

python3 bot.py

Configuration Reference

All secrets and configurations can be customized via environment variables:

Environment Variable	Description	Default
`API_ID`	Telegram API ID (from my.telegram.org)	`2040`
`API_HASH`	Telegram API Hash (from my.telegram.org)	`b18441a1ff...`
`BOT_TOKEN`	Token for the Pyrogram bot	`None`
`TG_GROUP`	Telegram support/discussion group username	`nub_coder_s`
`TG_CHANNEL`	Telegram news/update channel username	`nub_coders`
`ADMIN_IDS`	Space-separated list of admin Telegram IDs	`""`
`REDIS_HOST`	Hostname of the Redis server	`localhost`
`REDIS_PORT`	Port of the Redis server	`15440`
`REDIS_USERNAME`	Username for Redis authentication	`default`
`REDIS_PASSWORD`	Password for Redis authentication	`None`
`API_HOST`	Traefik host used by Docker Compose	`api.nubcoders.com`
`BASE_URL`	Public base URL used in bot/docs	`http://api.nubcoders.com`
`DAILY_LIMIT`	Default daily requests limit for free tier users	`1000`
`ADMIN_LIMIT`	Default daily requests limit for administrators	`10000`

Web API Endpoints

The web API is served at http://localhost:8000. Public endpoints are free, while data-heavy parsing endpoints require an API token passed as a query parameter (e.g., ?token=YOUR_TOKEN).

Public Endpoints (Free)

`GET /health`

Returns service health status.

Response: {"status": "ok"}

`GET /`

Returns service metadata and an endpoint directory.

`GET /search`

Perform queries on YouTube or YouTube Music.

Parameters:
- q (string, required): Query term.
- limit (integer, optional): Maximum results. Default 5.
- method (string, optional): 'scrape' (free crawler, default) or 'api' (official YouTube Data API).
Response: Search result list with titles, URLs, duration, and channel metadata.

`GET /trending`

Get trending music tracks.

Parameters:
- limit (integer, optional): Maximum results. Default 10.

`GET /suggest`

Get search completion suggestions for a partial query.

Parameters:
- q (string, required): Partial query.
- limit (integer, optional): Maximum suggestions. Default 5.

Authenticated Endpoints

Must include query parameter: token=YOUR_API_TOKEN

`GET /rate-limit-status`

Check your current token request usage and remaining quota.

`GET /info`

Get parsed metadata and direct streaming links for a video.

Parameters:
- q (string, required): YouTube video URL or search query.
- max_results (integer, optional): Max search results if q is a query. Default 1.
- mode (string, optional): 'audio' (default) or 'video'.
- redirect (boolean, optional): Return a temporary redirect URL or wait for extraction. Default True.

`GET /stream`

Resolve and return direct audio/video stream URLs.

Parameters:
- q (string, required): YouTube video URL or ID.
- mode (string, optional): 'audio' (default) or 'video'.
- redirect (boolean, optional): Return a temporary redirect URL. Default False.

`GET /stream/redirect`

Get an instant redirect URL for audio streaming (ideal for pytgcall integrations).

Parameters:
- q (string, required): YouTube video URL or ID.
- mode (string, optional): 'audio' (default) or 'video'.

`GET /video-stream`

Resolve and return separate high-quality video and audio URLs.

Parameters:
- q (string, required): YouTube video URL or ID.
- redirect (boolean, optional): Return a temporary redirect URL. Default False.

`GET /video-stream/redirect`

Get an instant redirect URL for video streaming.

Parameters:
- q (string, required): YouTube video URL or ID.
- type (string, optional): 'audio' (default) or 'video'.

`GET /playlist`

Parse all video tracks in a playlist.

Parameters:
- url (string, required): YouTube Playlist URL or ID.

Telegram Bot Interface

Users can interact with the Telegram bot (e.g. @ytdlp_nub_bot) to obtain an API token and monitor their request counts.

User Commands

/start - Authenticates user, creates account, and issues an API token.
/menu - Interactive inline button interface for checking rates and profile.
/token - Displays the user's active API token.
/status - Checks current rate limits, tier, and requested endpoint counts.
/ping - Latency ping check with bot uptime statistics.
/revoke - Revokes your current token and generates a new one.
/help - Show help and API documentation.

Administrative Commands (Admins only)

/stats - Comprehensive API performance dashboard (requests, uptime, user tiers, active logs).
/user <tg_id> - Inspect usage statistics and rate limit status of a specific user.
/grant <tg_id> <limit> - Set custom daily rate limit for a specific user.
/revoke <tg_id> - Reset custom rate limit for a user back to default.
/listusers - List all registered user IDs.
/errors - Display recent API 4xx/5xx failure logs with details.
/broadcast <msg> - Send an announcement message to all registered bot users.
/adminhelp - Show helper card for all administrative commands.

Programmatic Usage

If you prefer to import the modules programmatically inside other Python scripts, use the utils package:

import asyncio
from utils import Search, get_stream

async def main():
    # 1. Search song
    results = await Search("Kesariya", limit=1)
    if results and results.get("main_results"):
        song = results["main_results"][0]
        print(f"Found: {song['title']} by {song['channel']}")
        
        # 2. Extract direct stream URL
        stream_url = await get_stream(song['url'])
        print(f"Direct stream URL: {stream_url}")

asyncio.run(main())

Project Structure

yt-dlp_api/
│
├── config.py              # Centralised environment variable loader
├── main.py                # FastAPI endpoints and middleware / bot runner
├── bot.py                 # Bot startup script
├── tools.py               # Redis client connection and token handlers
│
├── utils/                 # Shared utilities and parsers
│   ├── __init__.py        # Package exports
│   ├── cache_manager.py   # Stream cache resolver (Redis & Local)
│   ├── cli_tool.py        # Command-line utility interface
│   ├── formatters.py      # Video output list formatter
│   ├── helpers.py         # Utility calculation functions
│   ├── media_extractor.py # Audio/video link resolving logic (yt-dlp)
│   ├── playlist_parser.py # Playlist item parser
│   ├── search_service.py  # Scraping-based search crawler
│   └── youtube_api.py     # Fallback YouTube Data API crawler
│
└── plugins/               # Telegram bot pyrogram plugins
    ├── admin.py           # Administrative stats, limits, and error logs
    ├── broadcast.py       # Global bot broadcast dispatcher
    ├── commands.py        # Menu, ping, start commands
    └── status.py          # User profile status and tokens

License

This project is licensed under the MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
plugins		plugins
utils		utils
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bot.py		bot.py
config.py		config.py
docker-compose.yml		docker-compose.yml
main.py		main.py
requirements.txt		requirements.txt
test_ytdlp.py		test_ytdlp.py
tools.py		tools.py

Folders and files

Latest commit

History

Repository files navigation

yt-dlp_api

Features

Architecture Overview

Quick Start (Docker Deployment)

1. Prerequisites

2. Configure Environment Variables

3. Run the Services

Manual Installation (Local Development)

1. Install System Dependencies

2. Install Python Dependencies

3. Run the Services

Configuration Reference

Web API Endpoints

Public Endpoints (Free)

GET /health

GET /

GET /search

GET /trending

GET /suggest

Authenticated Endpoints

GET /rate-limit-status

GET /info

GET /stream

GET /stream/redirect

GET /video-stream

GET /video-stream/redirect

GET /playlist

Telegram Bot Interface

User Commands

Administrative Commands (Admins only)

Programmatic Usage

Project Structure

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /health`

`GET /`

`GET /search`

`GET /trending`

`GET /suggest`

`GET /rate-limit-status`

`GET /info`

`GET /stream`

`GET /stream/redirect`

`GET /video-stream`

`GET /video-stream/redirect`

`GET /playlist`

Packages