Simple dockerized API to work with yt-dlp from your server anywhere
This API offers a range of endpoints for downloading YouTube videos, retrieving video information, and managing API keys. It is designed to be user-friendly while providing robust functionality for video processing and information retrieval. The API leverages yt-dlp to handle video downloads and information retrieval efficiently on a dedicated host.
/get_video
)/get_audio
)/get_video
)/get_audio
)/get_info
)/create_key
)/delete_key/<name>
)/get_keys
)/get_key/<name>
)/status/<task_id>
)/files/<path:filename>
)To run the server, follow these steps:
Clone the repository:
git clone https://github.com/your-username/youtube-downloader-api.git
cd youtube-downloader-api
Build and run the Docker container:
docker-compose up --build
The server will be accessible at http://localhost:5000
.
The server's configuration is defined in the config.py
file. Here are the default values:
DOWNLOAD_DIR
: The directory where downloaded files will be stored. Default is '/app/downloads'
.TASKS_FILE
: The path to the JSON file that stores task information. Default is 'jsons/tasks.json'
.KEYS_FILE
: The path to the JSON file that stores API keys and their permissions. Default is 'jsons/api_keys.json'
.TASK_CLEANUP_TIME
: The time (in minutes) after which completed tasks will be removed. Default is 10
.REQUEST_LIMIT
: The maximum number of requests allowed within the TASK_CLEANUP_TIME
period. Default is 20
.MAX_WORKERS
: The maximum number of concurrent workers for processing tasks. Default is 4
.All requests to the API must include an API key in the X-API-Key
header. To obtain an API key, contact the API administrator or use the /create_key
endpoint if you have create_key permissions.
/get_video
)Initiates a video get_video task from the specified URL.
/get_video
X-API-Key
: Your API keyContent-Type
: application/json{
"url": "https://youtu.be/1FPdtR_5KFo",
"video_format": "bestvideo[height<=1080]",
"audio_format": "bestaudio[abr<=129]"
}
get_video
permission.{
"status": "waiting",
"task_id": "abcdefgh12345678"
}
/get_audio
)Initiates a audio get_audio task from the specified URL.
/get_audio
X-API-Key
: Your API keyContent-Type
: application/json{
"url": "https://youtu.be/1FPdtR_5KFo"
}
url
(required): The URL of the audio to be downloaded.get_audio
permission.{
"status": "waiting",
"task_id": "abcdefgh12345678"
}
/get_live_video
)Initiates a video get_live_video task from the specified URL.
/get_live_video
X-API-Key
: Your API keyContent-Type
: application/json{
"url": "https://youtu.be/1FPdtR_5KFo",
"start": 0,
"duration": 300,
"video_format": "bestvideo[height<=1080]",
"audio_format": "bestaudio[abr<=129]"
}
url
(required): The URL of the live stream to be downloaded.start
(optional): The starting point in seconds for the stream recording.duration
(required): The length of the recording in seconds from the start point.video_format
(optional): The format of the video. Default is "bestvideo".audio_format
(optional): The format of the audio. Default is "bestaudio".get_live_video
permission.{
"status": "waiting",
"task_id": "abcdefgh12345678"
}
/get_live_audio
)Initiates a audio get_live_audio task from the specified URL.
/get_live_audio
X-API-Key
: Your API keyContent-Type
: application/json{
"url": "https://youtu.be/1FPdtR_5KFo",
"start": 0,
"duration": 300
}
url
(required): The URL of the live stream to be downloaded.start
(optional): The starting point in seconds for the stream recording.duration
(required): The length of the recording in seconds from the start point.get_live_audio
permission.{
"status": "waiting",
"task_id": "abcdefgh12345678"
}
/get_info
)Retrieves information about the video from the specified URL.
/get_info
X-API-Key
: Your API keyContent-Type
: application/json{
"url": "https://youtu.be/1FPdtR_5KFo"
}
url
(required): The URL of the video to retrieve information about.get_info
permission.{
"status": "waiting",
"task_id": "ijklmnop87654321"
}
/create_key
)Creates a new API key with the specified permissions.
/create_key
X-API-Key
: Your admin API keyContent-Type
: application/json{
"name": "user_key",
"permissions": ["get_video", "get_audio", "get_live_video", "get_live_audio", "get_info"]
}
name
(required): The name for the new API key.permissions
(required): A list of permissions for the new API key.create_key
permission.{
"message": "API key created successfully",
"key": "new_api_key_here",
"name": "name"
}
/delete_key/<name>
)Deletes an existing API key by its name.
/delete_key/<name>
X-API-Key
: Your admin API keydelete_key
permission.{
"name": "name",
"message": "API key deleted successfully"
}
/get_keys
)Retrieves a list of all existing API keys.
Method: GET
URL: /get_keys
Headers:
X-API-Key
: Your admin API keyPermissions: Requires the get_keys
permission.
Response:
{
"admin_key": {
"key": "admin_api_key_here",
"name": "name",
"permissions": ["create_key", "delete_key", "get_key", "get_keys", "get_video", "get_audio", "get_live_video", "get_live_audio", "get_info"]
},
"user_key": {
"key": "user_api_key_here",
"name": "name",
"permissions": ["get_video", "get_audio", "get_live_video", "get_live_audio", "get_info"]
}
}
/get_key/<name>
)Gets an existing API key by its name.
/get_key/<name>
X-API-Key
: Your admin API keyget_key
permission.{
"message": "API key get successfully",
"name": "name",
"key": "user_api_key_here"
}
/get_keys
)/status/<task_id>
)Retrieves the status of a specific task by its ID.
/status/<task_id>
X-API-Key
: Your API key{
"status": "completed",
"task_type": "get_video",
"url": "https://youtu.be/1FPdtR_5KFo",
"video_format": "bestvideo[height<=1080]",
"audio_format": "bestaudio[abr<=129]",
"file": "/files/abcdefgh12345678/video.mp4"
}
/files/<path:filename>
)Retrieves a file from the server.
/files/<path:filename>
info.json
filequalities
: Returns a structured list of available video and audio qualities formatsinfo.json
files:
info.json
filequalities
parameter:
{
"qualities": {
"audio": {
"249": {
"abr": 47,
"acodec": "opus",
"audio_channels": 2,
"filesize": 528993
},
"139": {
"abr": 48,
"acodec": "mp4a.40.5",
"audio_channels": 2,
"filesize": 549935
}
},
"video": {
"394": {
"height": 144,
"width": 256,
"fps": 25,
"vcodec": "av01.0.00M.08",
"format_note": "144p",
"dynamic_range": "SDR",
"filesize": 1009634
},
"134": {
"height": 360,
"width": 640,
"fps": 25,
"vcodec": "avc1.4D401E",
"format_note": "360p",
"dynamic_range": "SDR",
"filesize": 6648273
}
}
}
}
The API uses standard HTTP status codes to indicate the success or failure of requests. In case of an error, the response will include a JSON object with an error
field describing the issue.
Example error response:
{
"error": "Invalid API key"
}
Common error codes:
import requests
api_key = "your_api_key_here"
base_url = "http://api.example.com"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
data = {
"url": "https://youtu.be/1FPdtR_5KFo",
"video_format": "bestvideo[height<=1080]",
"audio_format": "bestaudio[abr<=129]"
}
response = requests.post(f"{base_url}/get_video", json=data, headers=headers)
print(response.json())
import requests
api_key = "your_api_key_here"
base_url = "http://api.example.com"
task_id = "abcdefgh12345678"
headers = {
"X-API-Key": api_key
}
response = requests.get(f"{base_url}/status/{task_id}", headers=headers)
print(response.json())
Contributions to yt-dlp-host are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue on the GitHub repository. Pull requests are also encouraged.