TikTok Video Downloader Actor

Resolve a TikTok video URL to a direct media link.

What you get

• The resolution you asked for, and the one you actually got. requestedHeight, resolvedHeight and heightWasDowngraded are all reported, so a 1080p request that came back 480p is visible rather than silent.
• Real metadata: title, uploader, upload date, duration, and the view, like and comment counts the site publishes.
• A per-URL result, so one bad link no longer ends the run.
• availableHeights, so you can see what else the source offers.
• Optional file storage: leave it off to get the direct source URL, which is much faster and cheaper; turn it on to keep a copy in the run's key-value store.
• Failed URLs are returned but never billed - see below.

Input

Field	Type	Required	What it does
video_urls	array	yes	The TikTok videos to process. Accepts plain URLs or objects with a "url" key.
desired_resolution	string	no	The height to aim for. If the source does not go that high, the tallest available is returned and heightWasDowngraded says so.
saveFilesToKeyValueStore	boolean	no	Download the media and keep it in the run's key-value store, returning a link. Leave off to get the direct source URL only, which is much faster and cheaper.
maxFileSizeMb	integer	no	A file larger than this is not stored, and the record says why. Only applies when saving to storage.
proxyConfiguration	object	no	The run rotates through a few IPs from this configuration when a site refuses one. TikTok refuses datacenter addresses outright, so a residential group matters here.

The silent-video problem

Measured on 2026-08-20: of the 53 formats YouTube offered for a test video, not one carried both picture and sound. Every stream is video-only or audio-only, and the site expects the player to combine them.

An Actor that hands back a single format URL therefore hands back a silent file. This one prefers a format that has sound where the site publishes one, and where none exists it says so - requiresAudioMerge: true - and returns audioDownloadUrl alongside downloadUrl so the two can be combined with ffmpeg or any equivalent tool.

TikTok and datacenter IPs

Measured on 2026-08-20: a direct request for a TikTok video returns "Your IP address is blocked from accessing this post". That is now reported as failureKind: "ip-blocked" with the advice to enable a residential proxy, and the run retries on a different exit node before giving up - rather than returning an unexplained error and charging you for it.

You are not charged for a URL that failed

Every previous version of this Actor pushed its error rows with charged_event_name="result" - the same paid event a successful result uses. A run over a hundred dead links cost exactly as much as a run over a hundred live ones.

Failures are still returned, because you need to know which URLs did not work, but they are not billed. Each one says what kind of failure it was and what to do about it:

failureKind	What it means
ip-blocked	The site refused this run's IP. Enable a residential proxy.
geo-blocked	Not available from that country. Set a proxy country.
login-required	Private, or the site wants a signed-in session.
removed	The media no longer exists at that URL.
no-media	A real page, but it carries no downloadable media.
age-restricted	Gated behind an age check.
unsupported	Not a URL this Actor can resolve.
network	A transient failure. Running it again may work.

ip-blocked, geo-blocked and network are retried on a different IP before being reported. A removed video is not - it will still be removed.

Proxy

The run rotates through a few IPs from your proxy configuration and moves to a new one when a site refuses the current one. TikTok in particular refuses datacenter addresses outright - measured, a direct request returns "Your IP address is blocked from accessing this post" - so a residential group is worth setting for it.

What it cannot do

• It does not sign in, so anything behind a login stays behind it.
• It resolves what the site publishes. A site that changes its delivery can break resolution until the underlying extractor catches up.
• Downloading media may be restricted by the source site's terms and by copyright. You are responsible for having the right to download and use what you fetch.