Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KevxxAlva/tiktok-bot-downloader/llms.txt

Use this file to discover all available pages before exploring further.

TikTokSaver ships a lightweight Express server that exposes three REST endpoints. Every request is made with URL query parameters — there are no request bodies. Depending on the endpoint, responses are either a structured JSON object or raw binary data streamed directly to the browser.

​
Base URL

EnvironmentBase URL
Developmenthttp://localhost:3000
Production (Vercel)https://your-app.vercel.app
All endpoint paths are relative to the base URL. For example, the download endpoint in production is https://your-app.vercel.app/api/download.

​
Authentication

The API is fully public. No API keys, tokens, or authentication headers are required for any endpoint.

​
Endpoints

GET /api/download

Fetches video metadata from TikWM for a given TikTok URL and returns a DownloadResult JSON object containing video, audio, image, and author fields.

GET /api/proxy-download

Buffers a TikTok CDN media URL and streams it to the browser with Content-Disposition: attachment headers, enabling direct file downloads.

GET /api/proxy-image

Proxies TikTok CDN image URLs through the server, bypassing hotlink restrictions and shielding the end-user’s IP from TikTok’s CDN.

​
Request Format

All parameters are passed as URL query strings. No JSON body or multipart payload is ever sent to the API — only GET requests with query parameters. 
# Example: all parameters as query strings
GET /api/download?url=https%3A%2F%2Fvm.tiktok.com%2FZMe7...
GET /api/proxy-download?url=<encoded_cdn_url>&filename=video.mp4
GET /api/proxy-image?url=<encoded_image_url>

​
Response Format

EndpointResponse TypeDescription
GET /api/downloadapplication/jsonA DownloadResult JSON object
GET /api/proxy-downloadBinary (video/mp4, audio/mpeg, etc.)The raw media file
GET /api/proxy-imageBinary (image/jpeg, etc.)The raw image file

​
Error Handling

All endpoints return standard HTTP status codes. GET /api/download returns JSON error objects; the two proxy endpoints return plain-text error strings.
Status CodeMeaning
400 Bad RequestA required query parameter (url) is missing
404 Not FoundNo watermark-free video version was found
500 Internal Server ErrorTikWM returned an error, or an unexpected server-side failure occurred
504 Gateway TimeoutThe upstream CDN or TikWM did not respond within the allowed time
// Example JSON error body from GET /api/download
{
  "status": "error",
  "error": "Could not fetch video info from provider.",
  "details": "video not found"
}

​
CORS

CORS is enabled globally on the server using the cors middleware with default settings. Any origin can call any endpoint — no Origin header restrictions are applied. 
// api/index.js
app.use(cors());

​
TypeScript Interfaces

The following interfaces from client/src/types.ts describe the canonical shape of every successful response from GET /api/download. Use these as the source of truth when consuming the API in TypeScript projects. 
export interface DownloadOption {
  type: 'hd' | 'normal' | 'music' | 'watermark';
  label: string;
  url: string;
  size?: number | string;
}

export interface DownloadResult {
  result: {
    downloads: DownloadOption[];
    video: string[];
    images?: string[];
    music: string;
    cover: string;
    desc: string;
    author: {
      nickname: string;
      avatar: string;
    };
  };
}

​
Quick Start

The following curl command fetches metadata for a TikTok video. Replace the url value with any valid TikTok link. 
curl "http://localhost:3000/api/download?url=https%3A%2F%2Fvm.tiktok.com%2FZMe7abc123"
A successful response looks like: 
{
  "status": "success",
  "result": {
    "downloads": [
      {
        "type": "normal",
        "label": "Sin Marca",
        "url": "https://v19-webapp.tiktok.com/video/...",
        "size": 8234567
      },
      {
        "type": "watermark",
        "label": "Con Marca (HD)",
        "url": "https://v19-webapp.tiktok.com/video/...",
        "size": 9102345
      },
      {
        "type": "music",
        "label": "Audio MP3",
        "url": "https://sf16-ies-music.tiktokcdn.com/...",
        "size": null
      }
    ],
    "video": ["https://v19-webapp.tiktok.com/video/..."],
    "images": [],
    "music": "https://sf16-ies-music.tiktokcdn.com/...",
    "cover": "https://p16-sign.tiktokcdn-us.com/...",
    "desc": "My awesome TikTok #fyp",
    "author": {
      "nickname": "creator_handle",
      "avatar": "https://p16-sign.tiktokcdn-us.com/..."
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us