# Download

Schemas

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.

- [GETTikTok Download API`/v1/tiktok/download`](https://socialtap.dev/docs/reference/tiktok/download/index.md)

## Schema

Every endpoint above returns this object as `data`. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, instagram, …). |
| `id` | `string` | Platform-native ID of the post (equals post.id). |
| `url` | `string` (uri) | Canonical URL of the post. |
| `type` | `string` | The post's content shape, as post.type. New values may be added; treat unknown values as other.<br>One of `video`, `image`, `carousel`, `audio` |
| `platform_type` | `string` or `null` | The platform's own product label, lowercase (reel, short, story, …), as post.platform_type. |
| `title` | `string` or `null` | Headline (Reddit title, Facebook video title); null on caption-only platforms. |
| `text` | `string` or `null` | Caption or body as plain text. |
| `author` | `object` | The posting account. |
| `author.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `author.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `author.display_name` | `string` or `null` | Display name shown on the profile. |
| `author.url` | `string` (uri) or `null` | Canonical profile URL. |
| `author.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `author.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `published_at` | `string` (date-time) or `null` | When the post went public, RFC 3339 UTC. |
| `duration_ms` | `integer` or `null` | Length of the post's primary video or audio in milliseconds; null for photo posts. |
| `thumbnail_url` | `string` (uri) or `null` | 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. |
| `files` | `object[]` | 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. |
| `files[].item_index` | `integer` or `null` | 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). |
| `files[].type` | `string` | Kind of file, as media\[\].type. New values may be added; treat unknown values as other.<br>One of `video`, `image`, `audio`, `gif` |
| `files[].url` | `string` (uri) or `null` | 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. |
| `files[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from its signature; null when unknown or it does not expire. |
| `files[].mime_type` | `string` or `null` | 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. |
| `files[].size_bytes` | `integer` or `null` | File size in bytes; an estimate from bitrate × duration is in approximate_fields. |
| `files[].width` | `integer` or `null` | Width in pixels (images and video). |
| `files[].height` | `integer` or `null` | Height in pixels (images and video). |
| `files[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio); null for images and when unknown. |
| `files[].bitrate_kbps` | `integer` or `null` | Average bitrate in kbit/s (video and audio), rounded; null when unknown. |
| `files[].frame_rate` | `number` or `null` | Frames per second (video and gif), to two decimals (an NTSC 30000/1001 is 29.97); null for images and audio and when unknown. |
| `files[].video_codec` | `string` or `null` | 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.<br>One of `h264`, `h265`, `vp9`, `av1` |
| `files[].audio_codec` | `string` or `null` | Audio codec of the file's sound; null when it has none. New values may be added; treat unknown values as other.<br>One of `aac`, `opus`, `mp3` |
| `files[].is_watermarked` | `boolean` or `null` | 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. |
| `files[].is_video_only` | `boolean` or `null` | 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. |
| `files[].thumbnail_url` | `string` (uri) or `null` | 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_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok download's own fields. |
| `platform_specific.tiktok.is_download_allowed` | `boolean` or `null` | 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_fields` | `string[]` | JSON paths of estimated or rounded values (a size from bitrate × duration, a duration in whole seconds). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, download endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The 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_unavailable` | 403 | No | The 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_media` | 404 | No | The 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. |

---

[HTML version](https://socialtap.dev/resources/download/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)