Table of Contents

• Description
• Quick Installation
• Installation Methods
  • Using Installation Script
  • Using NPM
  • Using Yarn
  • Using Github
• Usage Guide
  • Getting Tiktok Cookie
  • Using the Search Feature
  • Using CLI
  • Building from Source
  • CLI Usage
  • Example Cookie Usage
• Features
  • Tiktok Downloader
  • Tiktok Search
  • Tiktok Stalk User Profile
  • Tiktok Video User Comments
  • Tiktok Get User Posts
  • Tiktok Get User Reposts
  • Tiktok Get User Favorite Videos
  • Tiktok Collection
  • Tiktok Playlist
• API Response Types
  • Tiktok Downloader
    • Version 1 Response
    • Version 2 Response
    • Version 3 Response
  • Tiktok Search
  • Tiktok Stalk User Profile
  • Tiktok Video Comments
  • Tiktok User Posts
  • Tiktok User Reposts
  • Tiktok User Favorite Videos
  • Tiktok Collection
  • Tiktok Playlist
• Contributing
• License

Description

Note : This project uses the API from Tiktok & Unofficial Tiktok API from Another Website. This project is not affiliated with Tiktok.

• This project is made to help users to download videos, images / slides and music from Tiktok.
• This project is also made to help users to view someone's profile from Tiktok.
• This project is also made to help users to view comments from a video on Tiktok.
• This project is also made to help users to search for users, live streams and videos on Tiktok.
• This project is also made to help users to get user's posts, reposts and liked videos from Tiktok.
• This project is made to help users to get videos, images / slides from a Tiktok collection or playlist.

Quick Installation

Install using our automated script:

curl -o install.sh https://raw.githubusercontent.com/TobyG74/tiktok-api-dl/master/install.sh
chmod +x install.sh
./install.sh

The script automatically:

• Verifies Node.js installation and version
• Installs the library using npm or yarn
• Provides usage examples

Installation Methods

Using NPM

npm install @tobyg74/tiktok-api-dl

Using Yarn

yarn add @tobyg74/tiktok-api-dl

Using Github

npm install github:TobyG74/tiktok-api-dl

Usage Guide

Getting Tiktok Cookie

1. Install Cookie-Editor
2. Login to Tiktok
3. Open Cookie-Editor
4. Copy the cookie and use it in your code: COOKIE: "YOUR_COOKIE"

Using the Search Feature

• To use the search feature, you need to install the Canvas library.

npm install canvas

Using CLI

Global Installation

npm install -g @tobyg74/tiktok-api-dl
tiktokdl [command] [options]

Direct Usage

git clone https://github.com/TobyG74/tiktok-api-dl.git
cd tiktok-api-dl
npm install
npx ts-node src/cli/index.ts [command] [options]

NPM Script

npm run cli  [command] [options]

CLI Usage

$ tiktokdl -h
Usage: tiktokdl [options] [command]

Tiktok downloader and search CLI tool

Options:
  -V, --version                output the version number
  -h, --help                   display help for command

Commands:
  download [options] <url>     Download Tiktok Video / Slide / Music
  cookie                       Cookie Manager
  search                       Search Tiktok users or live streams
  getvideocomments [options] <url>  Get comments from a Tiktok video
  getuserposts [options] <username>  Get posts from a Tiktok user
  getuserreposts [options] <username>  Get reposts from a Tiktok user
  stalk [options] <username>   Stalk a Tiktok user
  help [command]               display help for command

Example Cookie Usage

# Set Tiktok Cookie to use in commands
tiktokdl cookie set "YOUR_COOKIE"

# Get Tiktok Cookie
tiktokdl cookie get

# Delete Tiktok Cookie
tiktokdl cookie delete

Building from Source

git clone https://github.com/TobyG74/tiktok-api-dl.git
cd tiktok-api-dl
npm install
npm run build

Features

Tiktok Downloader

const Tiktok = require("@tobyg74/tiktok-api-dl")

const url = "https://vt.tiktok.com/xxxxxxxx"
Tiktok.Downloader(url, {
  version: "v1", // "v1" | "v2" | "v3"
  proxy: "YOUR_PROXY", // optional
  showOriginalResponse: true // optional, v1 only
}).then((result) => console.log(result))

CLI Usage

# Download Tiktok Video
tiktokdl download "https://vt.tiktok.com/xxxxxxxx"

# Download Tiktok Video with version
tiktokdl download "https://vt.tiktok.com/xxxxxxxx" -v v1

# Download Tiktok Video with Custom Output Directory Path
tiktokdl download "https://vt.tiktok.com/xxxxxxxx" -v v1 -o "/path/to/save/video.mp4"

# Download Tiktok Video with Proxy
tiktokdl download "https://vt.tiktok.com/xxxxxxxx" -v v1 -proxy "http://your-proxy-url"

# Download Collection or Playlist
tiktokdl download "https://www.tiktok.com/@username/collection/name-id"
tiktokdl download "https://www.tiktok.com/@username/playlist/name-id"

# Download Collection or Playlist with Count
tiktokdl download "https://www.tiktok.com/@username/collection/name-id" -c 5
tiktokdl download "https://www.tiktok.com/@username/playlist/name-id" -c 5

# Download Collection or Playlist with Proxy
tiktokdl download "https://www.tiktok.com/@username/collection/name-id" -c 5 -proxy "http://your-proxy-url"
tiktokdl download "https://www.tiktok.com/@username/playlist/name-id" -c 5 -proxy "http://your-proxy-url"

• Version 1 Response
• Version 2 Response
• Version 3 Response

Tiktok Search

const Tiktok = require("@tobyg74/tiktok-api-dl")

Tiktok.Search("username", {
  type: "user", // "user" | "live" | "video"
  page: 1,
  cookie: "YOUR_COOKIE", // needed
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

CLI Usage

# Search Tiktok Users
tiktokdl search user <username>

# Search Tiktok Users with pagination
tiktokdl search user <username> -p 1

# Search Tiktok Users with proxy
tiktokdl search user <username> -p 1 -proxy "http://your-proxy-url"

# Search Tiktok Live Streams
tiktokdl search live <username>

# Search Tiktok Live Streams with pagination
tiktokdl search live <username> -p 1

# Search Tiktok Live Streams with proxy
tiktokdl search live <username> -p 1 -proxy "http://your-proxy-url"

# Search Tiktok Videos
tiktokdl search video <query>

# Search Tiktok Videos with pagination
tiktokdl search video <query> -p 1

# Search Tiktok Videos with proxy
tiktokdl search video <query> -p 1 -proxy "http://your-proxy-url"

• User Search Response
• Live Search Response
• Video Search Response

Tiktok Stalk User Profile

const Tiktok = require("@tobyg74/tiktok-api-dl")

const username = "Tobz2k19"
Tiktok.StalkUser(username, {
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

CLI Usage

# Stalk User Profile
tiktokdl stalk <username>

# Stalk User Profile with proxy
tiktokdl stalk <username> -proxy "http://your-proxy-url"

• Tiktok Stalk User Response

Tiktok Video Comments

const Tiktok = require("@tobyg74/tiktok-api-dl")

const url = "https://vt.tiktok.com/xxxxxxxx"
Tiktok.GetVideoComments(url, {
  commentLimit: 10, // optional, default is 30
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

CLI Usage

# Get Video Comments
tiktokdl getvideocomments "https://vt.tiktok.com/xxxxxxxx"

# Get Video Comments with limit of comments
tiktokdl getvideocomments "https://vt.tiktok.com/xxxxxxxx" -l 10

# Get Video Comments with proxy
tiktokdl getvideocomments "https://vt.tiktok.com/xxxxxxxx" -l 10 -proxy "http://your-proxy-url"

• Tiktok Video Comments Response

Tiktok Get User Posts

const Tiktok = require("@tobyg74/tiktok-api-dl")

const username = "Tobz2k19"
Tiktok.GetUserPosts(username, {
  postLimit: 10, // optional, default is 30
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

CLI Usage

# Get User Posts
tiktokdl getuserposts <username>

# Get User Posts with limit of posts
tiktokdl getuserposts <username> -l 10

# Get User Posts with proxy
tiktokdl getuserposts <username> -l 10 -proxy "http://your-proxy-url"

• Tiktok User Posts Response

Tiktok Get User Reposts

const Tiktok = require("@tobyg74/tiktok-api-dl")

const username = "Tobz2k19"
Tiktok.GetUserReposts(username, {
  postLimit: 10, // optional, default is 30
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

CLI Usage

# Get User Reposts
tiktokdl getuserreposts <username>

# Get User Reposts with limit of reposts
tiktokdl getuserreposts <username> -l 10

# Get User Reposts with proxy
tiktokdl getuserreposts <username> -l 10 -proxy "http://your-proxy-url"

• Tiktok User Reposts Response

Tiktok Get User Favorite Videos

• Note: To use this feature, you must be logged in with valid TikTok cookies to access user's liked videos

const Tiktok = require("@tobyg74/tiktok-api-dl")

const username = "Tobz2k19"
Tiktok.GetUserLiked(username, {
  postLimit: 10, // optional, default is 30
  cookie: "YOUR_COOKIE", // needed
  proxy: "YOUR_PROXY" // optional
})

CLI Usage

# Get User Liked Videos
tiktokdl getuserliked <username>

# Get User Liked Videos with limit of posts
tiktokdl getuserliked <username> -l 10

# Get User Liked Videos with proxy
tiktokdl getuserliked <username> -l 10 -proxy "http://your-proxy-url"

• Tiktok User Liked Videos Response

Tiktok Collection

Get videos from a TikTok collection (supports collection ID or URL)

const Tiktok = require("@tobyg74/tiktok-api-dl")

// Using collection ID
const collectionId = "7507916135931218695"
Tiktok.Collection(collectionId, {
  page: 1, // optional, default is 1
  count: 5, // optional, default is 5
  proxy: "YOUR_PROXY" // optional
}).then((result) => console.log(result))

// Using collection URL
const collectionUrl = "https://www.tiktok.com/@username/collection/name-id"
Tiktok.Collection(collectionUrl, {
  page: 1,
  count: 5,
  proxy: "YOUR_PROXY"
}).then((result) => console.log(result))

CLI Usage

# Using download command with collection URL
tiktokdl download "https://www.tiktok.com/@username/collection/name-id"

# Using download command with count
tiktokdl download "https://www.tiktok.com/@username/collection/name-id" -c 5

# Using collection ID
tiktokdl collection 7507916135931218695 -c 5

# Using collection URL
tiktokdl collection "https://www.tiktok.com/@username/collection/name-id"

# Using collection URL with count
tiktokdl collection "https://www.tiktok.com/@username/collection/name-id" -c 5

# With page for pagination
tiktokdl collection 7507916135931218695 -p 1 -c 5

# With proxy
tiktokdl collection 7507916135931218695 -c 5 -proxy "http://your-proxy-url"

• Tiktok Collection Response

Tiktok Playlist

Get videos from a TikTok playlist (supports playlist ID or URL)

const Tiktok = require("@tobyg74/tiktok-api-dl")

const playlistIdOrUrl = "https://www.tiktok.com/@username/playlist/name-id"
Tiktok.Playlist(playlistIdOrUrl, {
  page: 1,
  count: 5,
  proxy: "YOUR_PROXY"
}).then((result) => console.log(result))

CLI Usage

# Using download command with playlist URL
tiktokdl download "https://www.tiktok.com/@username/playlist/name-id"

# Using download command with count
tiktokdl download "https://www.tiktok.com/@username/playlist/name-id" -c 5

# Using playlist ID
tiktokdl download 7507916135931218695 -c 5

# Using playlist URL
tiktokdl playlist "https://www.tiktok.com/@username/playlist/name-id" -c 5

# With page for pagination
tiktokdl playlist 7507916135931218695 -p 1 -c 5

# With proxy
tiktokdl playlist 7507916135931218695 -c 5 -proxy "http://your-proxy-url"

• Tiktok Playlist Response

API Response Types

Tiktok Downloader

Version 1 Response

interface TiktokAPIResponse {
  status: "success" | "error"
  message?: string
  result?: {
    type: "video" | "image"
    id: string
    createTime: number
    desc: string
    author: {
      uid: number
      username: string
      nickname: string
      signature: string
      region: string
      avatarThumb: string[]
      avatarMedium: string[]
      url: string
    }
    statistics: {
      playCount: number
      downloadCount: number
      shareCount: number
      commentCount: number
      likeCount: number
      collectCount: number
      forwardCount: number
      whatsappShareCount: number
      loseCount: number
      loseCommentCount: number
      repostCount: number
    }
    hashtag: string[]
    isTurnOffComment: boolean
    isADS: boolean
    cover?: string[]
    dynamicCover?: string[]
    originCover?: string[]
    video?: {
      ratio: string
      duration: number
      playAddr: string[]
      downloadAddr: string[]
      cover: string[]
      dynamicCover: string[]
      originCover: string[]
    }
    images?: string[]
    music: {
      id: number
      title: string
      author: string
      album: string
      playUrl: string[]
      coverLarge: string[]
      coverMedium: string[]
      coverThumb: string[]
      duration: number
      isCommerceMusic: boolean
      isOriginalSound: boolean
      isAuthorArtist: boolean
    }
  }
  resultNotParsed?: any
}

Version 2 Response

interface SSSTikResponse {
  status: "success" | "error"
  message?: string
  result?: {
    type: "image" | "video" | "music"
    desc?: string
    author?: {
      avatar: string
      nickname: string
    }
    statistics?: {
      likeCount: string
      commentCount: string
      shareCount: string
    }
    images?: string[]
    video?: {
      playAddr: string
    }
    music?: {
      playUrl: string
    }
    direct?: string
  }
}

Version 3 Response

interface MusicalDownResponse {
  status: "success" | "error"
  message?: string
  result?: {
    type: "video" | "image"
    desc?: string
    author?: {
      avatar?: string
      nickname?: string
    }
    music?: string
    images?: string[]
    videoHD?: string
    videoWatermark?: string
  }
}

Tiktok Search

User Search Response

interface TiktokUserSearchResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    uid: string
    username: string
    nickname: string
    signature: string
    followerCount: number
    avatarThumb: string
    isVerified: boolean
    secUid: string
    url: string
  }>
  page?: number
  totalResults?: number
}

Live Search Response

interface TiktokLiveSearchResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    id: string
    title: string
    cover: string[]
    squareCover: string[]
    rectangleCover: string[]
    liveTypeThirdParty: boolean
    hashtag: string
    startTime: number
    stats: {
      totalUser: number
      viewerCount: number
      likeCount: number
    }
    owner: {
      id: string
      nickname: string
      username: string
      signature: string
      avatarThumb: string[]
      avatarMedium: string[]
      avatarLarge: string[]
      modifyTime: number
      stats: {
        followingCount: number
        followerCount: number
      }
      isVerified: boolean
    }
  }>
  page?: number
  totalResults?: number
}

Video Search Response

interface TiktokVideoSearchResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    id: string
    desc: string
    createTime: number
    author: {
      id: string
      uniqueId: string
      nickname: string
      avatarThumb: string
      avatarMedium: string
      avatarLarger: string
      signature: string
      verified: boolean
      secUid: string
      openFavorite: boolean
      privateAccount: boolean
      isADVirtual: boolean
      tiktokSeller: boolean
      isEmbedBanned: boolean
    }
    stats: {
      collectCount: number
      commentCount: number
      likeCount: number
      playCount: number
      shareCount: number
    }
    video: {
      id: string
      ratio: string
      cover: string
      originCover: string
      dynamicCover: string
      playAddr: string
      downloadAddr: string
      format: string
    }
    music: {
      id: string
      title: string
      playUrl: string
      coverThumb: string
      coverMedium: string
      coverLarge: string
      authorName: string
      original: boolean
      album: string
      duration: number
      isCopyrighted: boolean
    }
  }>
  page?: number
  totalResults?: number
}

Tiktok Stalk User Profile

Profile Response

interface TiktokStalkUserResponse {
  status: "success" | "error"
  message?: string
  result?: {
    user: {
      username: string
      nickname: string
      avatar: string
      signature: string
      verified: boolean
      region: string
    }
    stats: {
      followerCount: number
      followingCount: number
      heartCount: number
      videoCount: number
      likeCount: number
    }
  }
}

Tiktok Video Comments

Comments Response

interface TiktokVideoCommentsResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    cid: string
    text: string
    commentLanguage: string
    createTime: number
    likeCount: number
    isAuthorLiked: boolean
    isCommentTranslatable: boolean
    replyCommentTotal: number
    replyComment: []
    user: User
    url: string
  }>
  totalComments?: number
}

Tiktok User Posts

User Posts Response

interface TiktokUserPostsResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    id: string
    desc: string
    createTime: number
    digged: number
    duetEnabled: number
    forFriend: number
    officalItem: number
    originalItem: number
    privateItem: number
    shareEnabled: number
    stitchEnabled: number
    stats: {
      collectCount: number
      commentCount: number
      likeCount: number
      playCount: number
      shareCount: number
    }
    author: {
      id: string
      username: string
      nickname: string
      avatarLarger: string
      avatarThumb: string
      avatarMedium: string
      signature: string
      verified: boolean
      openFavorite: boolean
      privateAccount: boolean
      isADVirtual: boolean
      isEmbedBanned: boolean
    }
    video?: {
      id: string
      duration: number
      ratio: string
      cover: string
      originCover: string
      dynamicCover: string
      playAddr: string
      downloadAddr: string
      format: string
      bitrate: number
    }
    music: {
      authorName: string
      coverLarge: string
      coverMedium: string
      coverThumb: string
      duration: number
      id: string
      title: string
      playUrl: string
      original: boolean
    }
    images?: string[]
  }>
  totalPosts?: number
}

Tiktok User Reposts

User Reposts Response

interface TiktokUserRepostsResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    id: string
    desc: string
    createTime: number
    digged: boolean
    duetEnabled?: boolean
    forFriend: boolean
    officalItem: boolean
    originalItem: boolean
    privateItem: boolean
    secret: boolean
    shareEnabled: boolean
    stitchEnabled?: boolean
    stats: {
      shareCount: number
      collectCount?: number
      commentCount?: number
      likeCount?: number
      playCount?: number
      repostCount?: number
    }
    author: {
      id: string
      username: string
      nickname: string
      avatarLarger: string
      avatarThumb: string
      avatarMedium: string
      signature: string
      verified: boolean
      openFavorite?: boolean
      privateAccount?: boolean
      isADVirtual?: boolean
      isEmbedBanned?: boolean
    }
    video?: {
      id: string
      duration: number
      ratio: string
      cover: string
      originCover: string
      dynamicCover: string
      playAddr: string
      downloadAddr: string
      format: string
      bitrate: number
    }
    music: {
      authorName?: string
      coverLarge?: string
      coverMedium?: string
      coverThumb?: string
      duration?: number
      id?: string
      title?: string
      playUrl?: string
      original?: boolean
      tt2dsp?: any
    }
    imagePost?: {
      title: string
      images?: Array<{
        imageURL: {
          urlList: string[]
        }
      }>
    }
    AIGCDescription?: string
    CategoryType?: number
    collected?: boolean
    contents?: any[]
    challenges?: any[]
    textExtra?: any[]
    textLanguage?: string
    textTranslatable?: boolean
    titleLanguage?: string
    titleTranslatable?: boolean
    isAd?: boolean
    isReviewing?: boolean
    itemCommentStatus?: number
    item_control?: {
      can_repost?: boolean
      can_share?: boolean
    }
    duetDisplay?: number
    stitchDisplay?: number
    diversificationId?: number
    backendSourceEventTracking?: string
    stickersOnItem?: any[]
    videoSuggestWordsList?: any
  }>
  totalReposts?: number
}

Tiktok User Favorite Videos

User Favorite Videos Response

interface TiktokUserFavoriteVideosResponse {
  status: "success" | "error"
  message?: string
  result?: Array<{
    id: string
    desc: string
    createTime: string
    duetEnabled: boolean
    digged: boolean
    forFriend: boolean
    isAd: boolean
    originalItem: boolean
    privateItem: boolean
    officialItem: boolean
    secret: boolean
    shareEnabled: boolean
    stitchEanbled: boolean
    textTranslatable: boolean
    author: {
      id: string
      username: string
      nickname: string
      avatarLarger: string
      avatarThumb: string
      avatarMedium: string
      signature: string
      verified: string
      openFavorite: string
      privateAccount: string
      isADVirtual: string
      isEmbedBanned: string
    }
    stats: {
      collectCount: string
      commentCount: string
      likeCount: string
      playCount: string
      repostCount: string
      shareCount: string
    }
    video?: {
      id: string
      videoID: string
      duration: number
      ratio: string
      cover: string
      originCover: string
      dynamicCover: string
      playAddr: string
      downloadAddr: string
      format: string
      bitrate: number
      bitrateInfo: any[]
    }
    imagePost?: Array<{
      title: string
      images: string[]
    }>
    music: {
      id: string
      title: string
      playUrl: string
      coverThumb: string
      coverMedium: string
      coverLarge: string
      authorName: string
      original: boolean
      album: string
      duration: number
      isCopyrighted: boolean
      private: boolean
    }
  }>
  totalPosts?: number
}

Tiktok Collection

Collection Response

interface TiktokCollectionResponse {
  status: "success" | "error"
  message?: string
  result?: {
    itemList: Array<{
      id: string
      desc: string
      createTime: number
      author?: {
        id: string
        uniqueId: string
        nickname: string
        avatarThumb: string
        avatarMedium: string
        avatarLarger: string
        signature: string
        verified: boolean
      }
      statistics?: {
        playCount: number
        diggCount: number
        shareCount: number
        commentCount: number
        collectCount: number
      }
      video?: {
        id: string
        height: number
        width: number
        duration: number
        ratio: string
        cover: string
        originCover: string
        dynamicCover: string
        playAddr: string
        downloadAddr: string
        format: string
        bitrate: number
      }
      textExtra?: Array<{
        hashtagName: string
        hashtagId: string
        type: number
      }>
    }>
    hasMore: boolean
    cursor: string
  }
}

Tiktok Playlist

Playlist Response

status: "success" | "error"
message?: string
result?: {
  hasMore: boolean
  itemList: Array<{
    id: string
    desc: string
    createTime: number
    author: PlaylistAuthor
    stats: Statistics
    video: VideoTiktokAPI
    music: MusicTiktokAPI
    challenges: Array<{
      id: string
      title: string
      desc: string
      coverLarger: string
      coverMedium: string
      coverThumb: string
      profileLarger: string
      profileMedium: string
      profileThumb: string
    }>
    collected: boolean
    digged: boolean
    duetDisplay: number
    forFriend: boolean
    officalItem: boolean
    originalItem: boolean
    privateItem: boolean
    shareEnabled: boolean
    stitchDisplay: number
    textExtra: Array<{
      awemeId: string
      end: number
      hashtagName: string
      isCommerce: boolean
      start: number
      subType: number
      type: number
    }>
  }>
  extra?: {
    fatal_item_ids: string[]
    logid: string
    now: number
  }
}

Changelog

• All changes will be documented in the CHANGELOG.md file.

Contributing

• This repository is open source. We really appreciate it if you want to participate in developing this repository...
• Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing.

License

• This project is licensed under the Apache License - see the LICENSE file for details.