1. Supported TikTok Video URL & ID Formats
You do not need to pre-resolve short links or strip query parameters before calling the API. The gateway normalizes all TikTok link formats automatically.
| Input Format | Example Value | Supported |
|---|---|---|
| Standard Desktop URL | https://www.tiktok.com/@tiktok/video/7231338487075638570 | Yes |
| Photo Mode Carousel URL | https://www.tiktok.com/@creator/photo/7349182736451928374 | Yes (returns data.images[]) |
| Mobile Short Share Link | https://vm.tiktok.com/ZM2abc123/ or https://vt.tiktok.com/ZS8xyz/ | Yes (auto-resolved) |
| Raw 64-Bit Video ID | 7231338487075638570 | Yes |
2. Code Examples: Get Video Metadata & Download 1080p MP4
Below are complete, copy-pasteable examples in cURL, Python, and TypeScript/Node.js that fetch a TikTok video's metadata and stream the 1080p unwatermarked MP4 file.
Get Video Detail & 1080p HD Stream (GET /v1/videos/detail)
Pass url and hd=1. Check payload.code === 0, then read data.hdplay (1080p) or data.play (720p fast CDN).
curl -sS "https://api.tiktokapi.io/v1/videos/detail?url=https://www.tiktok.com/@tiktok/video/7231338487075638570&hd=1" \
-H "x-api-key: tk_your_api_key_here"3. Video Response Schema & Field Reference
Every video object returned by /v1/videos/detail, /v1/videos/search, and /v1/users/videos includes the following normalized fields:
| Field Path | Type | Description |
|---|---|---|
| data.id | string | 64-bit TikTok video ID serialized as a string to prevent IEEE-754 precision loss. |
| data.title | string | Full video caption including hashtags (#fyp) and @mentions. |
| data.play | string (URL) | Direct CDN link to the 720p no-watermark MP4 video stream. |
| data.hdplay | string (URL) | Direct CDN link to the 1080p original HD no-watermark MP4 stream (when hd=1). |
| data.images | string[] | undefined | Present on Photo Mode carousel posts: array of full-resolution image slide URLs. |
| data.play_count | integer | Total video views / impressions. |
| data.digg_count | integer | Total like (heart) count. |
| data.comment_count | integer | Total comment count. |
| data.share_count | integer | Total share count. |
| data.collect_count | integer | Total bookmark / favorite count. |
| data.create_time | integer | Unix epoch timestamp (seconds) when the video was published. |
| data.author | object | Creator summary object (id, unique_id, nickname, avatar). |
| data.music_info | object | Sound track metadata including direct MP3 stream (music_info.play). |
Frequently Asked Questions
- How long do the returned CDN video URLs (data.play / data.hdplay) remain valid?
- TikTok CDN signed URLs typically include an x-expires parameter valid for 4 to 24 hours. If you are building an archive or AI training dataset, download the MP4 binary or audio stream to your own S3/R2 bucket rather than storing the temporary CDN URL indefinitely.
- How do I detect whether a TikTok URL is a video or a Photo Mode image carousel?
- Check Array.isArray(data.images) && data.images.length > 0. For photo carousels, data.images contains the unwatermarked slide images and data.play / data.music_info.play contains the background audio track.
- Am I charged if a user passes an invalid URL or a deleted/private TikTok video?
- Never. If a video is private, deleted, or malformed, the API returns code: -1 and x-credits-cost: 0.