A collection of TikTok utilities and tools. Currently includes null-watermark video downloading, metadata extraction, and user post fetching. Built with Express.js, TypeScript, and yt-dlp.
Live API: https://tiktok-downloader-production-635b.up.railway.app
- Frontend: https://tiktok-downloader-production-635b.up.railway.app/web
- API Health: https://tiktok-downloader-production-635b.up.railway.app/health
|
|
|
- REST API - Simple GET endpoints for downloading TikTok videos
- No watermark - Downloads clean videos directly
- Streaming - Efficiently streams videos without saving to disk
- User posts - Get all videos from a TikTok user profile
- Range requests - Supports video seeking and partial content
- Video metadata - Get thumbnail, title, and uploader info
- Rate limiting - 5 requests per minute per IP
- Error handling - Graceful handling of invalid URLs, private videos, etc.
- Web interface - Optional minimal dark mode UI for easy testing (available at
/web) - Railway ready - Pre-configured for easy deployment
- Node.js 18+
- Python 3.x (for yt-dlp)
- yt-dlp installed globally:
pip install yt-dlp
- Clone the repository:
git clone <your-repo-url>
cd tt-toolk1t- Install dependencies:
npm install- Ensure yt-dlp is installed:
pip install yt-dlpnpm install
npm run build
npm startThe API will be available at http://localhost:3000
Run API server with hot reload:
npm run devFor frontend development (optional):
npm run dev:frontendGET /download?url=<tiktok_video_url>
Downloads a TikTok video without watermark. Streams the video directly to the client.
Query Parameters:
url(required) - The TikTok video URL
Example:
curl "http://localhost:3000/download?url=https://www.tiktok.com/@username/video/1234567890" --output video.mp4Response:
- Success: Video stream with headers:
Content-Type: video/mp4Content-Disposition: attachment; filename="tiktok-[id].mp4"Accept-Ranges: bytesContent-Length: <size>
- Error: JSON response with error details
Error Responses:
{
"error": "Missing URL parameter",
"message": "Please provide a TikTok video URL in the query parameter: ?url=<tiktok_url>"
}{
"error": "Invalid TikTok URL",
"message": "Please provide a valid TikTok video URL"
}{
"error": "Extraction failed",
"message": "Failed to extract video URL. The video might be private or unavailable."
}{
"error": "Rate limit exceeded",
"message": "Maximum 5 requests per minute allowed"
}GET /metadata?url=<tiktok_video_url>
Returns video information including thumbnail, title, uploader, and duration.
Example:
curl "http://localhost:3000/metadata?url=https://www.tiktok.com/@username/video/1234567890"Response:
{
"id": "1234567890",
"title": "Video Title",
"thumbnail": "https://...",
"duration": 30,
"uploader": "username"
}GET /user-posts?username=<username> or /user-posts?profile=<profile_url>
Returns a list of all public videos from a TikTok user profile.
Query Parameters:
username(optional) - TikTok username (without @)profile(optional) - Full TikTok profile URL
Example:
curl "http://localhost:3000/user-posts?username=example"
# or
curl "http://localhost:3000/user-posts?profile=https://www.tiktok.com/@example"Response:
{
"profile": "https://www.tiktok.com/@example",
"count": 10,
"posts": [
{
"id": "1234567890",
"url": "https://www.tiktok.com/@example/video/1234567890",
"title": "Video Title",
"thumbnail": "https://...",
"duration": 30,
"uploader": "example",
"view_count": 1000000,
"like_count": 50000
}
]
}GET /health
Returns API status.
Example:
curl http://localhost:3000/healthResponse:
{
"status": "ok",
"timestamp": "2024-01-01T00:00:00.000Z"
}- Limit: 5 requests per minute per IP address
- Window: 60 seconds
- Response: 429 Too Many Requests when exceeded
This project is pre-configured for Railway deployment using Docker:
- Push your code to GitHub
- Create a new project on Railway
- Connect your GitHub repository
- Railway will automatically detect the
Dockerfileand deploy
The Dockerfile ensures:
- Node.js 20 is installed
- Python 3, pip, and ffmpeg are available
- yt-dlp is installed via pip
- Frontend and backend are built in multi-stage build
- Production-ready optimized image
Getting your Railway URL:
- Go to your Railway project dashboard
- Click on your service
- Go to Settings → Networking
- Click Generate Domain to get your public URL
Live Deployment: https://tiktok-downloader-production-635b.up.railway.app
PORT- Server port (default: 3000)
tt-toolk1t/
├── src/
│ └── server.ts # Express API server
├── frontend/ # Optional web interface (convenience feature)
│ ├── app/ # Next.js app directory
│ └── components/ # React components
├── dist/ # Compiled backend JavaScript
├── dist-frontend/ # Static frontend build output
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── Dockerfile # Docker build configuration
├── docker-compose.yml # Local Docker testing
├── railway.json # Railway deployment config
└── README.md # This file
npm run build- Build both frontend and backendnpm run build:frontend- Build frontend onlynpm run build:backend- Build backend onlynpm start- Start production servernpm run dev- Start backend development server with hot reloadnpm run dev:frontend- Start frontend development servernpm run type-check- Type check without building
- URL Validation: Validates the provided TikTok URL format
- Video Extraction: Uses
yt-dlpto stream videos directly (no watermark) - Streaming: Streams video directly to the client without saving to disk
- Headers: Sets proper headers for video download and seeking support
- Error Handling: Returns JSON error responses for invalid requests
The API can be used independently from any client. The web interface at /web is provided as a convenience for testing and quick downloads.
- Videos are streamed directly without being saved to disk
- API can be used independently - the web interface is optional
- Range requests are supported for video seeking
- Rate limiting uses in-memory storage (resets on server restart)
- Web interface available at
/webfor convenience (built as static files)