Metadata-Version: 2.4
Name: TikTokLiveApiSdk
Version: 0.1.1
Summary: TikTok LIVE API SDK for Python. Real-time TikTok LIVE chat, gifts, likes, follows, viewer counts and PK battles via the EulerStream managed TikTok LIVE API, with typed clients for LIVE rooms, creators, gifts, rankings, LIVE alerts, moderation and agencies.
License: MIT
License-File: LICENSE
Keywords: tiktok,tiktok live,tiktok-live,tiktoklive,tiktok live api,tiktok api,tiktok live sdk,tiktok live chat,tiktok live gifts,tiktok live stream,tiktok webcast,tiktok live events,tiktok live alerts,tiktok live moderation,eulerstream,euler stream,livestream,websocket,webcast,api,sdk
Author: EulerStream
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: attrs (>=22.2.0)
Requires-Dist: httpx (>=0.23.1,<0.29.0)
Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
Project-URL: Documentation, https://www.eulerstream.com/docs/intro
Project-URL: Discord, https://www.eulerstream.com/discord
Project-URL: Homepage, https://www.eulerstream.com
Project-URL: Issues, https://github.com/EulerStream/TikTok-Api-Sdk/issues
Project-URL: OpenAPI Reference, https://www.eulerstream.com/docs/openapi
Project-URL: Pricing, https://www.eulerstream.com/pricing
Project-URL: Repository, https://github.com/EulerStream/TikTok-Api-Sdk
Description-Content-Type: text/markdown

# TikTok LIVE API SDK for Python

[![PyPI version](https://img.shields.io/pypi/v/TikTokLiveApiSdk?color=0274b5)](https://pypi.org/project/TikTokLiveApiSdk/)
[![PyPI downloads](https://img.shields.io/pypi/dm/TikTokLiveApiSdk)](https://pypi.org/project/TikTokLiveApiSdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/TikTokLiveApiSdk)](https://pypi.org/project/TikTokLiveApiSdk/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/EulerStream/TikTok-Api-Sdk/blob/master/LICENSE)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2)](https://www.eulerstream.com/discord)

`TikTokLiveApiSdk` is the official Python client for the [EulerStream TikTok LIVE API](https://www.eulerstream.com). Connect to any TikTok LIVE stream by `@username` and receive real-time **chat messages, gifts, likes, follows, shares, viewer counts, room stats and PK battles** over a managed WebSocket, plus fully typed sync and async clients for LIVE rooms, creators, gifts, rankings, LIVE alerts, moderation and agencies.

EulerStream is the managed TikTok LIVE backend behind [TikTokLive](https://github.com/isaackogan/TikTokLive), the most popular Python library for TikTok LIVE. The connection layer is hosted and maintained for you, so your integration keeps working when TikTok changes its webcast protocol.

> Unofficial: this project is not affiliated with, endorsed by, or connected to TikTok or ByteDance.

This package covers TikTok LIVE only. If you also need TikTok user profiles, videos, OAuth, request signing or captcha solving, install [`TikTokApiSdk`](https://pypi.org/project/TikTokApiSdk/) instead: it is the same client with everything in this package plus those.

## Installation

```bash
pip install TikTokLiveApiSdk
```

Requires Python 3.11+. Built on [httpx](https://www.python-httpx.org/) and [attrs](https://www.attrs.org/); every endpoint has `sync`, `sync_detailed`, `asyncio` and `asyncio_detailed` variants and ships with full type hints (`py.typed`).

## TikTok LIVE API quick start

1. [Create a free EulerStream account](https://www.eulerstream.com/register) (no credit card required)
2. Copy your API key from the dashboard
3. Make your first calls:

```python
from TikTokLiveApiSdk import AuthenticatedClient
from TikTokLiveApiSdk.api.tik_tok_live import retrieve_hashtag_list
from TikTokLiveApiSdk.api.tik_tok_live_gifts import retrieve_webcast_gifts
from TikTokLiveApiSdk.api.tik_tok_live_rooms import fetch_webcast_url

client = AuthenticatedClient(base_url="https://api.eulerstream.com", token="YOUR_API_KEY")

with client as c:
    # List the hashtags TikTok LIVE streams are grouped under
    hashtags = retrieve_hashtag_list.sync(client=c)
    print(hashtags.message)

    # Get the TikTok LIVE gift list (names, diamond values, images) as a JSON file to download
    gifts = retrieve_webcast_gifts.sync(client=c)
    print(gifts.url)

    # Fetch the TikTok LIVE WebSocket URL + first payload for a LIVE room (protobuf)
    webcast = fetch_webcast_url.sync_detailed(room_id="7318296342189919018", client=c)
    print(webcast.status_code)
```

The same calls with asyncio:

```python
import asyncio
from TikTokLiveApiSdk import AuthenticatedClient
from TikTokLiveApiSdk.api.tik_tok_live import retrieve_hashtag_list

async def main():
    async with AuthenticatedClient(base_url="https://api.eulerstream.com", token="YOUR_API_KEY") as c:
        hashtags = await retrieve_hashtag_list.asyncio(client=c)
        print(hashtags.message)

asyncio.run(main())
```

Business plans can resolve a LIVE room straight from the creator's `@username` with `TikTokLiveApiSdk.api.tik_tok_live_anchors.fetch_webcast_url_by_unique_id`. `AuthenticatedClient` sends your key in the `X-Api-Key` header; use `TikTokLiveApiSdk.Client` for the handful of routes that allow anonymous access.

## What you can build with the TikTok LIVE API

- **Live stream overlays** for OBS and browser sources showing TikTok LIVE chat, gifts and top gifters
- **Gift and follow alerts** that trigger sounds, animations or webhooks in real time
- **TikTok LIVE games** controlled by chat commands or gifts
- **Chatbots and moderation tools** that respond to and moderate TikTok LIVE chat
- **Analytics dashboards** tracking diamonds, viewer retention and top supporters
- **LIVE monitoring**: bulk "is this creator live?" checks and LIVE start/end alerts for thousands of accounts

## TikTok LIVE API coverage

Every TikTok LIVE path/method in the [EulerStream OpenAPI spec](https://www.eulerstream.com/docs/openapi) becomes a module under `TikTokLiveApiSdk.api.<group>`, so the SDK always matches the live API.

| Module | TikTok LIVE API group |
|---|---|
| `api.tik_tok_live` | Core TikTok LIVE: bulk live checks, webcast feed, hashtag lists, rankings |
| `api.tik_tok_live_anchors` | Creators: webcast URL by `@username`, room info / ID / cover, gift gallery, earnings, moderators, LIVE analytics |
| `api.tik_tok_live_rooms` | LIVE rooms: webcast URL by room ID, room info, room gifts, send chat |
| `api.tik_tok_live_events` | TikTok LIVE event history for a creator |
| `api.tik_tok_live_gifts` | TikTok LIVE gifts: the gift list, search and single-gift lookup |
| `api.tik_tok_live_rankings` | Creator leaderboards, rankings and ranking history |
| `api.tik_tok_live_agencies` | TikTok LIVE agency catalog |
| `api.tik_tok_live_alerts` / `api.tik_tok_live_alert_targets` | TikTok LIVE start/end alerts and webhook targets |
| `api.tik_tok_live_moderation` | Kicks, bans, mutes, sensitive words and comment toggles |
| `api.tik_tok_web_socket_api` | Your cloud WebSocket connections and their state |
| `api.accounts` / `api.authentication` | Your EulerStream account, rate limits, API keys and JWTs |

Moderation and sending chat act as a TikTok account, so those calls take either an OAuth access token or a cookie header. OAuth tokens are issued by the TikTok OAuth routes, which are part of [`TikTokApiSdk`](https://pypi.org/project/TikTokApiSdk/).

Per-endpoint Python examples for every operation are in the [EulerStream API docs](https://www.eulerstream.com/docs/intro).

## Advanced usage

Customize the underlying `httpx.Client` / `httpx.AsyncClient` (timeouts, proxies, event hooks) through `httpx_args`, or replace it entirely:

```python
import httpx
from TikTokLiveApiSdk import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.eulerstream.com",
    token="YOUR_API_KEY",
    timeout=httpx.Timeout(30),
    httpx_args={"proxy": "http://localhost:8030"},
)
```

See the docstrings on `Client` and `AuthenticatedClient` for every option, including `verify_ssl`, `raise_on_unexpected_status` and `follow_redirects`.

## Migrating from EulerApiSdk

`TikTokLiveApiSdk` is the TikTok LIVE part of what used to be published as `EulerApiSdk`. Install it:

```bash
pip install TikTokLiveApiSdk
```

- **Imports.** Change `EulerApiSdk` to `TikTokLiveApiSdk` in your imports. The modules inside keep the names they had in `EulerApiSdk` 0.6.
- **The old package can stay installed while you switch.** The two share no files. Remove it with `pip uninstall EulerApiSdk` once nothing imports it.
- **The non-LIVE modules moved out.** User profiles, videos, OAuth, request signing, captcha solving and usage analytics are not in this package. They are in [`TikTokApiSdk`](https://pypi.org/project/TikTokApiSdk/), which has everything `EulerApiSdk` had. If you use any of them, install that instead; nothing else in your code has to change.

## Other languages

The TikTok LIVE API SDK is also available for [Node.js / TypeScript](https://www.npmjs.com/package/tiktok-live-api-sdk), [C# / .NET](https://www.nuget.org/packages/EulerApiSdk), [Java](https://central.sonatype.com/artifact/com.eulerstream/euler-api-sdk) and [Go](https://pkg.go.dev/github.com/EulerStream/TikTok-Live-Api/sdk/go), and anything else can use the language-agnostic WebSocket directly.

## Links

- Website: [eulerstream.com](https://www.eulerstream.com)
- Documentation: [eulerstream.com/docs](https://www.eulerstream.com/docs/intro)
- OpenAPI reference: [eulerstream.com/docs/openapi](https://www.eulerstream.com/docs/openapi)
- Pricing (free tier available): [eulerstream.com/pricing](https://www.eulerstream.com/pricing)
- Community: [Discord](https://www.eulerstream.com/discord)
- Source and issues: [github.com/EulerStream/TikTok-Api-Sdk](https://github.com/EulerStream/TikTok-Api-Sdk)

## License

[MIT](https://github.com/EulerStream/TikTok-Api-Sdk/blob/master/LICENSE) © EulerStream

