TikTok LIVE API — Python

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 Sandbox tier. No credit card required.

🎤 Exclusive: Real-Time Live Captions — AI-powered speech-to-text with translation & speaker diarization. No other TikTok library offers this.

🚀 One-Command Quick Start

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

---

Table of Contents

• Why tiktok-live-api?
• Getting Started
• Try It Now — 5-Minute Demo
• Events
• Live Captions (AI STT)
• Async Usage
• Chat Bot Example
• Other Languages
• Pricing
• Star History
• License

---

🆚 Why tiktok-live-api?

	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	✅ 50 req/day, 5-min WS	✅ Free (when it works)	✅ Free (when it works)

---

⚡ Getting Started

1. Install

pip install tiktok-live-api

2. Get your free API key

Go to tik.tools → Sign up → Copy your API key. No credit card required.

3. Connect

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.

---

🚀 Try It Now — 5-Minute Live Demo

Copy-paste, run, see real-time TikTok events in your terminal. Works on the free Sandbox tier.

# demo.py — TikTok LIVE in 5 minutes
# pip install tiktok-live-api
from tiktok_live_api import TikTokLive
import signal, sys

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} — listening for 5 min...\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📊 Done! Received {events} events.\n")

# Auto-exit after 5 minutes
if sys.platform != "win32":
    signal.alarm(300)

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} — listening for 5 min...\n")
        try:
            async for message in asyncio.wait_for(ws, timeout=300):
                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}")
        except asyncio.TimeoutError:
            pass
    print(f"\n📊 Done! Received {events} events.\n")

asyncio.run(listen())

---

📋 Events

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.

Battle / PK example

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

---

🎤 Live Captions (Speech-to-Text)

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

Caption Events

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

---

🔄 Async Usage

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

---

🤖 Chat Bot Example

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

---

🌐 Other Languages

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

---

Environment Variable

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

---

💰 Pricing

Tier	Requests/Day	WS Connections	WS Duration	Price
Sandbox	50	1	5 min	Free
Basic	10,000	3	8 hours	$9/wk +tax
Pro	75,000	50	8 hours	$19/wk +tax
Ultra	300,000	250	8 hours	$58/wk +tax

Full plan details at tik.tools/pricing. Highlights:

• Sandbox ($0): 50 req/day · 1 WS (5 min limit) · basic endpoints · signatures included
• Basic ($9/wk): 10K req/day · 3 WS · all endpoints · 1 AI caption stream
• Pro ($19/wk, most popular): 75K req/day · 50 WS · all endpoints · 5 AI caption streams · priority routing · chat support
• Ultra ($58/wk): 300K req/day · 250 WS · 20 AI caption streams · League Rankings API (Ultra only) · 99.5% uptime SLA · priority chat support

Get your free API key → tik.tools

---

Star History

If this project helps you, please consider giving it a ⭐ — it helps others discover it!

---

Links

• 🌐 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

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

• TikTool — Creator & Maintainer — tik.tools

See also the full list of contributors who have participated in this project.