Fully-typed TikTok web API client that REALLY works—handles URL signing, msToken rotation, retries, video downloads with format detection, and helpers for profiles, posts, and challenges.
- Official TikTok web endpoints with automatic URL signing handled for you
- msToken extraction/rotation, retry with backoff, proxy support
- Video download with detailed format information (resolution, codec, watermark status)
- Dual builds (ESM + CJS) with full TypeScript types
- Pagination helpers for posts, followers, following, comments, and challenges
npm install @ssut/tiktok-api
npm install axios async-retry https-proxy-agentimport { TikTokClient, PostItemRequestType } from "@ssut/tiktok-api";
const client = new TikTokClient({ region: "US" });
// Get user profile
const user = await client.getUser("username");
// Get user posts
const posts = await client.getUserPosts(user.data?.userInfo.user.secUid ?? "", {
postLimit: 10,
requestType: PostItemRequestType.Popular,
});
// Get post comments
const comments = await client.getPostComments("7574735526134058262", 20);
// Download video with format detection
const download = await client.downloadVideo("https://www.tiktok.com/@zachking/video/6768504823336815877");
if (download.status === "success" && download.result?.type === "video") {
console.log("Available formats:", download.result.video.formats);
// Formats include resolution, codec (h264/h265), watermark status, etc.
}new TikTokClient({ region, proxy?, msToken?, tiktokApiHost? })getUser(username, overrides?)getUserPosts(secUid, { postLimit?, nextCursor?, requestType? } & overrides?)getUserFollowers(secUid, { followerLimit?, count?, cursor? } & overrides?)getUserFollowing(secUid, { followingLimit?, count?, cursor? } & overrides?)getPost(itemId, overrides?)getPostComments(awemeId, count?, { cursor? } & overrides?)getCommentReplies(awemeId, commentId, count?, { cursor? } & overrides?)getChallenge(hashtag, overrides?)downloadVideo(url, showOriginalResponse?, overrides?)
-
region(required) – e.g."US" -
proxy(optional) – HTTP proxy URL for all requests -
msToken(optional) – seed token; auto-rotates afterward -
tiktokApiHost(optional) – custom API host (defaults to"api16-normal-c-useast1a.tiktokv.com")
All methods support optional request overrides for per-request configuration:
// Use proxy for specific request
await client.getUser("username", {
proxy: "http://proxy.example.com:8080",
});
// Disable proxy for specific request (if set globally)
await client.downloadVideo(url, false, {
proxy: null,
});
// Override region for specific request
await client.getPost(itemId, {
region: "UK",
});The downloadVideo method provides rich format information:
const result = await client.downloadVideo(url);
if (result.status === "success" && result.result?.type === "video") {
const formats = result.result.video.formats;
// Each format includes:
for (const format of formats || []) {
console.log({
url: format.url, // Direct download URL
resolution: format.resolution, // e.g., "1080p", "720p", "480p"
format_id: format.format_id, // e.g., "play_addr", "download_addr"
format_note: format.format_note, // e.g., "Direct video", "Download video (watermarked)"
vcodec: format.vcodec, // e.g., "h264", "h265"
width: format.width, // Video width in pixels
height: format.height, // Video height in pixels
has_watermark: format.has_watermark, // Whether video has TikTok watermark
quality: format.quality, // Quality level
bitrate: format.bitrate, // Bitrate (if available)
fps: format.fps, // Frames per second (if available)
});
}
}All exports are fully typed:
import type {
// User types
TiktokStalkUserResponse,
TiktokUserDetailResponse,
TiktokUserFollowersResponse,
TiktokUserFollowingResponse,
TiktokUserPostsResponse,
TiktokPostItem,
// Content types
TiktokChallengeResponse,
TiktokPostResponse,
TiktokComment,
// Download types
TiktokDownloadResponse,
TiktokVideoResult,
TiktokImageResult,
TiktokVideoFormat,
TiktokAuthor,
TiktokStatistics,
TiktokMusic,
TiktokVideo,
// Enums
PostItemRequestType,
TiktokError,
} from "@ssut/tiktok-api";enum TiktokError {
HASHTAG_NOT_EXIST = 10205,
HASHTAG_BLACK_LIST = 10209,
HASHTAG_SENSITIVITY_WORD = 10211,
HASHTAG_UNSHELVE = 10212,
USER_BAN = 10221,
USER_PRIVATE = 10222,
USER_NOT_EXIST = 10202,
INVALID_ENTITY = 10201,
}- tiktok-web-reverse-engineering — X-Bogus and X-Gnarly implementation details
ISC
Forked from @rediska1114/tiktok-api (ISC); credits to the original authors.