0
# TikTok API
1

2
Core functionality for extracting video metadata, download URLs, and content from TikTok URLs. Supports both video posts and image carousels with comprehensive metadata extraction including author information, music details, and hashtags.
3

4
## Capabilities
5

6
### TikTok Download Function
7

8
Main function for downloading TikTok video or image data from URLs.
9

10
```javascript { .api }
11
/**
12
 * Download TikTok video or image data from a URL
13
 * @param url - TikTok video URL (supports vm.tiktok.com, vt.tiktok.com, www.tiktok.com)
14
 * @returns Promise resolving to TiktokResult with video/image data or error
15
 */
16
function TiktokDL(url: string): Promise<TiktokResult>;
17

18
interface TiktokResult {
19
  status: 'success' | 'error';
20
  message?: string;
21
  result?: VideoResult | ImageResult;
22
}
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import { TiktokDL } from './lib/ttapi.js';
29

30
// Download video data
31
const videoResult = await TiktokDL('https://vm.tiktok.com/ZSFxxxxxx/');
32
if (videoResult.status === 'success') {
33
  console.log('Video ID:', videoResult.result.id);
34
  console.log('Description:', videoResult.result.description);
35
  console.log('Video URLs:', videoResult.result.video);
36
}
37

38
// Handle image posts
39
const imageResult = await TiktokDL('https://www.tiktok.com/@user/photo/123');
40
if (imageResult.status === 'success' && imageResult.result.type === 'image') {
41
  console.log('Images:', imageResult.result.images);
42
}
43

44
// Error handling
45
const errorResult = await TiktokDL('invalid-url');
46
if (errorResult.status === 'error') {
47
  console.log('Error:', errorResult.message);
48
}
49
```
50

51
### Video Result Type
52

53
Data structure returned for TikTok video posts.
54

55
```javascript { .api }
56
interface VideoResult {
57
  /** Content type identifier */
58
  type: 'video';
59
  /** Unique TikTok video ID */
60
  id: string;
61
  /** Video creation timestamp */
62
  createTime: number;
63
  /** Video description/caption */
64
  description: string;
65
  /** Array of hashtags used in the video */
66
  hashtag: string[];
67
  /** Video duration in MM:SS format */
68
  duration: string;
69
  /** Author/creator information */
70
  author: AuthorInfo;
71
  /** Array of video download URLs from TikTok's play_addr.url_list */
72
  video: string[];
73
  /** Array of video cover image URLs from cover.url_list */
74
  cover: string[];
75
  /** Array of dynamic cover image URLs from dynamic_cover.url_list */
76
  dynamicCover: string[];
77
  /** Array of original cover image URLs from origin_cover.url_list */
78
  originCover: string[];
79
  /** Background music information */
80
  music: MusicInfo;
81
}
82
```
83

84
### Image Result Type
85

86
Data structure returned for TikTok image carousel posts.
87

88
```javascript { .api }
89
interface ImageResult {
90
  /** Content type identifier */
91
  type: 'image';
92
  /** Unique TikTok post ID */
93
  id: string;
94
  /** Post creation timestamp */
95
  createTime: number;
96
  /** Post description/caption */
97
  description: string;
98
  /** Array of hashtags used in the post */
99
  hashtag: string[];
100
  /** Author/creator information */
101
  author: AuthorInfo;
102
  /** Array of image URLs */
103
  images: string[];
104
  /** Background music information */
105
  music: MusicInfo;
106
}
107
```
108

109
### Author Information
110

111
Comprehensive author/creator profile data.
112

113
```javascript { .api }
114
interface AuthorInfo {
115
  /** TikTok user ID */
116
  uid: string;
117
  /** Unique username handle */
118
  username: string;
119
  /** Display name */
120
  nickname: string;
121
  /** User bio/signature */
122
  signature: string;
123
  /** User region/location */
124
  region: string;
125
  /** Avatar thumbnail URLs */
126
  avatarThumb: string[];
127
  /** Avatar medium size URLs */
128
  avatarMedium: string[];
129
  /** TikTok profile URL */
130
  url: string;
131
}
132
```
133

134
### Music Information
135

136
Background music and audio track details.
137

138
```javascript { .api }
139
interface MusicInfo {
140
  /** Music track ID */
141
  id: string;
142
  /** Track title */
143
  title: string;
144
  /** Music artist/author */
145
  author: string;
146
  /** Album name */
147
  album: string;
148
  /** Audio playback URLs */
149
  playUrl: string[];
150
  /** Large cover image URLs */
151
  coverLarge: string[];
152
  /** Medium cover image URLs */
153
  coverMedium: string[];
154
  /** Thumbnail cover image URLs */
155
  coverThumb: string[];
156
  /** Track duration in seconds */
157
  duration: number;
158
}
159
```
160

161
## Error Handling
162

163
The TiktokDL function includes robust error handling for various failure scenarios:
164

165
- **Invalid URLs**: Returns error status with descriptive message
166
- **Network failures**: Automatic retry mechanism with exponential backoff
167
- **API rate limiting**: Built-in retry logic for temporary API issues
168
- **Missing content**: Graceful handling when video data is unavailable
169

170
Common error messages:
171
- `"Failed to fetch tiktok url. Make sure your tiktok url is correct!"`
172
- `"Failed to fetch tiktok data. Make sure your tiktok url is correct!"`
173

174
### Internal Helper Functions
175

176
Core helper functions used internally by the TikTok API module.
177

178
```javascript { .api }
179
/**
180
 * Parse raw TikTok API response data into structured format
181
 * @param data - Raw API response from TikTok
182
 * @returns Parsed content with author and music information
183
 */
184
function parseTiktokData(data: any): { content: any; author: AuthorInfo; music: MusicInfo } | { content: null };
185

186
/**
187
 * Generate required parameters for TikTok API requests
188
 * @param args - Base parameters to extend
189
 * @returns Complete parameter object with device simulation
190
 */
191
function withParams(args: object): TikTokAPIParams;
192

193
/**
194
 * Generate random character string for device identifiers
195
 * @param char - Character set to choose from
196
 * @param range - Length of random string
197
 * @returns Random string of specified length
198
 */
199
function randomChar(char: string, range: number): string;
200

201
/**
202
 * Convert duration in seconds to MM:SS format
203
 * @param duration - Duration in seconds
204
 * @returns Formatted duration string
205
 */
206
function toMinute(duration: number): string;
207

208
/**
209
 * Fetch TikTok data by video ID with retry logic
210
 * @param ID - TikTok video ID
211
 * @returns Parsed TikTok content data
212
 */
213
async function fetchTiktokData(ID: string): Promise<ParsedTikTokData>;
214

215
/**
216
 * Generate TikTok API endpoint URL
217
 * @param Params - URL parameters string
218
 * @returns Complete API endpoint URL
219
 */
220
function _tiktokapi(Params: string): string;
221

222
interface TikTokAPIParams {
223
  version_name: string;
224
  version_code: string;
225
  build_number: string;
226
  manifest_version_code: string;
227
  update_version_code: string;
228
  openudid: string;
229
  uuid: string;
230
  _rticket: number;
231
  ts: number;
232
  device_brand: string;
233
  device_type: string;
234
  device_platform: string;
235
  resolution: string;
236
  dpi: number;
237
  os_version: string;
238
  os_api: string;
239
  carrier_region: string;
240
  sys_region: string;
241
  region: string;
242
  app_name: string;
243
  app_language: string;
244
  language: string;
245
  timezone_name: string;
246
  timezone_offset: string;
247
  channel: string;
248
  ac: string;
249
  mcc_mnc: string;
250
  is_my_cn: number;
251
  aid: number;
252
  ssmix: string;
253
  as: string;
254
  cp: string;
255
}
256

257
interface ParsedTikTokData {
258
  content: any;
259
  author: AuthorInfo;
260
  music: MusicInfo;
261
}
262
```
263

264
**Internal Implementation Details:**
265

266
The module uses TikTok's unofficial mobile API endpoint (`https://api22-normal-c-useast2a.tiktokv.com/aweme/v1/feed/`) and mimics Android app requests with proper headers and parameters. URL processing handles various TikTok URL formats (vm.tiktok.com, vt.tiktok.com, www.tiktok.com) and redirects to extract the video ID for API calls.
267

268
The `withParams()` function generates a complete Android device simulation including:
269
- Device specifications (Pixel 4, Android 10)
270
- Network information (carrier, region: US)
271
- App metadata (trill app, version 1.1.9)
272
- Random device identifiers for uniqueness
273

274
The `fetchTiktokData()` function implements infinite retry logic with async-retry for handling API rate limits and temporary failures.