FeedbackGet API access

Developer API

TikTok LIVE API in Python

The toktik package is the official Python client for the Toktik Developer API. REST calls need no dependencies; the realtime client adds one (websockets). This guide goes from pip install to a streaming gift counter.

Updated

Package: toktik 0.3.1 on PyPI

1. Install

shell
pip install toktik                # REST only — zero dependencies

For the realtime stream add the extra:

shell
pip install "toktik[realtime]"    # adds websockets for the realtime client

2. Authenticate

Create an API key (see the quickstart) and keep it out of source control — read it from an environment variable. Give the key only the scopes it needs, for example rank:read for rankings.

Python
import os
from toktik import TokTikClient

client = TokTikClient(api_key=os.environ["TOKTIK_API_KEY"])

3. Fetch rankings

The official ranking boards (hourly, daily, Popular LIVE, gaming, LIVE Shopping and the A1–D5 League) are one call. On the free tier creator identities below the open top rows are masked; rank, score and movement always show.

Python
board = client.rankings.official(board="hourly", region="VN")
for row in board["data"]["board"]["entries"][:3]:
    print(row["rank"], row["nickname"], row["score"])

perf = client.live.creator_performance("some.creator", limit=20)

4. Stream gifts in realtime

Subscribe to the creators you follow and receive decoded events as they happen. The client mints and refreshes the handshake token and resumes your subscriptions after a reconnect. Realtime is metered per room-minute. A free key can hold 1 connection and 100 room-minutes a month; paid tiers raise both. See the realtime reference for every frame and event type.

Python
import asyncio
from toktik import TokTikClient

async def main():
    client = TokTikClient(api_key="ttk_live_...")
    async for frame in await client.live.stream(["@creator_handle"]):
        if frame.type == "status":
            print("status", frame.creator_id, frame.status)
        elif frame.type == "event" and frame.event == "gift":
            g = frame.data["decoded"]
            if g.get("isCompleted"):
                print(g["gift"]["giftName"], g["gift"]["diamondCount"] * g["repeatCount"])

asyncio.run(main())

5. Handle errors and limits

One typed error covers every failure. 402 means out of credits, 403 a missing scope, and 429 or 5xx are safe to retry with back-off.

Python
from toktik import TokTikApiError

try:
    client.creators.get("someone")
except TokTikApiError as err:
    if err.is_payment_required:   # 402 — top up credits
        ...
    elif err.is_forbidden:        # 403 — missing scope
        ...
    elif err.retryable:           # 429 / 5xx — back off and retry
        ...

A complete script

Put it together: set TOKTIK_API_KEY, run it, and you get the top of the Vietnam hourly board.

Python — complete (guide.py)
import os
import sys

from toktik import TokTikApiError, TokTikClient

client = TokTikClient(api_key=os.environ["TOKTIK_API_KEY"])

try:
    board = client.rankings.official(board="hourly", region="VN")
    rows = board["data"]["board"]["entries"]
    print(f"{len(rows)} creators on the VN hourly board")
    for row in rows[:3]:
        print(row["rank"], row["nickname"], row["score"])
except TokTikApiError as err:
    if err.is_payment_required:
        sys.exit("out of credits (402): top up or wait for the cycle")
    if err.is_forbidden:
        sys.exit("this key lacks the rank:read scope (403)")
    raise

Frequently asked questions

How do I get TikTok LIVE data in Python?

Install toktik (pip install toktik), create a Toktik API key, and call the client: rankings, gifters, agencies, creator performance and a realtime stream are all methods on one client. Each response includes the provenance (when and from what source the data was observed).

Does the Python SDK support async and realtime?

The REST client is synchronous and has no dependencies. Realtime is async: install the realtime extra (pip install "toktik[realtime]") and iterate client.live.stream(...) with async for. The stream refreshes its handshake token and resumes subscriptions after a reconnect.

How are errors and rate limits reported?

As HTTP status codes in a typed error: 402 means out of credits, 403 a missing scope, 429 a rate limit (with Retry-After) and 5xx a server fault. The error object tells you whether a retry is safe, so one handler covers every call.

Is this the official TikTok API?

No. It is Toktik's own API for the public TikTok LIVE data Toktik observes. Toktik is independent and not affiliated with TikTok.

TikTok LIVE API overviewNode.js guideAPI reference

Toktik is independent and not affiliated with TikTok.