Facebook Video Downloader API

A production-ready REST API and web interface for downloading Facebook videos with audio support. Built with FastAPI, yt-dlp, and modern web technologies for reliable video extraction and processing.

Overview

This project provides a robust solution for downloading Facebook videos programmatically. The system handles Facebook's complex video streaming formats, including DASH streams that require audio and video merging, making it suitable for both developers and end-users.

Key Problem Solved

Facebook videos often use separate audio and video streams (DASH format), making direct downloads challenging. This API automatically detects and merges these streams using FFmpeg, ensuring downloaded videos include both audio and video components.

Features

Core Functionality

Video Download: Extract and download Facebook videos in multiple quality options
Audio Merging: Automatic handling of DASH streams with audio/video synchronization
Format Support: MP4 output with quality selection (360p, 720p, 1080p, best, worst)
URL Flexibility: Support for various Facebook URL formats including fb.watch short links

Technical Features

RESTful API: Clean HTTP API with comprehensive endpoint documentation
Rate Limiting: Built-in protection against abuse (10 requests per 60 seconds per IP)
Error Handling: Detailed error responses with actionable user guidance
Web Interface: Responsive frontend for non-technical users
Docker Support: Containerized deployment with all dependencies included

Quality Options

best: Highest available quality with audio
worst: Lowest quality for faster downloads
360p, 720p, 1080p: Specific resolution targets
Automatic fallback to best available quality if requested resolution unavailable

Live Demo

Web Interface: https://fdown.isuru.eu.org

API Documentation: https://fdown.isuru.eu.org/docs

GitHub Pages: https://sh13y.github.io/Facebook-Video-Download-API

Quick Test

curl -X POST "https://fdown.isuru.eu.org/info" \
     -H "Content-Type: application/json" \
     -d '{"url": "YOUR_FACEBOOK_VIDEO_URL"}'

Mobile Demo

Mobile interface demonstration: Paste Facebook video URL → Select quality → Download

Technical Architecture

Backend Stack

FastAPI: Modern Python web framework for API development
yt-dlp: Robust video extraction library with Facebook support
FFmpeg: Video processing for stream merging and format conversion
Pydantic: Data validation and serialization
aiohttp: Asynchronous HTTP client for URL resolution

Frontend Stack

Vanilla JavaScript: Lightweight, dependency-free frontend
Tailwind CSS: Utility-first CSS framework for responsive design
Responsive Design: Mobile-first approach supporting all screen sizes

Infrastructure

Docker: Containerization with multi-stage builds
Render: Production hosting with automatic deployments
GitHub Actions: CI/CD pipeline for documentation and testing

Installation

Prerequisites

Python 3.11 or higher
FFmpeg installed on system
Git for cloning the repository

Method 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/sh13y/Facebook-Video-Download-API.git
cd Facebook-Video-Download-API

# Build and run with Docker Compose
docker-compose up -d

# Access the application
# Web Interface: http://localhost:8000
# API Documentation: http://localhost:8000/docs

Method 2: Local Development

# Clone the repository
git clone https://github.com/sh13y/Facebook-Video-Download-API.git
cd Facebook-Video-Download-API

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

FFmpeg Installation

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

macOS:

brew install ffmpeg

Windows: Download from FFmpeg official website or use package managers like Chocolatey.

Usage

Web Interface

Navigate to the web interface at http://localhost:8000
Paste a Facebook video URL in the input field
Select desired video quality
Click "Download Video" to process and download

API Usage

Get Video Information

curl -X POST "http://localhost:8000/info" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://www.facebook.com/watch/?v=1234567890",
       "quality": "best"
     }'

Download Video

curl -X POST "http://localhost:8000/download" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://www.facebook.com/watch/?v=1234567890",
       "quality": "720p"
     }'

Supported URL Formats

The API accepts various Facebook URL formats:

https://www.facebook.com/watch/?v=1234567890
https://facebook.com/username/videos/1234567890
https://m.facebook.com/watch/?v=1234567890
https://fb.watch/ABC123/
https://www.facebook.com/reel/1234567890

Note: For fb.watch URLs, if processing fails, copy the full Facebook URL after the redirect for better reliability.

API Documentation

Endpoints

Method	Endpoint	Description
GET	`/`	Web interface
GET	`/health`	Health check
POST	`/info`	Get video information
POST	`/download`	Download video
GET	`/qualities`	List supported qualities
GET	`/stream/{video_id}`	Stream video file

Response Format

Success Response:

{
  "status": "success",
  "video_info": {
    "title": "Video Title",
    "duration": 120,
    "thumbnail": "https://example.com/thumb.jpg",
    "uploader": "Page Name",
    "view_count": 1000,
    "upload_date": "20240101"
  },
  "download_url": "https://example.com/video.mp4",
  "available_formats": [...]
}

Error Response:

{
  "status": "error",
  "message": "Invalid Facebook URL provided",
  "error_code": "INVALID_REQUEST"
}

Rate Limiting

Limit: 10 requests per 60 seconds per IP address
Headers: Rate limit information included in response headers
Behavior: Returns 429 status code when limit exceeded

Deployment

Production Deployment on Render

Fork this repository
Connect your GitHub account to Render
Create a new Web Service
Connect your forked repository
Render will automatically deploy using the included render.yaml

Environment Variables

# Optional: Set debug mode
DEBUG=false

# Optional: Custom port
PORT=8000

Docker Deployment

# Build the image
docker build -t facebook-video-downloader .

# Run the container
docker run -p 8000:8000 facebook-video-downloader

Project Evolution

This project evolved through several phases, each addressing specific technical challenges and user needs:

Phase 1: Core Functionality

Challenge: Basic video extraction without audio

Implemented yt-dlp integration for Facebook video extraction
Discovered Facebook's DASH stream architecture separating audio/video
Solution: Integrated FFmpeg for automatic stream merging

Phase 2: Web Interface Development

Challenge: Making the API accessible to non-technical users

Developed responsive web interface using Tailwind CSS
Implemented real-time feedback and error handling
Solution: Progressive enhancement with mobile-first design

Phase 3: URL Compatibility

Challenge: Supporting Facebook's diverse URL formats

Researched Facebook's URL structure variations
Implemented comprehensive regex patterns for URL validation
Solution: Built URL normalization system handling redirects

Phase 4: Production Readiness

Challenge: Deploying a reliable service for public use

Implemented rate limiting and error handling
Added comprehensive logging and monitoring
Solution: Containerized deployment with auto-scaling capabilities

Phase 5: Developer Experience

Challenge: Providing clear documentation and testing capabilities

Created comprehensive API documentation
Built interactive testing interface
Solution: Multi-format documentation with live examples

Current Status

Component	Status	Description
Core API	Production Ready	Stable video extraction with error handling
Web Interface	Production Ready	Responsive design supporting all devices
Documentation	Complete	API docs, deployment guides, troubleshooting
Deployment	Automated	Docker containers with CI/CD pipeline
Testing	Interactive	Live API testing through documentation

Contributing

Contributions are welcome! Please read our contributing guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Install development dependencies
pip install -r requirements.txt

# Run tests
python -m pytest

# Run with auto-reload for development
uvicorn app.main:app --reload

Code Style

Follow PEP 8 for Python code
Use type hints for all function parameters and return values
Write descriptive commit messages
Include tests for new features

License

This project is licensed under the WTFPL (Do What The F*** You Want To Public License) - see the LICENSE file for details.

Acknowledgments

yt-dlp: Robust video extraction library
FastAPI: Modern Python web framework
FFmpeg: Video processing capabilities
Tailwind CSS: Utility-first CSS framework

Built by sh13y

For questions, issues, or contributions, please visit the GitHub repository.

Install flyctl CLI

curl -L https://fly.io/install.sh | sh

Deploy

flyctl launch
flyctl deploy

Netlify (Serverless Functions)

# Using Netlify CLI
npm install -g netlify-cli
netlify login
netlify deploy --prod --dir=static --functions=netlify/functions

📖 How To Use This Magic

🖥️ Web Interface (For Humans)

"So simple, your grandma could use it!"

Visit http://localhost:8000 (or your live demo)
Paste that Facebook video URL you've been hoarding
Pick your quality (360p for data-savers, 1080p for perfectionists)
Click "Download Video"
Profit! 💰 (Well, more like... enjoy your video)

🤖 API Usage (For Developers)

"Because sometimes you need to download 1000 cat videos programmatically"

Download a Video

curl -X POST "http://localhost:8000/download" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.facebook.com/share/v/17GS54EKBN/",
    "quality": "best"
  }'

What You Get Back

{
  "status": "success",
  "video_info": {
    "title": "Cats Being Cats for 5 Minutes Straight",
    "duration": 300,
    "thumbnail": "https://beautiful-cat-thumbnail.jpg",
    "uploader": "CatLoversPro", 
    "view_count": 5000000
  },
  "download_url": "https://your-video-is-here.mp4",
  "available_formats": ["360p", "720p", "1080p"]
}

🎯 API Endpoints Reference

🌐 Method	🛤️ Endpoint	🎭 What It Does	😎 Cool Factor
GET	`/`	Web interface	⭐⭐⭐⭐⭐
POST	`/download`	Download video	⭐⭐⭐⭐⭐
POST	`/info`	Just the facts, ma'am	⭐⭐⭐⭐
GET	`/qualities`	Available quality options	⭐⭐⭐
GET	`/health`	"Are you alive?"	⭐⭐
GET	`/docs`	Interactive API playground	⭐⭐⭐⭐⭐

Pro tip: The /docs endpoint is where the real fun happens - interactive API testing! 🎮

⚙️ Configuration Wizardry

"Tweak it 'til it's perfect!"

Environment variables you can play with:

# Server Settings (The Basics)
HOST=0.0.0.0              # Listen everywhere
PORT=8000                 # Your favorite port
DEBUG=false               # Keep it cool in production

# Rate Limiting (Anti-Spam Shield)
RATE_LIMIT_REQUESTS=10    # 10 requests...
RATE_LIMIT_WINDOW=60      # ...per minute (be nice!)

# Download Settings (The Good Stuff)
DOWNLOAD_TIMEOUT=30       # 30 seconds to download or bust

🛠️ Supported Facebook URLs

"We speak all dialects of Facebook!"

✅ What Works:

https://www.facebook.com/user/videos/123456789/
https://www.facebook.com/share/v/abc123/
https://www.facebook.com/watch/?v=123456789
https://fb.watch/abc123/ (The short and sweet ones)

❌ What Doesn't Work:

Private videos (Sorry, no hacking here!)
Live streams (They're... still live)
Videos from pages you can't access (Facebook's rules, not ours)

🐛 When Things Go Wrong (Troubleshooting)

"Every developer's favorite section!" 😅

🔇 Problem: "My video has no sound!"

🎯 Solution: We already fixed this! Facebook's sneaky DASH streaming separates video and audio.

What We Did:

Before: Videos came out mute (like a sad mime)
After: Perfect video+audio harmony (like a beautiful symphony)
Magic: Our format selector automatically merges both streams

# The hero code that saved the day:
'format': 'best[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'

📵 Problem: "No video formats found"

🎯 Solution: Your yt-dlp needs a coffee break (aka update)

pip install --upgrade yt-dlp
# Sometimes YouTube changes their API, we adapt

🚫 Problem: "ffmpeg not found"

🎯 Solution: Install the video processing Swiss Army knife

# Ubuntu/Debian (The Penguins)
sudo apt install ffmpeg

# macOS (The Apple Way)
brew install ffmpeg

# Windows (The Scenic Route)
# Download from https://ffmpeg.org/download.html

🐌 Problem: "Downloads are slower than my internet in 2005"

🎯 Possible Causes:

Facebook's servers are having a bad day
Your internet is actually from 2005
The video is 4K and massive
Planetary alignment is off

🎯 Solutions:

Try a lower quality setting
Check your internet connection
Wait for Mercury to stop being in retrograde
Consider downloading smaller videos first

Windows - Download from https://ffmpeg.org/

🚨 Problem: Rate limit exceeded

🎯 Solution: Patience, young grasshopper! Wait 60 seconds and try again. Our rate limiter protects the server from overzealous downloading sprees

🔗 Problem: "Invalid Facebook URL"

🎯 Solution: Make sure you're using a direct video URL, not a post link

✅ Good: https://www.facebook.com/watch/?v=123456789
❌ Bad: https://www.facebook.com/user/posts/123456789

🔍 Debug Mode (For the Curious)

Want to see what's happening under the hood?

export DEBUG=true
python -m app.main
# Now you'll see ALL the things!

🏗️ Project Architecture

"How the sausage is made"

📁 Facebook-Video-Download-API/
├── 🐍 app/
│   ├── main.py              # The FastAPI magic happens here
│   ├── config.py            # All the boring settings
│   ├── models.py            # Data structures (Pydantic models)
│   ├── services/
│   │   └── video_service.py # The video downloading wizard
│   └── utils/
│       ├── rate_limiter.py  # The "calm down" enforcer
│       └── validators.py    # The URL quality checker
├── 🌐 static/
│   ├── index.html          # Pretty web interface
│   └── script.js           # Frontend JavaScript magic
├── 🐳 docker-compose.yml   # One-click deployment
├── 📦 Dockerfile          # Container recipe
└── 📋 requirements.txt     # Python shopping list

🚀 Deploy Your Own Instance

"Because sharing is caring, but having your own is cooler!"

🌟 Render (The Easy Button)

🍴 Fork this repository to your GitHub
🔗 Sign up at Render with GitHub
➕ Create a new Web Service → Connect your forked repo
⚙️ Configure these settings:
- Build Command: pip install -r requirements.txt
- Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
- Environment Variables:
  - DEBUG=false (Keep it professional)
  - PYTHON_VERSION=3.11.9 (The good stuff)
🚀 Deploy and be live in ~5 minutes!

Pro tip: Render's free tier is perfect for personal use and small projects!

🤝 Contributing

"All contributions welcome - from typo fixes to feature additions!"

🍴 Fork the repo
🌿 Branch it (git checkout -b feature/MyAwesomeFeature)
✨ Code your magic
💾 Commit with style (git commit -m 'Add some MyAwesomeFeature')
🚀 Push it (git push origin feature/MyAwesomeFeature)
🎯 PR it (Open a Pull Request)

Don't forget to add tests if you're feeling fancy! 🧪

📜 License

This project is licensed under WPFTL (WTFPL) - see the LICENSE file for details.

🎉 TL;DR: Do whatever you want with this code! Build it, break it, sell it, frame it - we don't mind!

🙏 Acknowledgments

"Standing on the shoulders of giants (and caffeinated developers)"

yt-dlp - The Swiss Army knife of video downloading ⚔️
FastAPI - The web framework that makes APIs fun again 🚀
Tailwind CSS - Making things pretty without the CSS nightmares 🎨
ffmpeg - The video processing wizard behind the curtain 🧙‍♂️
Coffee ☕ - The real MVP

📞 Support & Community

"Need help? We've got your back!"

🐛 Found a Bug? → GitHub Issues
💬 Want to Chat? → GitHub Discussions
📧 Direct Contact → GitHub Profile
📖 Read the Docs → Check out our documentation files above!

Response time: Usually faster than your pizza delivery! 🍕

🏆 Star History

"Our journey to GitHub stardom (one ⭐ at a time)"

🇱🇰 Made in Ceylon with ❤️ and Lots of Tea

Created by sh13y

If this project saved you from manually downloading videos one by one,
show some love with a ⭐ and maybe buy me a virtual tea! 🍵

Fun Fact: This entire project was built because downloading Facebook videos
shouldn't require a PhD in Computer Science! 🎓

README update to trigger workflow

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
app		app
assets		assets
netlify/functions		netlify/functions
static		static
.gitignore		.gitignore
=3.8.0		=3.8.0
API_DOCS.md		API_DOCS.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
NETLIFY_DEPLOYMENT.md		NETLIFY_DEPLOYMENT.md
PROBLEMS_AND_SOLUTIONS.md		PROBLEMS_AND_SOLUTIONS.md
Procfile		Procfile
README.md		README.md
RENDER_DEPLOYMENT.md		RENDER_DEPLOYMENT.md
docker-compose.yml		docker-compose.yml
netlify.toml		netlify.toml
railway.toml		railway.toml
render.yaml		render.yaml
requirements.txt		requirements.txt
runtime.txt		runtime.txt
test_render_deployment.sh		test_render_deployment.sh

License

sh13y/Facebook-Video-Download-API

Folders and files

Latest commit

History

Repository files navigation

Facebook Video Downloader API

Table of Contents

Overview

Key Problem Solved

Features

Core Functionality

Technical Features

Quality Options

Live Demo

Quick Test

Mobile Demo

Technical Architecture

Backend Stack

Frontend Stack

Infrastructure

Installation

Prerequisites

Method 1: Docker (Recommended)

Method 2: Local Development

FFmpeg Installation

Usage

Web Interface

API Usage

Get Video Information

Download Video

Supported URL Formats

API Documentation

Endpoints

Response Format

Rate Limiting

Deployment

Production Deployment on Render

Environment Variables

Docker Deployment

Project Evolution

Phase 1: Core Functionality

Phase 2: Web Interface Development

Phase 3: URL Compatibility

Phase 4: Production Readiness

Phase 5: Developer Experience

Current Status

Contributing

Development Setup

Code Style

License

Acknowledgments

Install flyctl CLI

Deploy

Netlify (Serverless Functions)

📖 How To Use This Magic

🖥️ Web Interface (For Humans)

🤖 API Usage (For Developers)

Download a Video

What You Get Back

🎯 API Endpoints Reference

⚙️ Configuration Wizardry

🛠️ Supported Facebook URLs

🐛 When Things Go Wrong (Troubleshooting)

🔇 Problem: "My video has no sound!"

📵 Problem: "No video formats found"

🚫 Problem: "ffmpeg not found"

🐌 Problem: "Downloads are slower than my internet in 2005"

Windows - Download from https://ffmpeg.org/

🚨 Problem: Rate limit exceeded

🔗 Problem: "Invalid Facebook URL"

🔍 Debug Mode (For the Curious)

🏗️ Project Architecture

🚀 Deploy Your Own Instance

🌟 Render (The Easy Button)

🤝 Contributing

📜 License

🙏 Acknowledgments

📞 Support & Community

🏆 Star History

Packages