AEGIS Downloader

01 // PROCESS

How It Works

AEGIS Downloader is a FastAPI-powered backend that wraps yt-dlp. Send a POST request with a video URL, get a job ID, and track the download progress in real time.

🔐

Authenticate

Include your secret API key in every request header as x-api-key. Unauthorized requests are rejected instantly.

🔗

Send URL

POST your video URL and preferred quality to the /download endpoint. Supports YouTube, Instagram, Twitter, TikTok & 1000+ more.

⚙️

Job Queued

The API returns a unique job_id instantly. The download runs in the background using yt-dlp and ffmpeg.

📡

Track Progress

Poll the /status/{job_id} endpoint to get real-time download progress from 0% to 100%.

✅

Done

Status returns "done" with the filename and title. The file is saved on the server or your configured output path.

02 // CAPABILITIES

Features

Built on yt-dlp — the most powerful video downloader engine — wrapped in a clean, authenticated REST API.

🌐

1000+ Sites

YouTube, Instagram, Twitter/X, TikTok, Facebook, Vimeo, Dailymotion, SoundCloud, and over 1000 more platforms supported out of the box.

🎬

Multiple Qualities

Choose from Best, 1080p, 720p, 480p, or MP3 audio-only. AEGIS picks the optimal format using yt-dlp's smart format selection engine.

🔐

API Key Auth

Every endpoint is protected by API key authentication. Set your key as an environment variable — no database needed.

⚡

Async Background Jobs

Downloads run in the background using FastAPI's BackgroundTasks. Your client gets an instant response with a job ID to track.

🎵

MP3 Extraction

Extract audio-only as MP3 from any video. Uses FFmpeg post-processing to convert on the fly with no quality loss.

📊

Live Progress Tracking

Real-time download percentage, file title, and status updates. Poll /status/{id} to build progress bars in your app.

🐳

Docker Ready

Ships with a production Dockerfile with FFmpeg pre-installed. One command to build and deploy anywhere — Railway, VPS, or locally.

📖

Swagger UI Built-in

FastAPI auto-generates interactive API documentation at /docs. Test every endpoint directly in your browser.

🆓

Free to Deploy

Deploy on Railway's free $5/month credit. No credit card needed to get started. Self-hostable on any VPS or local machine.

03 // REFERENCE

API Documentation

All endpoints require the x-api-key header. Base URL: https://your-api.up.railway.app

GET / Health Check

Check if the API is running. No authentication required.

# Response
{
  "message": "Video Downloader API is live 🚀"
}
    

POST /download Start Download

Start a download job. Returns a job_id immediately. The download runs in the background.

# Request
curl -X POST https://your-api.up.railway.app/download \
  -H "x-api-key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=xxx", "quality": "720p"}'

# Response
{
  "job_id": "abc-123-def-456",
  "message": "Download started"
}
    

GET /status/{job_id} Track Progress

Get the current status and progress of a download job using its job_id.

# Request
curl https://your-api.up.railway.app/status/abc-123 \
  -H "x-api-key: your-secret-key"

# Response (downloading)
{
  "status":   "downloading",
  "progress": 47.3,
  "url":      "https://youtube.com/...",
  "quality":  "720p",
  "filename": null,
  "title":    null,
  "error":    null
}

# Response (done)
{
  "status":   "done",
  "progress": 100,
  "filename": "My Video Title.mp4",
  "title":    "My Video Title"
}
    

GET /jobs List All Jobs

Returns all download jobs in memory. Useful for monitoring and debugging.

curl https://your-api.up.railway.app/jobs \
  -H "x-api-key: your-secret-key"
    

Quality Value	Description	Format	Use Case
`best`	Best available quality	Video + Audio	Maximum quality
`1080p`	Full HD — 1920×1080	Video + Audio	HD streaming
`720p`	HD — 1280×720	Video + Audio	Balanced quality/size
`480p`	SD — 854×480	Video + Audio	Low bandwidth
`mp3`	Audio only	Audio Only	Music / podcasts

05 // SETUP

Installation Guide

Get AEGIS Downloader running in minutes. Choose between local development or full cloud deployment on Railway.

Clone / Download Files

Get the 3 required files: api.py, requirements.txt, Dockerfile

mkdir aegis-api

cd aegis-api

# Place your files here

Install Dependencies

Install Python packages locally for testing.

pip install fastapi uvicorn yt-dlp

Run Locally

Start the API server on your machine.

uvicorn api:app \

  --host 0.0.0.0 \

  --port 8000

Push to GitHub

Push all 4 files to a GitHub repository.

git init && git add .

git commit -m "aegis api"

git push

Deploy on Railway

Connect your GitHub repo on railway.app and add environment variable.

# Environment Variable

API_KEY = your-secret-key

Generate Domain

In Railway → Settings → Domains → Generate Domain. Your API is live!

https://your-app.up.railway.app

# Done! 🚀

🐳 DOCKERFILE

FROM python:3.11-slim

# Install FFmpeg for audio extraction
RUN apt-get update && apt-get install -y ffmpeg && apt-get clean

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY api.py .

EXPOSE 8000
CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]
    