TikTokPy

TikTokPy allows you to extract data from TikTok without requiring login credentials or API keys. To begin using the library, you should follow these steps:

1. Install the library: Follow the installation guide to add TikTokPy to your project.
2. Understand the mechanics: Review the explanation of how the library works and its limitations (what it cannot do).
3. Learn usage patterns: Consult the usage guide to learn how to grab specific data from TikTok.
4. Download media: If your primary goal is downloading videos or slideshows, refer to the specific 'Download Videos and Slideshows' example.
5. Consult the API: For detailed technical specifications of the library's functions and classes, use the API Reference.

TikTokPy operates without login credentials or cookies by using a two-step retrieval process:

1. Grabbing Preloaded Content: It extracts data embedded directly in the HTML within a <script id="SIGI_STATE" type="application/json"> tag. This includes initial data for videos, comments, and users.
2. Grabbing Additional API Data: It intercepts subsequent API calls made by the page's JavaScript. TikTokPy uses the same cookies and headers that the page scripts would use, allowing it to mimic a normal browsing session without being logged in.

Note: This explanation applies to library versions prior to 0.2.0.

To use TikTokPy, install the tiktokapipy package using pip. You must also install the Playwright browsers to ensure the underlying automation works correctly.

Run the following commands in your terminal:

pip install tiktokapipy
python -m playwright install

TikTok restricts slideshows to mobile viewing. To retrieve data from slideshows, you must initialize the API with emulate_mobile=True.

Warning: You cannot use emulate_mobile=True and scroll_down_time simultaneously. If you need both slideshow data and additional data via scrolling, you must create two separate API instances: one for mobile emulation (for slideshows) and one for standard scraping (for scrolling).

# Using TikTokAPI
from tiktokapipy.api import TikTokAPI

def get_challenge_videos_scroll_down():
    with TikTokAPI(emulate_mobile=True) as api:
        slideshow = api.video(link_to_slideshow)
        ...

# Using AsyncTikTokAPI
from tiktokapipy.async_api import AsyncTikTokAPI

async def get_challenge_videos_scroll_down():
    async with AsyncTikTokAPI(emulate_mobile=True) as api:
        slideshow = await api.video(link_to_slideshow)
        ...

TikTokPy provides both synchronous (TikTokAPI) and asynchronous (AsyncTikTokAPI) interfaces. You should always use the API as a context manager to ensure proper lifecycle management of the underlying Playwright BrowserContext. The initialization arguments allow you to configure proxies, custom executable locations, and other browser settings.

# Synchronous usage
from tiktokapipy.api import TikTokAPI

def do_something():
    with TikTokAPI() as api:
        ...

# Asynchronous usage
from tiktokapipy.async_api import AsyncTikTokAPI

async def do_something():
    async with AsyncTikTokAPI() as api:
        ...

Install the tiktokapipy package via pip and ensure the Playwright browser binaries are installed to enable web automation.

Requirements:

• Python 3.8+

pip install tiktokapipy
python -m playwright install

To download content, you can use the download() method on a Video object.

Requirements:

• For download() to work, you must have yt-dlp installed (pip install yt-dlp or pip install tiktokapipy[download]).
• download() works for standard videos but not for slideshows.

Handling Slideshows: Slideshows consist of multiple images and an audio track. To download them as a single video, you must manually download the images and audio, then use a tool like ffmpeg to stitch them together.

# Basic video download using yt-dlp
with TikTokAPI() as api:
    video = api.video(video_url)
    video.download()

The library uses DeferredIterator subclasses to fetch data lazily. Instead of loading all results into memory at once, the iterator fetches chunks of data from the TikTok API only when needed during iteration.

Key implementations include:

• DeferredCommentIterator: Iterates through comments for a specific video_id.
• DeferredItemListIterator: Iterates through videos from a specific from_type ('post' or 'challenge') and target_id.
• DeferredChallengeIterator: Iterates through a list of provided challenge names.

Important Context Rule:

• If you are using an asynchronous API context, you must use async for with these iterators.
• If you are using a synchronous API context, you must use a standard for loop. Attempting to use the wrong loop type will raise a TikTokAPIError.

TikTokPy uses Pydantic models to represent the raw, unprocessed data retrieved from TikTok. These models are organized by the type of content being accessed. When working with raw responses, you will encounter several primary response types that wrap the actual data (like videos, users, or challenges) along with metadata like status codes and pagination cursors.

Key response types include:

• VideoResponse: Contains video data (item_module), comments (comment_item), and status information (video_page).
• UserResponse: Contains user data (user_module), video lists (item_module), and status information (user_page).
• ChallengeResponse: Contains challenge details (challenge_page) and associated videos (item_module).
• SentToLoginResponse: Triggered when a request requires authentication, providing a redirect_url to the login page.