StatusSupportGet API keyDashboard
SchemasDownloads

Schemas

Download

Use with AI

Direct download links for public video and photo posts, watermark-free first, with format, size, resolution and when each link expires.

Endpoints

1 endpoint returns downloads on TikTok.

Schema

Every endpoint above returns this object as data. The standard meta comes with every response.

platformstring

Platform ID (tiktok, instagram, …).

idstring

Platform-native ID of the post (equals post.id).

urlstring uri

Canonical URL of the post.

typestring

The post's content shape, as post.type. New values may be added; treat unknown values as other.

One ofvideoimagecarouselaudio

platform_typestringnullable

The platform's own product label, lowercase (reel, short, story, …), as post.platform_type.

titlestringnullable

Headline (Reddit title, Facebook video title); null on caption-only platforms.

textstringnullable

Caption or body as plain text.

authorobject

The posting account.

ShowHide 6 child fields
idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

published_atstring date-timenullable

When the post went public, RFC 3339 UTC.

duration_msintegernullable

Length of the post's primary video or audio in milliseconds; null for photo posts.

thumbnail_urlstring urinullable

Largest cover or poster image URL of the post (the first attachment's; each file's own is files[].thumbnail_url); CDN links can expire within hours.

filesobject[]

The post's files by item_index, the sound last; each item's best first (a url, the item's own kind before its separate audio, no watermark, with sound, not a manifest, then resolution). At least one has a url.

ShowHide 16 child fields
item_indexintegernullable

0-based position of the file's attachment in display order (post.media[item_index]); null for the post's sound (a slideshow's soundtrack).

typestring

Kind of file, as media[].type. New values may be added; treat unknown values as other.

One ofvideoimageaudiogif

urlstring urinullable

Direct CDN file URL, fetchable without cookies or headers; null when the platform serves it only with its cookie or to the IP that asked.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from its signature; null when unknown or it does not expire.

mime_typestringnullable

IANA media type without parameters (video/mp4, image/jpeg, audio/mp4); application/vnd.apple.mpegurl (HLS) or application/dash+xml (DASH) for a streaming manifest.

size_bytesintegernullable

File size in bytes; an estimate from bitrate × duration is in approximate_fields.

widthintegernullable

Width in pixels (images and video).

heightintegernullable

Height in pixels (images and video).

duration_msintegernullable

Duration in milliseconds (video and audio); null for images and when unknown.

bitrate_kbpsintegernullable

Average bitrate in kbit/s (video and audio), rounded; null when unknown.

frame_ratenumbernullable

Frames per second (video and gif), to two decimals (an NTSC 30000/1001 is 29.97); null for images and audio and when unknown.

video_codecstringnullable

Video codec (h264 plays everywhere; h265, vp9 and av1 need newer players); null for images and audio. New values may be added; treat unknown values as other.

One ofh264h265vp9av1

audio_codecstringnullable

Audio codec of the file's sound; null when it has none. New values may be added; treat unknown values as other.

One ofaacopusmp3

is_watermarkedbooleannullable

The platform's logo or the author's handle is burned into the picture (TikTok's download file); false: the clean original. Null for audio.

is_video_onlybooleannullable

True: video without its sound, which is the audio file of the same item_index. False: it plays with its sound, or has none. Null for images and audio.

thumbnail_urlstring urinullable

Cover image of this file's attachment (post.media[item_index].thumbnail_url), built like url; null for images and audio and when unknown.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

ShowHide 1 child field
tiktokobjectnullable

A TikTok download's own fields.

ShowHide 1 child field
is_download_allowedbooleannullable

The creator lets viewers save the post in TikTok's app; false: saving is turned off (the files stay public). Null when TikTok does not say.

approximate_fieldsstring[]

JSON paths of estimated or rounded values (a size from bitrate × duration, a duration in whole seconds). [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, download endpoints return:

CodeHTTPRetryMeaningWhat to do
not_found404NoThe item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).Check the link or ID. Do not retry.
private_or_unavailable403NoThe item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.Only public items can be fetched. Do not retry.
no_media404NoThe post exists but has no file to download: a text or link post, or one whose media the platform does not serve logged out.Do not retry. Fetch the post itself for its text and links.

Last updated