This release is a pre-release and may not be stable for production use.
TikTokLive Python API (Unofficial)
TikTokLive is an unofficial Python API wrapper for TikTok LIVE written in Python. With this library you can connect to any TikTok livestream and fetch all data available to users in a stream using just a creator's @unique_id.
Note: This is not a production-ready API. It is a reverse engineering project. Use the WebSocket API for production.
TikTok LIVE API
 |
Euler Stream offers a comprehensive TikTok LIVE API, WebSocket Server, CAPTCHA Solutions and much more! |
Table of Contents
- Getting Started
- Documentation
- Other Languages
- Community
- Examples
- Licensing
- Star History
- Contributors
Community
Join the TikTokLive discord and visit
the #py-support
channel for questions, contributions and ideas.
Getting Started
- Install the module via pip from the PyPi repository
pip install TikTokLive
- Create your first chat connection
from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent
# Create the client
client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")
# Listen to an event with a decorator!
@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")
# Or, add it manually via "client.add_listener()"
async def on_comment(event: CommentEvent) -> None:
print(f"{event.user.nickname} -> {event.comment}")
client.add_listener(CommentEvent, on_comment)
if __name__ == '__main__':
# Run the client and block the main thread
# await client.start() to run non-blocking
client.run()
For more quickstart examples, see the examples folder provided in the source tree.
Other Languages
TikTokLive is available in several alternate programming languages:
- Node.JS: https://github.com/zerodytrash/TikTok-Live-Connector
- Java: https://github.com/jwdeveloper/TikTok-Live-Java
- C#/Unity: https://github.com/frankvHoof93/TikTokLiveSharp
- Go: https://github.com/steampoweredtaco/gotiktoklive
- Rust: https://github.com/jwdeveloper/TikTokLiveRust
Parameters
| Param Name | Required | Default | Description |
|---|---|---|---|
| unique_id | Yes | N/A | The unique username of the broadcaster. You can find this name in the URL of the user. For example, the unique_id for https://www.tiktok.com/@isaackogz would be isaackogz. |
| web_proxy | No | None |
TikTokLive supports proxying HTTP requests. This parameter accepts an httpx.Proxy. Note that if you do use a proxy you may be subject to reduced connection limits at times of high load. |
| ws_proxy | No | None |
TikTokLive supports proxying the websocket connection. This parameter accepts an httpx.Proxy. Using this proxy will never be subject to reduced connection limits. |
| web_kwargs | No | {} |
Under the scenes, the TikTokLive HTTP client uses the httpx library. Arguments passed to web_kwargs will be forward the the underlying HTTP client. |
| ws_kwargs | No | {} |
Under the scenes, TikTokLive uses the websockets library to connect to TikTok. Arguments passed to ws_kwargs will be forwarded to the underlying WebSocket client. |
Methods
A TikTokLiveClient object contains the following methods worth mentioning:
| Method Name | Notes | Description |
|---|---|---|
| run | N/A | Connect to the livestream and block the main thread. This is best for small scripts. |
| add_listener | N/A | Adds an asynchronous listener function (or, you can decorate a function with @client.on(Type[Event])) and takes two parameters, an event name and the payload, an AbstractEvent |
| connect | async |
Connects to the tiktok live chat while blocking the current future. When the connection ends (e.g. livestream is over), the future is released. |
| start | async |
Connects to the live chat without blocking the main thread. This returns an asyncio.Task object with the client loop. |
| disconnect | async |
Disconnects the client from the websocket gracefully, processing remaining events before ending the client loop. |
Properties
A TikTokLiveClient object contains the following important properties:
| Attribute Name | Description |
|---|---|
| room_id | The Room ID of the livestream room the client is currently connected to. |
| web | The TikTok HTTP client. This client has a lot of useful routes you should explore! |
| connected | Whether you are currently connected to the livestream. |
| logger | The internal logger used by TikTokLive. You can use client.logger.setLevel(...) method to enable client debug. |
| room_info | Room information that is retrieved from TikTok when you use a connection method (e.g. client.connect) with the keyword argument fetch_room_info=True . |
| gift_info | Extra gift information that is retrieved from TikTok when you use a connection method (e.g. client.run) with the keyword argument fetch_gift_info=True. |
WebDefaults
TikTokLive has a series of global defaults used to create the HTTP client which you can customize. For info on how to set these parameters, see the web_defaults.py example.
| Parameter | Type | Description |
|---|---|---|
| tiktok_sign_api_key | str |
A Euler Stream API key used to increase rate limits. |
| tiktok_app_url | str |
The TikTok app URL (https://www.tiktok.com) used to scrape the room. |
| tiktok_sign_url | str |
The signature server used to generate tokens to connect to TikTokLive. By default, this is Euler Stream, but you can swap your own with ease. |
| tiktok_webcast_url | str |
The TikTok livestream URL (https://webcast.tiktok.com) where livestreams can be accessed from. |
| web_client_params | dict |
The URL parameters added on to TikTok requests from the HTTP client. |
| web_client_headers | dict |
The headers added on to TikTok requests from the HTTP client. |
| web_client_cookies | dict |
Custom cookies to initialize the http client with. |
| ws_client_params | dict |
The URL parameters added to the URI when connecting to TikTok's Webcast WebSocket server. |
| ws_client_params_append_str | dict |
Extra string data to append to the TikTokLive WebSocket connection URI. |
| ws_client_headers | dict |
Extra headers to append to the TikTokLive WebSocket client. |
Events
Events can be listened to using a decorator or non-decorator method call. The following examples illustrate how you can listen to an event:
@client.on(LikeEvent)
async def on_like(event: LikeEvent) -> None:
...
async def on_comment(event: CommentEvent) -> None:
...
client.add_listener(CommentEvent, on_comment)
There are two types of events, CustomEvent
events and ProtoEvent events.
Both belong to the TikTokLive Event type and can be listened to. The following events are available:
Custom Events
ConnectEvent- Triggered when the Webcast connection is initiatedDisconnectEvent- Triggered when the Webcast connection closes (including the livestream ending)LiveEndEvent- Triggered when the livestream endsLivePauseEvent- Triggered when the livestream is pausedLiveUnpauseEvent- Triggered when the livestream is unpausedFollowEvent- Triggered when a user in the livestream follows the streamerShareEvent- Triggered when a user shares the livestreamSuperFanEvent- Triggered when a viewer becomes a super fan of the streamerSuperFanJoinEvent- Triggered when an existing super fan joins the live (distinct fromSuperFanEvent)SuperFanBoxEvent- Triggered when a super-fan envelope (gift box) is deliveredWebsocketResponseEvent- Triggered when any event is received (contains the event)UnknownEvent- An instance ofWebsocketResponseEventthrown whenever an event does not have an existing definition, useful for debugging
Proto Events
These events are auto-generated from the TikTokLiveProto v3 schema. Only events whose proto messages are present in v3 are emitted; if you don't see one you used to rely on, it's because TikTok removed it from the schema.
If you know what an event does that's missing a description below, make a pull request and add it.
BarrageEvent- A "VIP" viewer (based on gifting level) joins the chat roomCaptionEvent- Auto-caption update from the host's audioCommentEvent- A viewer sent a chat commentControlEvent- Stream action (e.g. start, end, pause, unpause)EmoteChatEvent- A custom emote was sent in chatEnvelopeEvent- A treasure chest / envelope was sentGiftEvent- A gift was sent (see Gift handling below)GoalUpdateEvent- Subscriber/follow goal updatedHourlyRankRewardEvent- Hourly rank reward deliveredImDeleteEvent- A viewer's messages were deleted by a moderatorInRoomBannerEvent- In-room banner noticeJoinEvent- A viewer joined the livestreamLikeEvent- The stream received likesLinkEvent- Generic link-mic eventLinkLayerEvent- Link-mic layer/visibility changeLinkMicArmiesEvent- A battle user received pointsLinkMicBattleEvent- A battle was startedLinkMicBattlePunishFinishEvent- A battle's punishment phase endedLinkMicFanTicketMethodEventLinkMicMethodEventLinkmicBattleTaskEventLiveIntroEvent- Live-intro message appearsMessageDetectEventOecLiveShoppingEvent- Live-shopping signalPollEvent- The creator launched / updated a pollQuestionNewEvent- Someone asked a new question via the question featureRankTextEvent- Gift count made a viewer enter the top threeRankUpdateEventRoomEvent- Broadcast message to all room users (e.g. "Welcome to TikTok LIVE!")RoomPinEvent- A message was pinnedRoomUserSeqEvent- Current viewer count informationSocialEvent- A viewer shared or followed the host (also surfaced asFollowEvent/ShareEventcustom events)SystemEventUnauthorizedMemberEvent
GiftEvent
Fires every time a gift is sent. Extra static metadata for every gift type
in the room can be fetched once on connect by passing
fetch_gift_info=True to client.run() / client.start(); the result is
cached on client.gift_info.
Streaks: streakable gifts trigger multiple
GiftEvents as the viewer ramps up the streak, withevent.repeat_countincrementing each time. The final gift in a streak carriesevent.repeat_end == 1. Use theevent.streakinghelper to filter intermediate events out and only act on the final one.
@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
gift = event.gift
if gift is None:
return
# Streakable gift & streak is over
if not event.streaking and gift.type == 1: # ``type == 1`` is streakable
print(f"{event.user.unique_id} sent {event.repeat_count}x \"{gift.name}\"")
# Non-streakable gift
elif gift.type != 1:
print(f"{event.user.unique_id} sent \"{gift.name}\"")
In v3 the canonical Gift field names are name, type, and image. The
v2-era prefixed names (gift_name, gift_type, gift_image) remain
available as read-only aliases on ExtendedGift for backwards compatibility.
Wrap a Gift in ExtendedGift(...) if you want the .streakable helper.
Checking If A User Is Live
It is considered inefficient to use the connect method to check if a user is live. It is better to use the dedicated await client.is_live() method.
There is a complete example of how to do this in the examples folder.
Star History
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributors
- Isaac Kogan - Creator, Primary Maintainer, and Reverse-Engineering - isaackogan
- Zerody - Creator of the NodeJS library, introduced me to scraping TikTok LIVE - Zerody
See also the full list of secondary contributors who have participated in this project.
1 maintainer
Metadata
1 maintainer
Release files for TikTokLive 7.0.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tiktoklive-7.0.0a1.tar.gz | 67.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tiktoklive-7.0.0a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 141.9 kB
Release files / tiktoklive-7.0.0a1.tar.gz
| Download URL | tiktoklive-7.0.0a1.tar.gz |
|---|---|
| Size | 67.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87802d3eb06ee1df05e772c63c25f2921058eb874ed4052337f7fe8740b64423
|
|
BLAKE2b-256 checksum How to use checksums |
2d8b1f72358cd58fe2efd0cf7c56af357088134c47a002a7f5218984a077dacb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency logRelease files / tiktoklive-7.0.0a1-py3-none-any.whl
| Download URL | tiktoklive-7.0.0a1-py3-none-any.whl |
|---|---|
| Size | 74.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0b20c7b5cd6c5e2f58bb11af7da3e261cd0c31c490d826114f900d11e431b144
|
|
BLAKE2b-256 checksum How to use checksums |
07d470c942cbf63a0935ebde25d1252fead69615d7549ecdf9d342144fc82235
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency log
