difyz9/yt-dlp-api repository overview
yt-dlp API
A lightweight RESTful API service built with FastAPI and yt-dlp for video downloading and information retrieval. Supports asynchronous download processing, multiple video formats, and persistent task management.
✨ Features
- 🚀 Asynchronous Processing - Non-blocking download tasks
- 📊 Task Management - Track download progress with persistent storage
- 🎥 Multiple Formats - Support for various video/audio formats
- 🔄 Auto-Updates - yt-dlp automatically updated to latest version weekly
- 🐳 Multi-Platform - Docker images for AMD64 and ARM64
- ⚙️ Configurable - Full environment variable support
- 📁 File Download - Direct video file download via API
🚀 Quick Start
Run with Docker
docker run -d \
-p 8000:8000 \
-v $(pwd)/downloads:/app/downloads \
-v $(pwd)/data:/app/data \
--name yt-dlp-api \
difyz9/yt-dlp-api:latest
The API will be available at http://localhost:8000
Run with Docker Compose
Create a docker-compose.yml:
version: '3.8'
services:
yt-dlp-api:
image: difyz9/yt-dlp-api:latest
container_name: yt-dlp-api
ports:
- "8000:8000"
environment:
HOST: 0.0.0.0
PORT: 8000
DOWNLOAD_DIR: /app/downloads
DB_FILE: /app/data/tasks.db
MAX_CONCURRENT_DOWNLOADS: 3
LOG_LEVEL: INFO
volumes:
- ./downloads:/app/downloads
- ./data:/app/data
restart: unless-stopped
Start the service:
docker-compose up -d
⚙️ Configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
HOST | Server host address | 0.0.0.0 |
PORT | Server port | 8000 |
DOWNLOAD_DIR | Download directory | /app/downloads |
DB_FILE | SQLite database file | tasks.db |
MAX_CONCURRENT_DOWNLOADS | Max concurrent downloads | 3 |
MAX_FILENAME_LENGTH | Max filename length | 200 |
LOG_LEVEL | Log level (DEBUG/INFO/WARNING/ERROR) | INFO |
Example with Custom Configuration
docker run -d \
-p 9000:9000 \
-e HOST=0.0.0.0 \
-e PORT=9000 \
-e DOWNLOAD_DIR=/app/downloads \
-e MAX_CONCURRENT_DOWNLOADS=5 \
-e LOG_LEVEL=DEBUG \
-v $(pwd)/downloads:/app/downloads \
-v $(pwd)/data:/app/data \
difyz9/yt-dlp-api:latest
📖 API Usage
Submit Download Task
curl -X POST http://localhost:8000/download \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"format": "bestvideo+bestaudio/best"
}'
Response:
{
"status": "success",
"task_id": "550e8400-e29b-41d4-a716-446655440000"
}
Check Task Status
curl http://localhost:8000/task/550e8400-e29b-41d4-a716-446655440000
Response:
{
"status": "success",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"status": "completed",
"result": { ... }
}
}
Download Completed Video File
curl -O -J http://localhost:8000/download/550e8400-e29b-41d4-a716-446655440000/file
Get Video Information
curl "http://localhost:8000/info?url=https://www.youtube.com/watch?v=VIDEO_ID"
List All Tasks
curl http://localhost:8000/tasks
List Available Formats
curl "http://localhost:8000/formats?url=https://www.youtube.com/watch?v=VIDEO_ID"
🔧 API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /download | Submit a download task |
GET | /task/{task_id} | Get task status |
GET | /tasks | List all tasks |
GET | /download/{task_id}/file | Download completed video file |
GET | /info | Get video information |
GET | /formats | List available formats |
📦 Volumes
/app/downloads- Downloaded video files/app/data- SQLite database for task persistence
Important: Mount these volumes to persist your data across container restarts.
🏷️ Image Tags
latest- Latest stable release (includes latest yt-dlp)v1.0.0- Specific version releaseytdlp-YYYY.MM.DD- Specific yt-dlp version
🔄 Auto-Update Strategy
The Docker image is automatically rebuilt weekly to include the latest version of yt-dlp, ensuring compatibility with video platforms.
💡 Use Cases
- Automated Video Archival - Integrate with automation tools like n8n, Zapier
- Batch Downloads - Process multiple videos with task management
- Video Information Extraction - Get metadata without downloading
- Custom Workflows - Build custom video processing pipelines
- Self-hosted Solution - Full control over your video downloads
🔒 Security Notes
- Network Security: Consider restricting access with reverse proxy
- Storage: Ensure sufficient disk space for downloads
- Compliance: Respect video platform terms of service and copyright
📝 Example Workflows
Integration with n8n
// n8n HTTP Request Node
{
"method": "POST",
"url": "http://yt-dlp-api:8000/download",
"body": {
"url": "{{$json.video_url}}",
"format": "bestvideo+bestaudio/best"
}
}
Python Integration
import requests
# Submit download
response = requests.post('http://localhost:8000/download', json={
'url': 'https://www.youtube.com/watch?v=VIDEO_ID',
'format': 'bestvideo+bestaudio/best'
})
task_id = response.json()['task_id']
# Check status
status = requests.get(f'http://localhost:8000/task/{task_id}')
print(status.json())
Shell Script
#!/bin/bash
# Download video and wait for completion
URL="https://www.youtube.com/watch?v=VIDEO_ID"
# Submit task
TASK_ID=$(curl -s -X POST http://localhost:8000/download \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Poll for completion
while true; do
STATUS=$(curl -s http://localhost:8000/task/$TASK_ID | jq -r '.data.status')
echo "Status: $STATUS"
if [ "$STATUS" = "completed" ]; then
echo "Download completed!"
curl -O -J http://localhost:8000/download/$TASK_ID/file
break
elif [ "$STATUS" = "failed" ]; then
echo "Download failed!"
break
fi
sleep 5
done
🐛 Troubleshooting
Container logs
docker logs yt-dlp-api
Check container status
docker ps -a | grep yt-dlp-api
Restart container
docker restart yt-dlp-api
Access container shell
docker exec -it yt-dlp-api /bin/bash
📄 License
This project is open source. Please check the repository for license details.
🔗 Links
🤝 Support
For issues, questions, or contributions, please visit the GitHub repository.
Built with ❤️ using FastAPI and yt-dlp
Tag summary
Content type
Image
Digest
sha256:180ea845b…
Size
548.9 MB
Last updated
1 day ago
docker pull difyz9/yt-dlp-api