Agency rank feeds in Discord: gaming ranks, creator ranks and 99+ movers across all 30 regions, copy-paste usernames for backstage. /ranks to start (Global Agency).

TikTok LIVE API for Python

tiktok-live-api is the most complete, production-managed TikTok LIVE API for Python. Receive real-time chat, gifts, likes, viewers, follows, shares and battle events from any TikTok LIVE stream over a single WebSocket, with an Unreal Engine plugin and SDKs in multiple languages. Managed signing works out of the box: no third-party sign server, no keys to configure. 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, CAPTCHA solving, and more. Sandbox: free 7-day evaluation. No credit card required.

Why tik.tools

The premium managed alternative for TikTok LIVE data. What you get out of the box:

• Managed signing infrastructure. Signing runs on our servers and works immediately - no third-party sign server to run, no separate key to configure.
• Unreal Engine plugin. Drive avatars, overlays and gameplay directly from live chat, gifts and battles.
• Agency and leaderboard intelligence. Gifter leaderboards, gaming and creator ranks across regions, and eligible-creator discovery.
• Multi-language SDKs. First-class Python and Node.js clients plus a plain WebSocket API for any language.
• Sandbox: free 7-day evaluation. Build and test for 7 days from account creation, then move to a paid plan (Basic and up) to keep going.

🚀 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 - Live Demo
• Events
• Live Captions (legacy)
• Async Usage
• Chat Bot Example
• Other Languages
• Pricing
• Star History
• License

🆚 Why tiktok-live-api?

⚡ Getting Started

1. Install

pip install tiktok-live-api

2. Get an API key

Go to tik.tools → Sign up → Copy your API key. No credit card required for the 7-day Sandbox evaluation; after that, pick a plan at tik.tools/pricing.

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 - Live Demo

Copy-paste, run, see real-time TikTok events in your terminal. Works on Sandbox during the 7-day evaluation (2 hours per WebSocket connection) and on every paid plan. 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 an API key → https://tik.tools/pricing
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. Sandbox caps each WebSocket connection at 2 hours.
client.run()

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

REST API - leaderboards, recruiting, profiles, gifts

The WebSocket client streams live events. For everything else - leaderboards, gaming ranks, recruiting, live status, gift catalogs, profiles - use the TikTool REST client. Async, one method per endpoint, no extra dependencies.

import asyncio
from tiktok_live_api import TikTool, TikToolError

async def main():
    api = TikTool(api_key="YOUR_KEY")

    # Live status (single + bulk)
    await api.live_status("charlidamelio")
    await api.bulk_live_check(["user1", "user2", "user3"])

    # Leaderboards + rankings
    await api.leaderboard(region="US+")
    await api.ranklist_gaming("US+")
    await api.region_movers("US+")            # entered top today, below cutoff now

    # Recruiting (Global Agency) - find eligible creators
    recruits = await api.eligible_creators(region="US+", limit=50, min_score=1000)

    # Profiles + gifts
    await api.profile_info("khaby.lame")
    await api.gifts_by_country("US")

asyncio.run(main())

Tier gating is enforced server-side: a call above your tier raises TikToolError with .status == 403. Any endpoint not yet wrapped is reachable via await api.request("/webcast/...", query={...}).

try:
    await api.eligible_creators(region="US+")
except TikToolError as e:
    if e.status == 403:
        print("Upgrade required:", e)

See the full endpoint + tier matrix.

📋 Events (54 v3 event types)

Every event is dispatched by name. Each event payload extends the BaseEvent shape (type, timestamp, msgId, optional protoVersion: 1 | 2 | 3).

Core live events

PK / battle events

Native captions (v3)

Creator-side events

Moderation / safety

Gift catalog + ecommerce

Engagement + AI

Catch-all

• event - Fires for every decoded event.
• unknown - Fires when TikTok ships a method we don't yet model (forward-compat hook).

All events ship with full TypedDict annotations. Your IDE shows autocompletion for every field. See full per-event JSON examples + field tables.

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

The Live Captions service is no longer offered to new customers. It remains available for existing caption customers, and the TikTokCaptions client stays in this package for them. For free captions on any stream, use the caption event from TikTok native captions (see Native captions above).

from tiktok_live_api import TikTokCaptions

captions = TikTokCaptions("streamer_username", api_key="YOUR_API_KEY", translate="en")

@captions.on("caption")
def on_caption(event):
    print(event["text"])

captions.run()

Caption Events (legacy)

🔄 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:

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 and limits (USD)

Full pricing + checkout: https://tik.tools/pricing

Tiers

Tier ladder (each includes everything below it): Sandbox -> Basic -> Pro -> Ultra -> Global Agency. Sandbox is a free 7-day evaluation (counted from account creation) with reduced rate limits + masked identifiers on intelligence endpoints; after 7 days the key is refused (WebSocket close 4401, REST 403) until the account moves to Basic or higher; paid tiers raise limits and unmask data. Outgoing webhooks need Basic+. The agency intelligence endpoints (gaming ranks, movers, eligible-creator finder, gifter intel) need Global Agency.

Endpoints and required tier

Full docs with request/response shapes and examples: https://tik.tools/docs

What you get

Creators: real-time live events (gifts, chat, viewers), your own live status + room info, earnings + analytics, signed CDN/stream URLs that do not expire. Developers: drop-in signing (works as a tiktok-live-connector backend - point the sign base at api.tik.tools), one-WebSocket fan-out (your IP never touches TikTok), bulk live checks, leaderboards, webhooks (HMAC-signed live.start/live.end and more), SDKs across languages. Agencies (Global Agency): TikTok LIVE gaming ranks + creator ranks + 99+ movers across all 30 regions, eligible-creator recruiting finder, gifter intelligence (top gifters, profiles, leaderboards), and the Discord bot that posts copy-paste username batches for backstage.

Live Gifter Firehose - Global Agency

Real-time gift event stream. 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&region=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 an API key → tik.tools/pricing (7-day free evaluation)

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.