HTTP Routes

Detailed reference for all TikTokWebClient HTTP route endpoints

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")

See Also

• TikTokWebClient
• WebDefaults Configuration
• Error Handling Guide
• Session Management