TikTok LIVE API — Node.js & TypeScript

The managed TikTok Live Connector — receive chat, gifts, viewers, battles & 18+ events from any TikTok LIVE stream via WebSocket.

99.9% uptime — Never breaks when TikTok updates. No protobuf, no reverse engineering, no maintenance. Also available for Python, Java, Go, C#, and any language via WebSocket.

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

Try It Now · Events · Live Captions · API · Rate Limits · Get API Key

⚡ Quick Start

npm install @tiktool/live

Get your free API key at tik.tools — then run the demo below.

🚀 Try It Now — 5-Minute Live Demo

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

Save as demo.mjs and run with node demo.mjs:

// demo.mjs — TikTok LIVE in 5 minutes
// npm install @tiktool/live
import { TikTokLive } from '@tiktool/live';

const API_KEY       = 'YOUR_API_KEY';        // Get free key → https://tik.tools
const LIVE_USERNAME = 'tv_asahi_news';       // Any live TikTok username

const live = new TikTokLive({ uniqueId: LIVE_USERNAME, apiKey: API_KEY });
let events = 0;

live.on('chat',        e => { events++; console.log(`💬 ${e.user.uniqueId}: ${e.comment}`); });
live.on('gift',        e => { events++; console.log(`🎁 ${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount}💎)`); });
live.on('like',        e => { events++; console.log(`❤️  ${e.user.uniqueId} liked × ${e.likeCount}`); });
live.on('member',      e => { events++; console.log(`👋 ${e.user.uniqueId} joined`); });
live.on('follow',      e => { events++; console.log(`➕ ${e.user.uniqueId} followed`); });
live.on('share',       e => { events++; console.log(`🔗 ${e.user.uniqueId} shared`); });
live.on('roomUserSeq', e => { events++; console.log(`👀 Viewers: ${e.viewerCount}`); });
live.on('subscribe',   e => { events++; console.log(`⭐ ${e.user.uniqueId} subscribed`); });
live.on('battle',      e => { events++; console.log(`⚔️  Battle update`); });

live.on('connected',   () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
live.on('disconnected', () => console.log(`\n📊 Done! Received ${events} events.\n`));

await live.connect();
setTimeout(() => { live.disconnect(); }, 300_000);

// ws-demo.mjs — Pure WebSocket, zero SDK
// npm install ws
import WebSocket from 'ws';

const API_KEY       = 'YOUR_API_KEY';
const LIVE_USERNAME = 'tv_asahi_news';

const ws = new WebSocket(`wss://api.tik.tools?uniqueId=${LIVE_USERNAME}&apiKey=${API_KEY}`);
let events = 0;

ws.on('open', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
ws.on('message', (raw) => {
  const msg = JSON.parse(raw);
  events++;
  const d = msg.data || {};
  const user = d.user?.uniqueId || d.uniqueId || '';
  switch (msg.event) {
    case 'chat':        console.log(`💬 ${user}: ${d.comment}`); break;
    case 'gift':        console.log(`🎁 ${user} sent ${d.giftName} (${d.diamondCount}💎)`); break;
    case 'like':        console.log(`❤️  ${user} liked × ${d.likeCount}`); break;
    case 'member':      console.log(`👋 ${user} joined`); break;
    case 'roomUserSeq': console.log(`👀 Viewers: ${d.viewerCount}`); break;
    case 'roomInfo':    console.log(`📡 Room: ${msg.roomId}`); break;
    default:            console.log(`📦 ${msg.event}`); break;
  }
});
ws.on('close', () => console.log(`\n📊 Done! Received ${events} events.\n`));

setTimeout(() => ws.close(), 300_000);

How It Works

    Your App                    tik.tools                    TikTok
  +-----------+              +--------------+           +--------------+
  |          -+-- sign_url --> Signs URL    |           |              |
  |  Your   <-+-- X-Bogus --|  with params |           |   TikTok     |
  |  Code    |              |              |           |   WebSocket  |
  |          -+------------ Connect directly ---------->|   Server     |
  |          <-+------------ Live events (protobuf) <---|              |
  +-----------+              +--------------+           +--------------+
                            ^ Only interaction             ^ Direct from
                              with our server                YOUR IP

• Your app connects directly to TikTok — from your IP or through a proxy
• The sign server only generates cryptographic signatures (requires API key)
• TikTok never sees the sign server
• Built-in protobuf parser, no external dependencies

Events

Listening

live.on('chat', (event) => {
    event.user.uniqueId  // string
    event.comment        // string
});

live.on('event', (event) => {
    console.log(event.type, event);
});

Reference

Connection Events

🎤 Real-Time Live Captions

AI-powered speech-to-text transcription and translation for TikTok LIVE streams. Features include:

• Auto-detect language — Automatically identifies the spoken language
• Speaker diarization — Identifies individual speakers in multi-person streams
• Real-time translation — Translate to any supported language with sub-second latency
• Partial + final results — Get streaming partial transcripts and confirmed final text
• Credit-based billing — 1 credit = 1 minute of transcription/translation

Quick Start

import { TikTokCaptions } from '@tiktool/live';

const captions = new TikTokCaptions({
    uniqueId: 'streamer_name',
    apiKey: 'YOUR_API_KEY',
    translate: 'en',
    diarization: true,
});

captions.on('caption', (event) => {
    const prefix = event.speaker ? `[${event.speaker}] ` : '';
    console.log(`${prefix}${event.text}${event.isFinal ? ' ✓' : '...'}`);
});

captions.on('translation', (event) => {
    console.log(`  → ${event.text}`);
});

captions.on('credits', (event) => {
    console.log(`${event.remaining}/${event.total} min remaining`);
});

captions.on('credits_low', (event) => {
    console.warn(`Low credits! ${event.remaining} min left`);
});

await captions.start();

new TikTokCaptions(options)

Caption Events

Methods

Raw WebSocket

You can also connect directly via WebSocket without the SDK:

wss://api.tik.tools/captions?uniqueId=USERNAME&apiKey=YOUR_KEY&translate=en&diarization=true&max_duration_minutes=120

Caption Credits

Caption credits are pay-as-you-go add-ons — no credits are included in the base subscription. Requires Basic tier or higher.

1 credit = 1 minute of audio transcribed/translated into one language. If translating to 2 languages simultaneously, it burns 2 credits per minute.

Try the live demo at tik.tools/captions — see real-time transcription and translation on actual TikTok LIVE streams.

API Reference

new TikTokLive(options)

Methods

Rate Limits

All API requests require an API key. Get yours at tik.tools.

Caption Credits are available as pay-as-you-go add-ons (1 credit = 1 min of audio in 1 language):

• Starter: 1,000 credits — $10
• Creator: 5,000 credits — $35
• Agency: 20,000 credits — $100

The SDK calls the sign server once per connection, then stays connected via WebSocket. Sandbox is for API verification only — use Basic or higher for production.

🔍 Feed Discovery

Discover recommended TikTok LIVE streams. Requires Pro or Ultra tier.

import { getLiveFeed, fetchFeed } from '@tiktool/live';

// Option 1: Two-step (sign-and-return)
const signed = await getLiveFeed({
    apiKey: 'YOUR_PRO_KEY',
    sessionId: 'YOUR_TIKTOK_SESSIONID',
    region: 'US',
    count: 10,
});

const resp = await fetch(signed.signed_url, {
    headers: { ...signed.headers, Cookie: signed.cookies || '' },
});
const data = await resp.json();

// Option 2: One-step convenience
const feed = await fetchFeed({
    apiKey: 'YOUR_PRO_KEY',
    sessionId: 'YOUR_TIKTOK_SESSIONID',
    count: 10,
});

for (const entry of feed.data || []) {
    const room = entry.data;
    console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
}

Channel Types

Pagination

Use maxTime from the previous response to load more:

const page2 = await getLiveFeed({
    apiKey: 'YOUR_PRO_KEY',
    sessionId: 'YOUR_TIKTOK_SESSIONID',
    maxTime: data.extra?.max_time, // cursor from previous response
});

🏆 Regional Leaderboard

Get daily, hourly, popular, or league LIVE rankings for any streamer. Requires Pro or Ultra tier.

This endpoint uses a two-step sign-and-return pattern because TikTok sessions are IP-bound:

1. Call getRegionalRanklist() to get a signed URL from the server
2. POST the signed URL from your own IP with your TikTok session cookie

import { getRegionalRanklist } from '@tiktool/live';

const signed = await getRegionalRanklist({
    apiKey: 'YOUR_PRO_KEY',
    roomId: '7607695933891218198',
    anchorId: '7444599004337652758',
    rankType: '8',
});

const resp = await fetch(signed.signed_url, {
    method: signed.method,
    headers: { ...signed.headers, Cookie: `sessionid=YOUR_SID; ${signed.cookies}` },
    body: signed.body,
});

const { data } = await resp.json();
data.rank_view.ranks.forEach((r: any, i: number) =>
    console.log(`${i+1}. ${r.user.nickname} — ${r.score} pts`)
);

Rank Types

Examples

Chat Bot

import { TikTokLive } from '@tiktool/live';

const live = new TikTokLive({
    uniqueId: 'streamer_name',
    apiKey: 'YOUR_API_KEY',
});

live.on('chat', (e) => {
    if (e.comment.toLowerCase() === '!hello') {
        console.log(`Hello, ${e.user.nickname}!`);
    }
});

live.on('gift', (e) => {
    if (e.repeatEnd) {
        console.log(`${e.user.uniqueId} sent ${e.repeatCount}x ${e.giftName} (${e.diamondCount * e.repeatCount} diamonds)`);
    }
});

await live.connect();

OBS Overlay

import { TikTokLive } from '@tiktool/live';
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });
const live = new TikTokLive({
    uniqueId: 'streamer_name',
    apiKey: 'YOUR_API_KEY',
});

live.on('event', (event) => {
    for (const client of wss.clients) {
        client.send(JSON.stringify(event));
    }
});

await live.connect();
console.log('Forwarding events to ws://localhost:8080');

🌐 Proxy Support

Route all connections through an HTTP proxy. Works with any HTTPS proxy provider (residential, datacenter, etc.).

import { TikTokLive } from '@tiktool/live';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://user:pass@proxy.example.com:1234');

const live = new TikTokLive({
    uniqueId: 'streamer_name',
    apiKey: 'YOUR_API_KEY',
    agent,
});

await live.connect();

Both the initial page request and the WebSocket connection are routed through the proxy. This is useful for:

• Running multiple concurrent connections from different IPs
• Avoiding rate limits
• Geo-targeting specific regions

TypeScript

Full TypeScript support with type inference:

import { TikTokLive, ChatEvent, GiftEvent } from '@tiktool/live';

const live = new TikTokLive({
    uniqueId: 'username',
    apiKey: 'YOUR_API_KEY',
});

live.on('chat', (event: ChatEvent) => {
    const username: string = event.user.uniqueId;
    const message: string = event.comment;
});

live.on('gift', (event: GiftEvent) => {
    const diamonds: number = event.diamondCount;
    const isCombo: boolean = event.combo;
});

License

MIT © tiktool