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-image fetches an image from a TikTok CDN URL on the server and forwards the binary to the browser with appropriate caching headers. The TikTokSaver frontend routes every image through this endpoint — including video cover thumbnails and all slideshow frames — so that images load reliably inside the application without being blocked by TikTok’s hotlink protections.

​
Endpoint

GET /api/proxy-image?url=<encoded_image_url>

​
Why It Exists

TikTok’s CDN applies two restrictions that make it impractical to use raw CDN image URLs directly in browser <img> tags hosted on a third-party domain:
  1. Hotlink blocking — TikTok’s CDN may check the Origin or Referer header and refuse requests that do not originate from a TikTok page, resulting in broken images.
  2. IP exposure — when the browser fetches a CDN URL directly, TikTok’s CDN logs the end-user’s IP address. Routing the request through the server prevents this, so only the server’s IP is visible to TikTok.
By proxying every image through this endpoint, TikTokSaver sidesteps both issues and delivers images reliably regardless of the user’s network or browser configuration.

​
Parameters

​
url
string
required
The image URL to proxy, URL-encoded. Typical sources:
  • result.cover from a DownloadResult object — the video thumbnail
  • An element of result.images[] from a DownloadResult object — a slideshow frame
  • result.author.avatar — the creator’s profile picture

​
Behavior

The endpoint performs the following steps on every request:
  1. Timeout guard — an AbortController is created with a 10-second timeout. If the upstream server does not respond within 10 seconds, the request is aborted and a 504 is returned.
  2. Upstream fetch — a plain GET request is made to the provided url with no additional headers.
  3. Content-Type forwarding — the Content-Type header from the upstream response is forwarded directly to the client. If the upstream does not provide a Content-Type, it defaults to image/jpeg.
  4. Cache-Control — a Cache-Control: public, max-age=31536000 header is set, allowing browsers and CDN edges to cache the proxied image for up to one year.
  5. Binary passthrough — the full response body is read into a Buffer and sent to the client in one call.

​
Success Response

HTTP 200 — raw image binary with the following headers:
HeaderValue
Content-TypeForwarded from upstream; defaults to image/jpeg
Cache-Controlpublic, max-age=31536000

​
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 returns a non-OK status or when an unexpected runtime error occurs.
Error
​
504 Gateway Timeout
plain text
Returned when the upstream CDN does not respond within the 10-second AbortController deadline.
Timeout

​
Frontend Usage

The TikTokSaver frontend constructs proxy image URLs inline inside <img src> attributes. The following patterns are taken directly from client/src/components/VideoResult.tsx: 
// Video cover thumbnail (standard video post)
<img
  src={`/api/proxy-image?url=${encodeURIComponent(data.result.cover)}`}
  alt="Cover"
/>

// Individual slideshow frame (carousel / photo post)
{data.result.images!.map((img, idx) => (
  <img
    src={`/api/proxy-image?url=${encodeURIComponent(img)}`}
    alt={`Slide ${idx + 1}`}
  />
))}

​
Example

curl -o cover.jpg \
  "http://localhost:3000/api/proxy-image?url=https%3A%2F%2Fp16-sign.tiktokcdn-us.com%2Ftos-useast5-p-0068-tx%2F..."
This endpoint does not validate or restrict the url parameter beyond checking that it is present. It will attempt to proxy any HTTP or HTTPS image URL it receives. In a production environment, consider adding an allowlist of trusted CDN hostnames (e.g. *.tiktokcdn.com, *.tiktokcdn-us.com) to prevent the endpoint from being abused as an open image proxy.

Build docs developers (and LLMs) love

Get started for freeTalk to us