tiktok-live-api 1.0.2

Unofficial TikTok LIVE API Client — Real-time chat, gifts, viewers, battles, and live captions from any TikTok livestream via the TikTool managed API.

tiktok-live-api

Unofficial TikTok LIVE API Client for Python — Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, viewer counts, battles, and more. Powered by the TikTool managed API.

This package is not affiliated with or endorsed by TikTok. It connects to the TikTool Live managed API service — 99.9% uptime, no reverse engineering, no maintenance required. Also available for Node.js and any language via WebSocket.

Install

pip install tiktok-live-api

Quick Start

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("like")
def on_like(event):
    print(f"{event['user']['uniqueId']} liked (total: {event['totalLikes']})")

@client.on("follow")
def on_follow(event):
    print(f"{event['user']['uniqueId']} followed!")

@client.on("roomUserSeq")
def on_viewers(event):
    print(f"{event['viewerCount']} viewers watching")

client.run()

That's it. No complex setup, no protobuf, no reverse engineering.

---

🚀 Try It Now — 60-Second Live Demo

Copy-paste this into a file and run it. Connects to a live TikTok stream, prints every event for 60 seconds, then exits. Works on the free Sandbox tier.

Save as demo.py and run with python demo.py:

# demo.py — TikTok LIVE in 60 seconds
# pip install tiktok-live-api
from tiktok_live_api import TikTokLive
import signal

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 60s...\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")

signal.alarm(60)  # Auto-exit after 60s (Linux/macOS)
client.run()

🔌 Pure WebSocket version (no SDK)

# ws-demo.py — Pure WebSocket, zero SDK
# 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 60s...\n")
        try:
            async for message in asyncio.wait_for(ws, timeout=60):
                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', '')} ({data.get('diamondCount', 0)}💎)")
                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)}")
                elif event == "roomInfo":  print(f"📡 Room: {msg.get('roomId', '')}")
                else:                      print(f"📦 {event}")
        except asyncio.TimeoutError:
            pass
    print(f"\n📊 Done! Received {events} events.\n")

asyncio.run(listen())

---

Get a Free API Key

1. Go to tik.tools
2. Sign up (no credit card required)
3. Copy your API key

The free Sandbox tier gives you 50 requests/day and 1 WebSocket connection.

Environment Variable

Instead of passing api_key directly, you can set it as an environment variable:

# Linux / macOS
export TIKTOOL_API_KEY=your_api_key_here

# Windows (CMD)
set TIKTOOL_API_KEY=your_api_key_here

# Windows (PowerShell)
$env:TIKTOOL_API_KEY="your_api_key_here"

python my_bot.py

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

Events

Event	Description	Key Fields
chat	Chat message	user, comment, emotes
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	viewerCount, topViewers
battle	Battle event	type, teams, scores
envelope	Treasure chest	diamonds, user
streamEnd	Stream ended	reason
connected	Connected	uniqueId
disconnected	Disconnected	uniqueId
error	Error occurred	error
event	Catch-all	Full raw event

Live Captions (Speech-to-Text)

Transcribe and translate any TikTok LIVE stream in real-time. This feature is unique to TikTool Live — no other service offers it.

from tiktok_live_api import TikTokCaptions

captions = TikTokCaptions(
    "streamer_username",
    api_key="YOUR_API_KEY",
    translate="en",       # translate to English
    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()

Async Usage

For integration with async frameworks (FastAPI, aiohttp, 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()

Why tiktok-live-api?

	tiktok-live-api	TikTokLive (Python)	tiktok-live-connector (Node.js)
Stability	✓ Managed API, 99.9% uptime	✗ Breaks on TikTok updates	✗ Breaks on TikTok updates
Live Captions	✓ AI speech-to-text	✗	✗
Maintenance	✓ Zero — we handle it	✗ You fix breakages	✗ You fix breakages
CAPTCHA Solving	✓ Built-in (Pro+)	✗	✗
Feed Discovery	✓ See who's live	✗	✗
Free Tier	✓ 50 requests/day	✓ Free (unreliable)	✓ Free (unreliable)

Pricing

Tier	Requests/Day	WebSocket Connections	Price
Sandbox	50	1 (60s)	Free
Basic	10,000	3 (8h)	$7/week
Pro	75,000	50 (8h)	$15/week
Ultra	300,000	500 (8h)	$45/week

Also Available

• Node.js/TypeScript: npm install @tiktool/live
• Any language: Connect via WebSocket: wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY
• Unreal Engine: Native C++/Blueprint plugin

Links

• Website: tik.tools
• Documentation: tik.tools/docs
• Python Guide: tik.tools/guides/python-tiktok-live
• GitHub: github.com/tiktool/live-python
• npm (Node.js): @tiktool/live

License

MIT