TikTok Media Downloader

Apify Actor that downloads video or audio from TikTok post URLs. Media is resolved via upstream services, downloaded through Apify Proxy, 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. Apify Proxy (datacenter) is enabled by default; switch to residential in the proxy editor if you see a rise in blocked/empty CDN responses.

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 (Apify Proxy is enabled by default).
3. Run the Actor and filter the dataset by status.

Pricing

This Actor uses Apify's Pay Per Event pricing:

Event	Price	When it's charged
Actor start	Apify's standard synthetic event price	Once per run start (covers the first few seconds of compute)
Media download	$15.00 per 1,000 ($0.015 each)	Once per successfully downloaded file — never for skipped or failed URLs

You only pay for files you actually receive; duplicate, unavailable, or failed URLs are reported in the dataset for free. Set ACTOR_MAX_TOTAL_CHARGE_USD (or the Console's max cost per run) to cap spend — the run stops gracefully once the limit is reached.

Best Practices

1. Proxies — Apify Proxy (datacenter) is used by default and is included for most requests; switch to residential in proxyConfiguration if you notice more blocked/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