ClipVault

English | 简体中文

A minimal multi-platform media download API supporting YouTube, Bilibili, TikTok, Douyin, and more.

Features

• 🚀 Simple REST API for video downloads
• 🌐 Multi-platform support (YouTube, Bilibili, TikTok, Douyin, etc.)
• 🔌 Plugin architecture for easy extension
• 📦 Auto-installation of dependencies
• ⚡ Synchronous file streaming (no polling needed)

Compliance Notice

IMPORTANT: This is a technical tool. Users are responsible for ensuring they have proper authorization to download content. Only use this API for:

• Content you own or created
• Content you have explicit permission to download
• Educational and research purposes in compliance with local laws
• Backup of your own uploaded content

Respect platform Terms of Service and copyright laws. Unauthorized downloading may violate platform policies and local regulations.

Quick Start

Installation

# Clone the repository
git clone https://github.com/chicogong/clipvault.git
cd clipvault

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m clipvault.main

The API will be available at http://localhost:8000

Dependencies

ClipVault will automatically install:

• yt-dlp: For YouTube, TikTok, Douyin, and other platforms
• BBDown: For Bilibili (downloaded from GitHub releases)

API Usage

Health Check

curl http://localhost:8000/health

Response:

{
  "status": "ok",
  "dependencies": {
    "yt-dlp": "installed",
    "BBDown": "installed"
  }
}

Download Video

curl -X POST http://localhost:8000/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}' \
  --output video.mp4

Or using Python:

import requests

response = requests.post(
    "http://localhost:8000/download",
    json={"url": "https://www.bilibili.com/video/BV1xx411c7mD"}
)

with open("video.mp4", "wb") as f:
    f.write(response.content)

Interactive API Documentation

Visit http://localhost:8000/docs for interactive Swagger UI documentation.

Supported Platforms

• ✅ YouTube (youtube.com, youtu.be)
• ✅ Bilibili (bilibili.com, b23.tv)
• ✅ TikTok (tiktok.com)
• ✅ Douyin (douyin.com)
• ✅ Twitter/X (twitter.com, x.com)
• ✅ Instagram (instagram.com)
• ✅ And many more via yt-dlp

Configuration

Create a .env file in the project root:

CLIPVAULT_HOST=0.0.0.0
CLIPVAULT_PORT=8000
CLIPVAULT_TEMP_DIR=/tmp/clipvault
CLIPVAULT_MAX_FILE_SIZE=2147483648
CLIPVAULT_REQUEST_TIMEOUT=3600

Architecture

clipvault/
├── api/
│   └── routes.py          # FastAPI endpoints
├── downloaders/
│   ├── base.py            # Downloader interface
│   ├── ytdlp.py           # yt-dlp adapter
│   └── bbdown.py          # BBDown adapter
├── core/
│   ├── dependency.py      # Dependency management
│   └── utils.py           # Utilities
├── config.py              # Configuration
├── exceptions.py          # Custom exceptions
└── main.py                # Application entry point

Development

Running Tests

pytest tests/

Adding a New Platform

1. Create a new downloader in clipvault/downloaders/:

from .base import BaseDownloader

class MyDownloader(BaseDownloader):
    async def can_handle(self, url: str) -> bool:
        return "myplatform.com" in url

    async def download(self, url: str, output_dir: Path) -> Path:
        # Implementation
        pass

2. Register it in clipvault/api/routes.py:

downloaders = [
    MyDownloader(),
    BBDownDownloader(),
    YtDlpDownloader(),
]

License

MIT License - See LICENSE file for details

Disclaimer

This tool is provided for educational and research purposes. The developers are not responsible for misuse or any legal consequences arising from the use of this software. Users must comply with all applicable laws and platform Terms of Service.