GET /api/download — Fetch TikTok Video Metadata

GET /api/download is the primary entry point for all TikTokSaver operations. It accepts a TikTok video URL, forwards it to the TikWM third-party API with HD quality requested, normalizes the response into a stable DownloadResult shape, and returns it as JSON. The returned CDN URLs are then passed to /api/proxy-download or /api/proxy-image for delivery to the browser.

Endpoint

GET /api/download?url=<encoded_tiktok_url>

Parameters

url

string

required

The TikTok video URL to fetch, URL-encoded. The following URL formats are all supported:

https://vm.tiktok.com/ZMe7abc123 — short share link
https://www.tiktok.com/@username/video/7123456789012345678 — full canonical URL
https://m.tiktok.com/v/7123456789012345678.html — mobile URL

Pass the raw TikTok URL through encodeURIComponent() (JavaScript) or urllib.parse.quote() (Python) before appending it to the query string.

Upstream Behavior

The handler constructs a multipart/form-data POST request to https://www.tikwm.com/api/ with two fields: url (the TikTok URL) and hd set to 1 (requests HD quality). The TikWM response is then normalized:

For standard videos, up to two DownloadOption entries are produced: one normal (watermark-free, H.264 play field) and one watermark (wmplay field).
For slideshows (when TikWM returns an images array), video download options are skipped entirely because TikWM’s slideshow video render is unreliable. Only the music option is added alongside the images array.
A music option is always appended when data.music is present.

Success Response

HTTP 200 — returns a DownloadResult JSON object.

status

string

Always "success" on a 200 response.

result

object

The normalized video metadata object.

Show result fields

result.downloads

DownloadOption[]

Array of available download options. Each element describes one downloadable file. See the DownloadOption section below for the full field list.

result.video

string[]

Array containing the URL of the first available download option (i.e., downloads[0].url). Provided as a convenience shortcut. Empty array [] when no video downloads are available (e.g., slideshow posts).

result.images

string[]

Array of direct CDN image URLs for slideshow posts. Empty array [] for standard video posts. Each URL should be proxied through /api/proxy-image before use in an <img> tag.

result.music

string

Direct CDN URL for the video’s background audio track. Pass this URL to /api/proxy-download with a .mp3 filename to download it.

result.cover

string

Thumbnail image URL for the video. Pass this URL to /api/proxy-image before using it in an <img> tag.

result.desc

string

The video’s title or description text as returned by TikWM (mapped from TikWM’s title field).

result.author

object

Information about the video’s creator.

Show author fields

result.author.nickname

string

The creator’s display name on TikTok.

result.author.avatar

string

CDN URL of the creator’s profile picture.

DownloadOption Object

Each element of result.downloads conforms to the DownloadOption interface.

type

'hd' | 'normal' | 'music' | 'watermark'

Identifies the kind of media file:

normal — watermark-free video (H.264, from TikWM’s play field)
watermark — watermarked HD video (from TikWM’s wmplay field)
music — audio-only MP3 track
hd — reserved for future high-definition video variants

label

string

Human-readable label shown in the UI. Current values produced by the server:

"Sin Marca" — watermark-free video download
"Con Marca (HD)" — watermarked HD video download
"Audio MP3" — audio track download

url

string

Direct TikTok CDN URL for the media file. Do not link this URL directly in browser <a> tags or <video src> — pass it through /api/proxy-download instead for reliable delivery.

size

number | null

File size in bytes, sourced from TikWM’s size, hd_size, or wm_size fields depending on the download type. null for music type options, as TikWM does not return a size for audio tracks.

Error Responses

400 Bad Request

JSON

Returned when the url query parameter is missing.

{ "status": "error", "error": "URL is required" }

404 Not Found

JSON

Returned when TikWM returns data but no watermark-free video option could be constructed and no images were found. This can happen for private or region-locked videos.

{
  "status": "error",
  "error": "Could not find a watermark-free version. The video might be private or region-locked."
}

500 Internal Server Error

JSON

Returned when TikWM responds with a non-zero code, when its response cannot be parsed, or when an unexpected runtime error occurs.

{
  "status": "error",
  "error": "Could not fetch video info from provider.",
  "details": "video not found"
}

Examples

curl "http://localhost:3000/api/download?url=https%3A%2F%2Fvm.tiktok.com%2FZMe7abc123"

Example success response (standard video):

{
  "status": "success",
  "result": {
    "downloads": [
      {
        "type": "normal",
        "label": "Sin Marca",
        "url": "https://v19-webapp.tiktok.com/video/tos/...",
        "size": 8234567
      },
      {
        "type": "watermark",
        "label": "Con Marca (HD)",
        "url": "https://v19-webapp.tiktok.com/video/tos/...",
        "size": 9102345
      },
      {
        "type": "music",
        "label": "Audio MP3",
        "url": "https://sf16-ies-music.tiktokcdn.com/obj/...",
        "size": null
      }
    ],
    "video": ["https://v19-webapp.tiktok.com/video/tos/..."],
    "images": [],
    "music": "https://sf16-ies-music.tiktokcdn.com/obj/...",
    "cover": "https://p16-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/...",
    "desc": "My TikTok video #fyp #trending",
    "author": {
      "nickname": "creator_handle",
      "avatar": "https://p16-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/..."
    }
  }
}

The CDN URLs inside result.downloads[].url, result.music, result.cover, and result.images are raw TikTok CDN links. Embedding them directly in <a href>, <video src>, or <img src> tags will often result in 403 errors or CORS failures. Always route them through /api/proxy-download (for file downloads) or /api/proxy-image (for image display) for reliable delivery.

Endpoints

GET /api/download — Fetch TikTok Video Metadata

Endpoint

Parameters

Upstream Behavior

Success Response

DownloadOption Object

Error Responses

Examples

Build docs developers (and LLMs) love

Endpoints

Documentation Index

​Endpoint

​Parameters

​Upstream Behavior

​Success Response

​DownloadOption Object

​Error Responses

​Examples

Build docs developers (and LLMs) love

Endpoint

Parameters

Upstream Behavior

Success Response

DownloadOption Object

Error Responses

Examples