Unofficial TikTok/Musical.ly API

A reverse-engineered implementation of the TikTok (previously musical.ly) app's API.

Installation

npm i tiktok-api

Usage

Creating an instance

import TikTokAPI, { getRequestParams } from 'tiktok-api';

// Required - a method that signs the URL with anti-spam parameters
// You must provide an implementation yourself to successfully make
// most requests with this library.
const signURL = async (url, ts, deviceId) => {
  const as = 'anti-spam parameter 1';
  const cp = 'anti-spam parameter 2'
  const mas = 'anti-spam parameter 3';
  return `${url}&as=${as}&cp=${cp}&mas=${mas}`;
}

// Required - device parameters
// You need to source these using a man-in-the-middle proxy such as mitmproxy,
// CharlesProxy or PacketCapture (Android)
const params = getRequestParams({
  device_id: '<device_id>',
  fp: '<device_fingerprint>',
  iid: '<install_id>',
  openudid: '<device_open_udid>',
});

const api = new TikTokAPI(params, { signURL });

// You are now able to make successful requests

Instance methods

• .loginWithEmail(email, password)
• .getUser(id)
• .searchUsers(params)
• .listPosts(params)
• .listFollowers(params)
• .listFollowing(params)
• .follow(id)
• .unfollow(id)
• .likePost(id)
• .unlikePost(id)
• .listComments(params)
• .postComment(postId, text, [tags])
• .listCategories(params)
• .searchHashtags(params)
• .listForYouFeed([params])
• .listFollowingFeed([params])
• .joinLiveStream(id)
• .leaveLiveStream(id)

.loginWithEmail(email, password)

Authenticates you with the API and stores your session data in a cookie jar. Subsequent requests will include these cookies.

api.loginWithEmail('<email>', '<password>')
  .then(res => console.log(res.data))
  .catch(console.log)

// Outputs:
// { email: '<email>', session_key: '123456', user_id: '123456', ... }

See the login types for the response data.

.getUser(id)

Gets a user's profile.

api.getUser('<user_id>')
  .then(res => console.log(res.data.user))
  .catch(console.log);

// Outputs:
// { aweme_count: 1000, nickname: 'example', unique_id: 'musername', ... }

See the user types for the response data.

.searchUsers(params)

Searches for users.

api.searchUsers({
  keyword: 'example',
  count: 10,
  cursor: 0,
})
  .then(res => console.log(res.data.user_list))
  .catch(console.log);

// Outputs:
// [{ user_info: {...}, position: [], uniqposition: [] }, ...]

See the search types for the complete request/response objects.

.listPosts(params)

Lists a user's posts.

api.listPosts({
  user_id: '<user_id>',
  max_cursor: 0,
})
  .then(res => console.log(res.data.aweme_list))
  .catch(console.log);

// Outputs:
// [{ author: {...}, aweme_id: '999', desc: 'description', music: {...}, statistics: {...}, video: {...} }, ...]

See the post types for the complete request/response objects.

.listFollowers(params)

Lists the users that follow the specified user.

api.listFollowers({
  user_id: '<user_id>',
  max_time: Math.floor(new Date().getTime() / 1000),
})
  .then(res => console.log(res.data.followers))
  .catch(console.log);

// Outputs:
// [{ unique_id: 'follower1' }, { unique_id: 'follower2' }, ...]

See the follower types for the complete request/response objects.

.listFollowing(params)

Lists the users that the specified user follows.

api.listFollowing({
  user_id: '<user_id>',
  max_time: Math.floor(new Date().getTime() / 1000),
})
  .then(res => console.log(res.data.followings))
  .catch(console.log);

// Outputs:
// [{ unique_id: 'following1' }, { unique_id: 'following2' }, ...]

See the following types for the complete request/response objects.

.follow(id)

Follows a user.

api.follow('<user_id>')
  .then(res => console.log(res.data.follow_status))
  .catch(console.log);

// Outputs:
// 1

See the follow types for the response data.

.unfollow(id)

Stops following a user.

api.unfollow('<user_id>')
  .then(res => console.log(res.data.follow_status))
  .catch(console.log);

// Outputs:
// 0

See the follow types for the response data.

.likePost(id)

Likes a post.

api.likePost('<post_id>')
  .then(res => console.log(res.data.is_digg))
  .catch(console.log);

// Outputs:
// 1

.unlikePost(id)

Unlikes a post.

api.unlikePost('<post_id>')
  .then(res => console.log(res.data.is_digg))
  .catch(console.log);

// Outputs:
// 0

.listComments(params)

Lists comments for a post.

api.listComments({
  aweme_id: '<post_id>',
  cursor: 0,
})
  .then(res => console.log(res.data.comments))
  .catch(console.log);

// Outputs:
// [{ text: 'first!', user: {...} }, { text: 'second!', user: {...} }, ...]

See the comment types for the response data.

.postComment(postId, text, [tags])

Comments on a post.

api.postComment('<post_id>', 'first!')
  .then(res => console.log(res.data.comment))
  .catch(console.log);

// Outputs:
// { cid: '<comment_id>', text: 'first!', user: {...}, ... }

See the comment types for the response data.

.listCategories(params)

Lists popular categories/hashtags.

api.listCategories({
  count: 10,
  cursor: 0,
})
  .then(res => console.log(res.data.category_list))
  .catch(console.log);

// Outputs:
// [{ { challenge_info: { cha_name: 'posechallenge', cid: '123' }, desc: 'Trending Hashtag' }, ...]

See the category types for the complete request/response objects.

.searchHashtags(params)

Searches for hashtags.

api.searchHashtags({
  keyword: 'example',
  count: 10,
  cursor: 0,
})
  .then(res => console.log(res.data.challenge_list))
  .catch(console.log);

// Outputs:
// [{ challenge_info: {...}, position: [] }, ...]

See the search types for the complete request/response objects.

.listForYouFeed([params])

Lists posts in the For You feed.

api.listForYouFeed()
  .then(res => console.log(res.data.aweme_list))
  .catch(console.log);

// Outputs:
// [{ author: {...}, aweme_id: '999', desc: 'description', music: {...}, statistics: {...}, video: {...} }, ...]

See the feed types for the complete request/response objects.

.listFollowingFeed([params])

Lists posts in the Following feed.

api.listFollowingFeed()
  .then(res => console.log(res.data.aweme_list))
  .catch(console.log);

// Outputs:
// [{ author: {...}, aweme_id: '999', desc: 'description', music: {...}, statistics: {...}, video: {...} }, ...]

See the feed types for the complete request/response objects.

.joinLiveStream(id)

Joins a live stream.

The rtmp_pull_url value can be used with VLC's Open Network Stream option.

api.joinLiveStream('<room_id>')
  .then(res => console.log(res.data.room))
  .catch(console.log);

// Outputs:
// { create_time: 1000000000, owner: {...}, stream_url: {...}, title: 'Example', user_count: 1000, ... }

See the live stream types for the complete request/response objects.

.leaveLiveStream(id)

Leaves a live stream.

api.leaveLiveStream('<room_id>')
  .then(res => console.log(res.data.status_code))
  .catch(console.log);

// Outputs:
// 0

See the live stream types for the complete request/response objects.

Resources

• Reverse engineering the musical.ly API

Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by TikTok or any of its affiliates or subsidiaries. This is an independent and unofficial API. Use at your own risk.