TikTok Media Downloader

Apify Actor that downloads video or audio from TikTok post URLs. Media is resolved via upstream services, downloaded through residential-friendly proxies, and stored in the default key-value store with a per-URL dataset report.

Features

• Download TikTok videos in the highest available quality
• Optional watermark-free video only (noWatermarkOnly)
• Audio-only or video-only download modes
• Automatic fallback when the primary source cannot satisfy the request
• Proxy rotation on stalled or slow downloads
• In-run deduplication for duplicate input URLs
• Per-URL dataset rows for downloaded, skipped, and failed outcomes

Input Parameters

Required

• startUrls (array) — TikTok post URLs to process.

  [
    { "url": "https://www.tiktok.com/@mysticwild/video/7435475440392850721" }
  ]
  

• downloadType (string) — What to download:

  • "video" — video only (default)
  • "audio" — audio only
  • "videoOrAudio" — video when available, otherwise audio

• proxyConfiguration (object) — Proxy settings. Residential proxies are strongly recommended; datacenter IPs are often blocked by the download CDN.

Optional

Field	Type	Default	Description
noWatermarkOnly	boolean	false	Skip posts that have no watermark-free video
downloadTimeoutSecs	integer	500	Per-request CDN download timeout
stallTimeoutSecs	integer	30	Abort and retry if no bytes arrive for this long
slowDownloadTimeoutSecs	integer	120	Abort and retry if the whole download exceeds this; 0 disables
maxRequestRetries	integer	25	Crawlee retry count per URL
maxConcurrency	integer	5	Parallel downloads (1–15)
verboseProgress	boolean	false	Log per-chunk download progress

Output

Every input URL produces one dataset row.

Downloaded

{
  "sourceUrl": "https://www.tiktok.com/@mysticwild/video/7435475440392850721",
  "status": "downloaded",
  "statusNote": null,
  "quality": "HD Original",
  "type": "MP4",
  "timestamp": "2025-03-16T01:08:56.082Z",
  "filename": "a076ba86-10e4-476b-b17e-b63caf0071b3.mp4",
  "fileUrl": "https://api.apify.com/v2/key-value-stores/[store-id]/records/[filename]",
  "fileSize": 9876543,
  "fileSizeFormatted": "9.4 MB",
  "fileType": "video"
}

• status — downloaded, skipped, or failed
• statusNote — reason when skipped or failed; null on success
• fileType — video or audio
• fileSize — exact size in bytes
• fileSizeFormatted — human-readable size for display (e.g. 9.4 MB)
• filename / fileUrl — present only when status is downloaded

Skipped or failed

{
  "sourceUrl": "https://www.tiktok.com/@mysticwild/video/7435475440392850721",
  "status": "skipped",
  "statusNote": "no watermark-free video available (all sources tried)",
  "timestamp": "2025-03-16T01:08:56.082Z"
}

Media files live in the default key-value store and are linked from fileUrl.

Usage

1. Create a task on Apify and add TikTok post URLs to startUrls.
2. Set downloadType and proxyConfiguration (residential recommended).
3. Run the Actor and filter the dataset by status.

Best Practices

1. Proxies — Use Apify residential proxy; datacenter IPs frequently get empty CDN responses.
2. Download type — Default video is appropriate for most runs; use audio or videoOrAudio when needed.
3. Concurrency — Keep maxConcurrency moderate (default 5); each download buffers the full file in memory.
4. Timeouts — Raise downloadTimeoutSecs for large files; tune stallTimeoutSecs / slowDownloadTimeoutSecs if proxies are slow.
5. URLs — Use direct TikTok post links (tiktok.com, vm.tiktok.com, vt.tiktok.com).

Development

npm install
npm test
npm run start:dev

Live integration tests (network required):

$RUN_LIVE_TESTS=1 npm run test:live

Resources

• Apify SDK Documentation
• Crawlee Documentation
• Apify Platform Documentation
• Apify Proxy Documentation