The managed TikTok Live connector for Python - receive chat, gifts, viewers, battles & 18+ events from any TikTok LIVE stream. Zero maintenance, zero breakages.
99.9% uptime - Never breaks when TikTok updates. No protobuf, no reverse engineering, no maintenance required. Powered by the TikTool managed WebSocket API.
 |
TikTool offers a fully managed TikTok LIVE API - real-time events, AI captions, CAPTCHA solving, and more. Free Community tier (forever). No credit card required. |
🎤 Exclusive: Real-Time Live Captions - AI-powered speech-to-text with translation & speaker diarization. No other TikTok library offers this.
Instantly connect to a live TikTok stream and print real-time events to your terminal.
pip install tiktok-live-api
python -m tiktok_live_api
Or connect to a specific stream: python -m tiktok_live_api @username
- Why tiktok-live-api?
- Getting Started
- Try It Now - Live Demo
- Events
- Live Captions (AI STT)
- Async Usage
- Chat Bot Example
- Other Languages
- Pricing
- Star History
- License
| tiktok-live-api | TikTokLive (isaackogan) | TikTok-Live-Connector (Node.js) | |
|---|---|---|---|
| Stability | ✅ Managed API, 99.9% uptime | ❌ Breaks on TikTok updates | ❌ Breaks on TikTok updates |
| Setup | ✅ 3 lines of code | ❌ Protobuf + reverse engineering | ❌ Protobuf + signing server |
| Live Captions (AI STT) | ✅ Real-time speech-to-text | ❌ Not available | ❌ Not available |
| Translation | ✅ 50+ languages | ❌ Not available | ❌ Not available |
| CAPTCHA Solving | ✅ Built-in (Pro+) | ❌ Manual | ❌ Manual |
| Feed Discovery | ✅ See who's live | ❌ Not available | ❌ Not available |
| Maintenance | ✅ Zero - we handle everything | ❌ You fix breakages | ❌ You fix breakages |
| Multi-Language | ✅ Python, Node.js, Java, Go, C# | Python only | Node.js only |
| Free Tier | ✅ 2,500 req/day, 15 WS, 2h per WS | ✅ Free (when it works) | ✅ Free (when it works) |
pip install tiktok-live-api
Go to tik.tools → Sign up → Copy your API key. No credit card required.
from tiktok_live_api import TikTokLive
client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
@client.on("chat")
def on_chat(event):
print(f"{event['user']['uniqueId']}: {event['comment']}")
@client.on("gift")
def on_gift(event):
print(f"{event['user']['uniqueId']} sent {event['giftName']} ({event['diamondCount']} 💎)")
@client.on("roomUserSeq")
def on_viewers(event):
print(f"Viewers: {event['viewerCount']}")
client.run()
That's it. No protobuf, no signing servers, no reverse engineering, no breakages.
Copy-paste, run, see real-time TikTok events in your terminal. Works on the free Community tier - 2h per WS, runs as long as the stream is live.
# demo.py - TikTok LIVE in real time
# pip install tiktok-live-api
from tiktok_live_api import TikTokLive
API_KEY = "YOUR_API_KEY" # Get free key → https://tik.tools
LIVE_USERNAME = "tv_asahi_news" # Any live TikTok username
client = TikTokLive(LIVE_USERNAME, api_key=API_KEY)
events = 0
@client.on("connected")
def on_connected(event):
print(f"\n✅ Connected to @{LIVE_USERNAME} - streaming events...\n")
@client.on("chat")
def on_chat(event):
global events; events += 1
print(f"💬 {event['user']['uniqueId']}: {event['comment']}")
@client.on("gift")
def on_gift(event):
global events; events += 1
print(f"🎁 {event['user']['uniqueId']} sent {event['giftName']} ({event.get('diamondCount', 0)}💎)")
@client.on("like")
def on_like(event):
global events; events += 1
print(f"❤️ {event['user']['uniqueId']} liked × {event.get('likeCount', 0)}")
@client.on("member")
def on_member(event):
global events; events += 1
print(f"👋 {event['user']['uniqueId']} joined")
@client.on("roomUserSeq")
def on_viewers(event):
global events; events += 1
print(f"👀 Viewers: {event['viewerCount']}")
@client.on("disconnected")
def on_disconnect(event):
print(f"\n📊 Disconnected. Received {events} events.\n")
# Press Ctrl+C to stop. Community tier caps each WebSocket at 2 hours.
client.run()
🔌 Pure WebSocket version (no SDK)
# ws-demo.py - Pure WebSocket, zero dependencies
# pip install websockets
import asyncio, websockets, json
API_KEY = "YOUR_API_KEY"
LIVE_USERNAME = "tv_asahi_news"
async def listen():
url = f"wss://api.tik.tools?uniqueId={LIVE_USERNAME}&apiKey={API_KEY}"
events = 0
async with websockets.connect(url) as ws:
print(f"\n✅ Connected to @{LIVE_USERNAME} - streaming events...\n")
async for message in ws:
msg = json.loads(message)
events += 1
data = msg.get("data", {})
user = data.get("user", {}).get("uniqueId", "")
event = msg.get("event", "")
if event == "chat": print(f"💬 {user}: {data.get('comment', '')}")
elif event == "gift": print(f"🎁 {user} sent {data.get('giftName', '')}")
elif event == "like": print(f"❤️ {user} liked × {data.get('likeCount', 0)}")
elif event == "member": print(f"👋 {user} joined")
elif event == "roomUserSeq": print(f"👀 Viewers: {data.get('viewerCount', 0)}")
else: print(f"📦 {event}")
print(f"\n📊 Disconnected. Received {events} events.\n")
asyncio.run(listen())
| Event | Description | Key Fields |
|---|---|---|
chat |
Chat message | user, comment, emotes, starred? |
gift |
Virtual gift | user, giftName, diamondCount, repeatCount |
like |
Like event | user, likeCount, totalLikes |
follow |
New follower | user |
share |
Stream share | user |
member |
Viewer joined | user |
subscribe |
New subscriber | user |
roomUserSeq |
Viewer count update | viewerCount, topViewers |
battle |
PK start / end / status change | battleId, status (1=ACTIVE / 2=STARTING / 3=ENDED / 4=PREPARING), battleDuration, teams |
battleArmies |
Live PK score update | battleId, status, matchId, sessionId, durationSec, secsRemaining, hosts[] - each host has teamTotalScore + contributors[] (MVP first) |
battleItemCard |
Booster multipliers, gloves, mist, match-guide, thunder, extra-time | effect ('gloves' / 'mist' / 'booster_x2' / 'booster_x3' / 'match_guide' / ...), multiplier (2 or 3), senderUserId, senderNickname, activatedAtSec, durationSec, endsAtSec, commentTemplate |
roomPin |
Pinned/starred message | user, comment, action, durationSeconds |
envelope |
Treasure chest | diamonds, user |
streamEnd |
Stream ended | reason |
connected |
WebSocket connected | uniqueId |
disconnected |
WebSocket disconnected | uniqueId |
error |
Error occurred | error |
event |
Catch-all (every event) | Full raw event payload |
All events include the full raw TikTok payload, giving you access to every field TikTok provides.
from tiktok_live_api import TikTokLive
client = TikTokLive(unique_id="creator_username", api_key="tk_...")
@client.on("battle")
def on_battle(e):
print(f"PK status={e['status']} id={e['battleId']} duration={e['battleDuration']}s")
@client.on("battleArmies")
def on_armies(e):
print(f"Countdown: {e.get('secsRemaining')}s")
for host in e.get("hosts", []):
print(f" @{host['hostUserId']} total={host['teamTotalScore']}")
if host["contributors"]:
mvp = host["contributors"][0]
print(f" MVP {mvp['nickname']} score={mvp['score']}")
@client.on("battleItemCard")
def on_card(e):
if e["multiplier"] > 0:
print(f"x{e['multiplier']} booster from @{e['senderUniqueId']}")
else:
print(f"Effect {e['effect']} from @{e['senderUniqueId']} ({e['durationSec']}s)")
client.connect()
Transcribe and translate any TikTok LIVE stream in real-time. This feature is unique to TikTool - no other TikTok library offers it.
from tiktok_live_api import TikTokCaptions
captions = TikTokCaptions(
"streamer_username",
api_key="YOUR_API_KEY",
translate="en", # translate to English (50+ languages)
diarization=True, # identify who is speaking
)
@captions.on("caption")
def on_caption(event):
speaker = event.get("speaker", "")
text = event["text"]
is_final = event.get("isFinal", False)
print(f"[{speaker}] {text}{' ✓' if is_final else '...'}")
@captions.on("translation")
def on_translation(event):
print(f" → {event['text']}")
captions.run()
| Event | Description | Key Fields |
|---|---|---|
caption |
Real-time caption text | text, speaker, isFinal, language |
translation |
Translated caption | text, sourceLanguage, targetLanguage |
credits |
Credit balance update | total, used, remaining |
For integration with async frameworks (FastAPI, Django Channels, etc.):
import asyncio
from tiktok_live_api import TikTokLive
async def main():
client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
@client.on("chat")
async def on_chat(event):
print(f"{event['user']['uniqueId']}: {event['comment']}")
await client.connect()
asyncio.run(main())
from tiktok_live_api import TikTokLive
client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
gift_leaderboard = {}
message_count = 0
@client.on("chat")
def on_chat(event):
global message_count
message_count += 1
msg = event["comment"].lower().strip()
user = event["user"]["uniqueId"]
if msg == "!hello":
print(f">> BOT: Welcome {user}! 👋")
elif msg == "!stats":
print(f">> BOT: {message_count} messages, {len(gift_leaderboard)} gifters")
elif msg == "!top":
top = sorted(gift_leaderboard.items(), key=lambda x: -x[1])[:5]
for i, (name, diamonds) in enumerate(top):
print(f" {i+1}. {name} - {diamonds} 💎")
@client.on("gift")
def on_gift(event):
user = event["user"]["uniqueId"]
diamonds = event.get("diamondCount", 0)
gift_leaderboard[user] = gift_leaderboard.get(user, 0) + diamonds
client.run()
TikTool Live is available in every major language:
| Language | Package | Install |
|---|---|---|
| Python | tiktok-live-api | pip install tiktok-live-api |
| Node.js / TypeScript | @tiktool/live | npm install @tiktool/live |
| Any Language | WebSocket API | wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY |
Full documentation with examples in Java, Go, C#, cURL → tik.tools/docs
Instead of passing api_key directly, set it as an environment variable:
# Linux / macOS
export TIKTOOL_API_KEY=your_api_key_here
# Windows (PowerShell)
$env:TIKTOOL_API_KEY="your_api_key_here"
from tiktok_live_api import TikTokLive
# Automatically reads TIKTOOL_API_KEY from environment
client = TikTokLive("streamer_username")
client.on("chat", lambda e: print(e["comment"]))
client.run()
| Tier | Requests/Day | WS Connections | WS Duration | Price |
|---|---|---|---|---|
| Community | 2,500 | 15 | 2h per WS | Free forever |
| Pro | 75,000 | 50 | 8 hours | from $19/wk +tax |
| Ultra | 300,000 | 250 | 8 hours | from $69/wk +tax |
| Global Agency | 300,000 | 500 + Firehose | 8 hours | $149/wk or $549/mo +tax |
Full plan details at tik.tools/pricing. Highlights:
- Community ($0 forever): 2,500 req/day · 15 WS · 2h per WS · masked leaderboards. Build apps with masked names - upgrade when you need real identities. No datacenter proxies; requests run from your own IP.
- Pro ($19/wk): 75K req/day · 50 WS · unmasked leaderboards · Feed Discovery · 5 AI caption streams · priority routing · chat support
- Ultra ($69/wk): 300K req/day · 250 WS · 20 AI caption streams · League Rankings API unmasked · 99.5% uptime SLA · priority chat support
- Global Agency ($149/wk or $549/mo): Everything in Ultra + Live Gifter Firehose WS (region/league/global filters + min-diamond threshold) + VIP Telegram alerts + VIP Web Vault (unmasked historical visual access)
Real-time gift event stream from our Dragonfly fan-out. Filter by region, league, or globally; cap by minimum diamond threshold.
import asyncio, json, websockets
API_KEY = "tk_..."
URL = f"wss://api.tik.tools/firehose/gifters?apiKey={API_KEY}&mode=region®ion=US%2B&min_diamonds=1000"
async def main():
async with websockets.connect(URL) as ws:
async for raw in ws:
evt = json.loads(raw)
# evt: { type:'gifter_alert', ts, gifter:{username,displayName,isAnonymous},
# creator:{uniqueId}, gift:{name,totalDiamonds}, region }
print(evt)
asyncio.run(main())
Modes: global (all regions), region (single region code), league (region + league class, e.g. B2). Update the filter mid-stream by sending {"type":"update_filter","mode":"global","min_diamonds":5000} - no reconnect needed.
Get your free API key → tik.tools
If this project helps you, please consider giving it a ⭐ - it helps others discover it!
- 🌐 Website: tik.tools
- 📖 Documentation: tik.tools/docs
- 📦 Node.js SDK: @tiktool/live on npm
- 🐍 PyPI: tiktok-live-api
- 💻 GitHub (Node.js): tiktool/tiktok-live-api
This project is licensed under the MIT License - see the LICENSE file for details.
- TikTool - Creator & Maintainer - tik.tools
See also the full list of contributors who have participated in this project.