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.

GET /api/proxy-download acts as a server-side relay between the browser and TikTok’s CDN. It fetches the media file on the server, buffers it entirely, and then sends it to the client with a Content-Disposition: attachment header — which causes the browser to save the file rather than open it. This endpoint is used for every file download in the TikTokSaver frontend, including videos, watermarked variants, audio tracks, and slideshow images.

​
Endpoint

GET /api/proxy-download?url=<encoded_media_url>&filename=<desired_filename>

​
Why a Proxy Is Needed

TikTok CDN URLs frequently reject direct browser fetch() or <a href> requests. Specifically:
  • TikTok’s CDN checks the Referer header and may return 403 Forbidden if the request does not appear to originate from TikTok’s own pages.
  • Browsers cannot set arbitrary User-Agent or Referer headers on <a href> downloads due to CORS and security restrictions.
  • CDN links returned by TikWM often do not include proper Content-Disposition headers, so browsers open them in a new tab rather than prompting a save dialog.
By routing all downloads through this server endpoint, TikTokSaver solves all three problems: the server controls headers, buffers the full file, and attaches the correct Content-Disposition header before forwarding the binary to the client.

​
Parameters

​
url
string
required
The media URL to proxy. This is typically the url field from a DownloadOption object returned by GET /api/download, a result.music audio URL, or an individual image URL from result.images. The value must be URL-encoded.
​
filename
string
The desired filename for the downloaded file. Defaults to tiktok_video.mp4 if omitted. All characters outside [a-zA-Z0-9._-] are replaced with _ to prevent HTTP header injection from special characters or emoji. The extension may be automatically corrected based on the upstream Content-Type (see Behavior below).

​
Behavior

The endpoint performs the following steps on every request:
  1. First fetch attempt — sends a GET request to the upstream url with:
    • User-Agent: Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36
    • Referer: https://www.tiktok.com/
    • Range: bytes=0-
  2. 403 retry — if the upstream server returns 403 Forbidden, the request is immediately retried with the same User-Agent but without the Referer header.
  3. Buffer — the full response body is loaded into memory as an ArrayBuffer before any response headers are sent to the client. This ensures Content-Length can be set accurately.
  4. Smart extension correction — the final filename is adjusted based on the upstream Content-Type:
    • If Content-Type contains audio and the filename ends in .mp4, the extension is changed to .mp3.
    • If Content-Type contains image and the filename ends in .mp4, the extension is changed to .jpeg.
  5. Response headers sent to the client:
    • Content-Disposition: attachment; filename="<finalFilename>"
    • Content-Type: <upstream Content-Type> (falls back to application/octet-stream)
    • Content-Length: <buffer byte length>

​
Success Response

HTTP 200 — binary file data with the following headers:
HeaderValue
Content-Dispositionattachment; filename="<finalFilename>"
Content-TypeMirrored from upstream (e.g. video/mp4, audio/mpeg, image/jpeg)
Content-LengthExact byte size of the buffered file

​
Error Responses

​
400 Bad Request
plain text
Returned when the url query parameter is missing.
URL required
​
500 Internal Server Error
plain text
Returned when the upstream fetch fails (non-OK status after the optional 403 retry) or when an unexpected runtime error occurs.
Error downloading file: Failed to fetch video: Not Found

​
Examples

# Download a watermark-free MP4
curl -OJ "http://localhost:3000/api/proxy-download?url=https%3A%2F%2Fv19-webapp.tiktok.com%2Fvideo%2F...&filename=tiktok_creator_normal.mp4"

# Download an audio track
curl -OJ "http://localhost:3000/api/proxy-download?url=https%3A%2F%2Fsf16-ies-music.tiktokcdn.com%2Fobj%2F...&filename=tiktok_creator_music.mp3"
Assigning a proxy URL directly to window.location.href is the simplest way to trigger a browser Save As dialog. Because the endpoint responds with Content-Disposition: attachment, the browser will immediately prompt the user to save the file without navigating away from the current page.

Build docs developers (and LLMs) love

Get started for freeTalk to us