Metadata-Version: 2.4
Name: EulerApiSdk
Version: 0.4.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 webcast signing, rooms, gifts, rankings, LIVE alerts, moderation, captchas and analytics.
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,tiktok signing,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-Live-Api/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-Live-Api
Description-Content-Type: text/markdown

# TikTok LIVE API SDK for Python

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

`EulerApiSdk` 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 webcast signing, LIVE rooms, gifts, rankings, LIVE alerts, moderation, captchas and analytics.

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.

## Installation

```bash
pip install EulerApiSdk
```

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`).

## 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 EulerApiSdk import AuthenticatedClient
from EulerApiSdk.api.tik_tok_users import retrieve_tik_tok_user_basic
from EulerApiSdk.api.tik_tok_live_gifts import list_webcast_gifts
from EulerApiSdk.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:
    # Look up any TikTok user by @username
    user = retrieve_tik_tok_user_basic.sync(unique_id="tv_asahi_news", client=c)
    print(user.user.nickname)

    # Browse the TikTok LIVE gift catalog (names, diamond values, images)
    catalog = list_webcast_gifts.sync(client=c)
    for gift in catalog.gifts:
        print(f"{gift.gift_name} = {gift.diamond_count} diamonds")

    # 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 EulerApiSdk import AuthenticatedClient
from EulerApiSdk.api.tik_tok_users import retrieve_tik_tok_user_basic


async def main():
    async with AuthenticatedClient(base_url="https://api.eulerstream.com", token="YOUR_API_KEY") as c:
        user = await retrieve_tik_tok_user_basic.asyncio(unique_id="tv_asahi_news", client=c)
        print(user.user.nickname)


asyncio.run(main())
```

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

## What you can build

- **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

## API coverage

Every path/method in the [EulerStream OpenAPI spec](https://www.eulerstream.com/docs/openapi) becomes a module under `EulerApiSdk.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 gift catalog: list, search and look up gifts |
| `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_signing` | TikTok request signing and payload decryption |
| `api.tik_tok_captchas` | TikTok captcha solving |
| `api.tik_tok_general` | TikTok OAuth: token exchange, introspection, revocation, user info |
| `api.tik_tok_users` / `api.tik_tok_videos` | TikTok user profiles and videos |
| `api.tik_tok_web_socket_api` | Your cloud WebSocket connections and their state |
| `api.accounts` / `api.authentication` / `api.analytics` | Your EulerStream account, API keys, JWTs and usage analytics |

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 EulerApiSdk 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`.

## 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-Live-Api](https://github.com/EulerStream/TikTok-Live-Api)

## License

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

