HTTP Routes - TikTokLive

Overview

HTTP routes are registered on the TikTokWebClient and provide access to TikTok’s web API endpoints. Each route is a callable class that handles a specific API interaction.

Room Information Routes

FetchRoomIdLiveHTMLRoute

Fetch a user’s room ID by parsing their TikTok LIVE HTML page. Source: TikTokLive/client/web/routes/fetch_room_id_live_html.py:20

Usage

room_id = await client.web.fetch_room_id_from_html("username")

Parameters

unique_id (str) - The user’s unique_id/username

Returns

str - The room ID

Raises

UserOfflineError - User is not currently live
UserNotFoundError - User does not exist or cannot go live
FailedParseRoomIdError - Failed to parse room ID from HTML

FetchRoomIdAPIRoute

Fetch a user’s room ID from TikTok’s API endpoint. Source: TikTokLive/client/web/routes/fetch_room_id_api.py:9

Usage

room_id = await client.web.fetch_room_id_from_api("username")

Parameters

unique_id (str) - The user’s unique_id/username

Returns

int - The room ID

Raises

UserNotFoundError - User does not exist or cannot go live
FailedParseRoomIdError - Failed to parse room ID from response

FetchRoomInfoRoute

Retrieve detailed room information for a livestream. Source: TikTokLive/client/web/routes/fetch_room_info.py:21

Usage

# By room_id
room_info = await client.web.fetch_room_info(room_id=123456)

# By unique_id
room_info = await client.web.fetch_room_info(unique_id="username")

# Using stored room_id from client
room_info = await client.web.fetch_room_info()

Parameters

room_id (Optional[int]) - The room ID to fetch info for
unique_id (Optional[str]) - The user’s unique_id (alternative to room_id)

Returns

Dict[str, Any] - Room information dictionary

Raises

InvalidFetchRoomInfoPayload - Both room_id and unique_id specified, or neither specified
AgeRestrictedError - Stream is 18+ restricted (requires sessionid cookie)
FailedFetchRoomInfoError - Request failed

Age-restricted streams require authentication via sessionid cookie.

Status Routes

FetchIsLiveRoute

Check if a user is currently live on TikTok. Source: TikTokLive/client/web/routes/fetch_is_live.py:29

Usage

# Check by room_id
is_live = await client.web.fetch_is_live(room_id=123456)

# Check by unique_id
is_live = await client.web.fetch_is_live(unique_id="username")

# Check multiple room IDs at once
live_statuses = await client.web.fetch_is_live.fetch_is_live_room_ids(123456, 789012, 345678)

Parameters

room_id (Optional[int]) - The room ID to check
unique_id (Optional[str]) - The user’s unique_id to check

Returns

bool - Whether the user is currently live

Raises

InvalidFetchIsLiveRequest - Neither room_id nor unique_id provided
MissingRoomIdInResponse - Room ID not found (nonexistent or detected by TikTok)

Additional Methods

fetch_is_live_room_ids(*room_ids: int) -> List[bool] Check multiple room IDs at once:

statuses = await client.web.fetch_is_live.fetch_is_live_room_ids(123, 456, 789)
# Returns: [True, False, True]

fetch_is_live_unique_id(unique_id: str) -> bool Check a single unique_id:

is_live = await client.web.fetch_is_live.fetch_is_live_unique_id("username")

Gift Routes

FetchGifListRoute

Fetch the list of available gifts from TikTok. Source: TikTokLive/client/web/routes/fetch_gift_list.py:17

Usage

gift_data = await client.web.fetch_gift_list()

Parameters

room_id (Optional[str]) - The room ID to fetch gifts for (currently unused)

Returns

Dict[str, Any] - Gift list data containing gift information

Raises

FailedFetchGiftListError - Request to gift list endpoint failed

Media Routes

FetchImageDataRoute

Fetch image data from TikTok’s CDN. Source: TikTokLive/client/web/routes/fetch_image_data.py:9

Usage

from TikTokLive.proto import ImageModel

# From ImageModel object
image_bytes = await client.web.fetch_image_data(image_model)

# From URL string
image_bytes = await client.web.fetch_image_data("https://p16-sign.tiktokcdn-us.com/...")

Parameters

image (Union[str, ImageModel]) - Image URL string or ImageModel protobuf object

Returns

bytes - Raw image data

FetchVideoDataRoute

Record a TikTok livestream video in real-time using FFmpeg. Source: TikTokLive/client/web/routes/fetch_video_data.py:57

Usage

from TikTokLive.client.web.routes.fetch_video_data import (
    VideoFetchQuality,
    VideoFetchFormat
)

# Start recording
client.web.fetch_video_data(
    output_fp="stream_recording.flv",
    room_info=room_info,
    quality=VideoFetchQuality.HD,
    record_format=VideoFetchFormat.FLV,
    record_for=300  # Record for 5 minutes (-1 for infinite)
)

# Stop recording
client.web.fetch_video_data.stop()

Parameters

output_fp (Union[Path, str]) - Output file path for the recording
room_info (dict) - Room information dictionary (from fetch_room_info)
record_for (Optional[int]) - Duration in seconds (-1 or ≤0 for infinite)
quality (VideoFetchQuality) - Video quality preset
record_format (VideoFetchFormat) - Source format from TikTok
output_format (Optional[str]) - Output format for FFmpeg (defaults to record_format)
**kwargs - Additional FFmpeg options

Video Quality Options

class VideoFetchQuality(enum.Enum):
    LD = "ld"        # Low definition (480p, 500kbps)
    SD = "sd"        # Standard definition (480p, 800kbps)
    HD = "hd"        # High definition (540p, 1Mbps)
    UHD = "uhd"      # Ultra-high definition (720p, 1Mbps)
    ORIGIN = "origin"  # Original quality

Video Format Options

class VideoFetchFormat(enum.Enum):
    FLV = "flv"    # Flash Video
    HLS = "hls"    # HTTP Live Streaming
    CMAF = "cmaf"  # Common Media Application Format

Properties

ffmpeg (Optional[FFmpeg]) - The FFmpeg instance (None when not recording)
is_recording (bool) - Whether currently recording
output_filename (Optional[str]) - Current output file path

Methods

start(**kwargs) - Start recording (alias for __call__) stop() - Stop the current recording

Raises

DuplicateDownloadError - Already recording this stream

Requires FFmpeg to be installed and available in system PATH.

WebSocket Routes

FetchSignedWebSocketRoute

Fetch signed WebSocket connection data from the signature server. Source: TikTokLive/client/web/routes/fetch_signed_websocket.py:30

Usage

from TikTokLive.client.web.routes.fetch_signed_websocket import WebcastPlatform

ws_data = await client.web.fetch_signed_websocket(
    platform=WebcastPlatform.WEB,
    room_id=123456
)

Parameters

platform (WebcastPlatform) - Platform type (WEB or MOBILE)
room_id (Optional[int]) - Room ID to connect to
session_id (Optional[str]) - Session ID for authenticated connection
tt_target_idc (Optional[str]) - TikTok target IDC cookie value

Returns

ProtoMessageFetchResult - Initial WebSocket message data

Platform Options

class WebcastPlatform(enum.Enum):
    WEB = "web"        # Web platform
    MOBILE = "mobile"  # Mobile platform (requires sessionid)

Raises

SignAPIError - Sign server request failed
SignatureRateLimitError - Too many connection attempts
ValueError - Mobile platform requires sessionid cookie

Mobile platform requires authentication. Web platform is recommended for most use cases.

User Routes

FetchUserUniqueIdRoute

Resolve a TikTok user ID to their unique_id (username). Source: TikTokLive/client/web/routes/fetch_user_unique_id.py:27

Usage

unique_id = await client.web.fetch_user_unique_id(7230478347297063942)
# Returns: "username"

Parameters

user_id (int) - The numeric user ID

Returns

str - The user’s unique_id (username)

Raises

FailedParseAppInfo - Failed to extract user data from HTML
FailedResolveUserId - Failed to resolve user ID to unique_id

Interaction Routes

All interaction routes require authentication via session cookies. See Session Management for setup instructions.

SendRoomChatRoute

Send a chat message to a livestream room. Source: TikTokLive/client/web/routes/send_room_chat.py:10

Usage

# Set session first
client.web.set_session(
    session_id="your_sessionid_cookie",
    tt_target_idc="useast1a"
)

# Send message
response = await client.web.send_room_chat(
    content="Hello from TikTokLive!",
    room_id=123456
)

Parameters

content (str) - The chat message content
room_id (Optional[int]) - Room ID to send message to
session_id (Optional[str]) - Session ID cookie (overrides client cookies)
tt_target_idc (Optional[str]) - TikTok target IDC value

Returns

dict - Response from TikTok’s chat endpoint

Raises

ValueError - No room_id provided and client has no stored room_id
Authentication errors if session is invalid

SendRoomLikeRoute

Send likes to a livestream room. Source: TikTokLive/client/web/routes/send_room_like.py:9

Usage

response = await client.web.send_room_like(
    count=5,
    room_id=123456
)

Parameters

count (int) - Number of likes to send
room_id (Optional[int]) - Room ID to send likes to

Returns

dict - Response from TikTok’s like endpoint

Raises

UserOfflineError - Cannot send likes to offline room
WebcastBlocked200Error - Blocked by TikTok (JA3 fingerprint mismatch)

Requires curl_cffi HTTP backend for JA3 fingerprint spoofing and valid signature from sign server.

SendRoomGiftRoute

Send a gift to a livestream broadcaster. Source: TikTokLive/client/web/routes/send_room_gift.py:40

Usage

from TikTokLive.client.web.routes.send_room_gift import GiftPayload
import time

payload: GiftPayload = {
    "room_id": 123456,
    "count": 1,
    "gift_id": 5655,
    "to_user_id": 7230478347297063942,
    "enter_from": "live_detail_",
    "is_opted_in_host": True,
    "is_subscription": False,
    "send_gift_req_start_ms": int(time.time() * 1000),
    "send_scene": 1,
    "send_type": 1
}

response = await client.web.send_room_gift(payload)

Parameters

payload (GiftPayload) - Gift payload dictionary

GiftPayload Structure

class GiftPayload(TypedDict):
    room_id: Optional[int]              # Room ID
    count: int                          # Number of gifts
    gift_id: int                        # Gift ID from gift list
    to_user_id: int                     # Recipient user ID
    enter_from: str                     # Entry source (e.g., "live_detail_")
    is_opted_in_host: bool              # Host opt-in status
    is_subscription: bool               # Subscription gift flag
    send_gift_req_start_ms: int         # Request timestamp in milliseconds
    send_scene: int                     # Send scene ID
    send_type: int                      # Send type ID

Returns

dict - Response from TikTok’s gift endpoint

Raises

WebcastBlocked200Error - Blocked by TikTok (JA3 fingerprint mismatch)

Requires:

Valid sessionid cookie
curl_cffi HTTP backend for JA3 fingerprint spoofing
Valid signature from sign server
Sufficient TikTok coin balance

Error Handling

All routes may raise the following general errors:

httpx.HTTPError - Network/HTTP errors
SignAPIError - Sign server errors
TikTokLiveError - Base exception for all TikTokLive errors

Example error handling:

from TikTokLive.client.errors import (
    UserOfflineError,
    UserNotFoundError,
    AgeRestrictedError,
    SignatureRateLimitError
)

try:
    room_info = await client.web.fetch_room_info(unique_id="username")
except UserOfflineError:
    print("User is not currently live")
except UserNotFoundError:
    print("User does not exist")
except AgeRestrictedError:
    print("Stream is age-restricted, authentication required")
except SignatureRateLimitError as e:
    print(f"Rate limited, try again in {e.retry_after} seconds")

Client

Events

Web Client

WebSocket

Errors

​Overview

​Room Information Routes

​FetchRoomIdLiveHTMLRoute

​Usage

​Parameters

​Returns

​Raises

​FetchRoomIdAPIRoute

​Usage

​Parameters

​Returns

​Raises

​FetchRoomInfoRoute

​Usage

​Parameters

​Returns

​Raises

​Status Routes

​FetchIsLiveRoute

​Usage

​Parameters

​Returns

​Raises

​Additional Methods

​Gift Routes

​FetchGifListRoute

​Usage

​Parameters

​Returns

​Raises

​Media Routes

​FetchImageDataRoute

​Usage

​Parameters

​Returns

​FetchVideoDataRoute

​Usage

​Parameters

​Video Quality Options

​Video Format Options

​Properties

​Methods

​Raises

​WebSocket Routes

​FetchSignedWebSocketRoute

​Usage

​Parameters

​Returns

​Platform Options

​Raises

​User Routes

​FetchUserUniqueIdRoute

​Usage

​Parameters

​Returns

​Raises

​Interaction Routes

​SendRoomChatRoute

​Usage

​Parameters

​Returns

​Raises

​SendRoomLikeRoute

​Usage

​Parameters

​Returns

​Raises

​SendRoomGiftRoute

​Usage

​Parameters

​GiftPayload Structure

​Returns

​Raises

​Error Handling

​See Also

Overview

Room Information Routes

FetchRoomIdLiveHTMLRoute

Usage

Parameters

Returns

Raises

FetchRoomIdAPIRoute

Usage

Parameters

Returns

Raises

FetchRoomInfoRoute

Usage

Parameters

Returns

Raises

Status Routes

FetchIsLiveRoute

Usage

Parameters

Returns

Raises

Additional Methods

Gift Routes

FetchGifListRoute

Usage

Parameters

Returns

Raises

Media Routes

FetchImageDataRoute

Usage

Parameters

Returns

FetchVideoDataRoute

Usage

Parameters

Video Quality Options

Video Format Options

Properties

Methods

Raises

WebSocket Routes

FetchSignedWebSocketRoute

Usage

Parameters

Returns

Platform Options

Raises

User Routes

FetchUserUniqueIdRoute

Usage

Parameters

Returns

Raises

Interaction Routes

SendRoomChatRoute

Usage

Parameters

Returns

Raises

SendRoomLikeRoute

Usage

Parameters

Returns

Raises

SendRoomGiftRoute

Usage

Parameters

GiftPayload Structure

Returns

Raises

Error Handling

See Also