Metadata-Version: 2.4
Name: TikTokApiSdk
Version: 0.2.0
Summary: TikTok API SDK for Python. Typed sync and async client for the EulerStream TikTok API: user profiles, videos, OAuth, request signing and captcha solving, plus the full TikTok LIVE API for real-time chat, gifts, rooms, rankings, alerts and moderation.
License: MIT
License-File: LICENSE
Keywords: tiktok,tiktok api,tiktok-api,tiktokapi,tiktok sdk,tiktok api sdk,tiktok api client,tiktok user api,tiktok video api,tiktok oauth,tiktok signing,tiktok captcha,tiktok captcha solver,tiktok scraper,tiktok data,unofficial tiktok api,tiktok live,tiktok live api,eulerstream,euler stream,api,sdk,client,python
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 API SDK for Python

[![PyPI version](https://img.shields.io/pypi/v/TikTokApiSdk?color=0274b5)](https://pypi.org/project/TikTokApiSdk/)
[![PyPI downloads](https://img.shields.io/pypi/dm/TikTokApiSdk)](https://pypi.org/project/TikTokApiSdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/TikTokApiSdk)](https://pypi.org/project/TikTokApiSdk/)
[![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)

`TikTokApiSdk` is the official Python client for the [EulerStream TikTok API](https://www.eulerstream.com). Use one typed TikTok API client, sync or async, to **look up TikTok users, videos, comments, sounds and hashtags**, **search TikTok**, run **TikTok OAuth**, **sign TikTok web requests** and **solve TikTok captchas**. The complete TikTok LIVE API is included as well, so the same client can read real-time LIVE chat, gifts and viewer counts.

The TikTok API behind this SDK is hosted by EulerStream, the managed TikTok backend behind [TikTokLive](https://github.com/isaackogan/TikTokLive), the most popular Python library for TikTok LIVE. Request signing, captcha solving and the LIVE connection layer are maintained for you, so your integration keeps working when TikTok changes.

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

Only need TikTok LIVE? [`TikTokLiveApiSdk`](https://pypi.org/project/TikTokLiveApiSdk/) is the same client with just the LIVE groups.

## Installation

```bash
pip install TikTokApiSdk
```

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 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 TikTok API calls:

```python
from TikTokApiSdk import AuthenticatedClient
from TikTokApiSdk.api.tik_tok_users import retrieve_tik_tok_user_basic, retrieve_tik_tok_user_videos
from TikTokApiSdk.api.tik_tok_live import retrieve_hashtag_list

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

with client as c:
    # TikTok users API: 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)

    # TikTok videos API: a creator's latest videos, newest first
    videos = retrieve_tik_tok_user_videos.sync(unique_id="tv_asahi_news", client=c)
    print(len(videos.videos))

    # TikTok LIVE API (included): list the hashtags LIVE streams are grouped under
    hashtags = retrieve_hashtag_list.sync(client=c)
    print(hashtags.message)
```

The same TikTok API calls with asyncio:

```python
import asyncio
from TikTokApiSdk import AuthenticatedClient
from TikTokApiSdk.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())
```

`AuthenticatedClient` sends your key in the `X-Api-Key` header; use `TikTokApiSdk.Client` for the handful of routes that allow anonymous access.

## What the TikTok API covers

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

| TikTok API | Module | Functions |
|---|---|---|
| **TikTok users API** | `api.tik_tok_users` | `retrieve_tik_tok_user_basic`, `retrieve_tik_tok_user_profile`, `retrieve_tik_tok_user_videos`, `retrieve_tik_tok_user_reposts`, `retrieve_tik_tok_user_stories`, `retrieve_tik_tok_user_playlists`, `retrieve_tik_tok_playlist_videos`, `retrieve_tik_tok_user_info`, plus the users catalog (`search_tik_tok_users_catalog`, `retrieve_tik_tok_users_catalog_username`, `retrieve_tik_tok_users_catalog_numeric_id`) |
| **TikTok videos API** | `api.tik_tok_videos` | `retrieve_tik_tok_video_detailed`, `retrieve_tik_tok_video_comments`, `retrieve_tik_tok_video_comment_replies`, `retrieve_tik_tok_video_captions`, `retrieve_tik_tok_video_thumbnail` |
| **TikTok search API** | `api.tik_tok_search` | `search_tik_tok_general`, `search_tik_tok_videos`, `search_tik_tok_users`, `search_tik_tok_photos`, `search_tik_tok_autocomplete` |
| **TikTok sounds API** | `api.tik_tok_sounds` | `retrieve_tik_tok_sound`, `retrieve_tik_tok_sound_videos` |
| **TikTok hashtags API** | `api.tik_tok_tags` | `retrieve_tik_tok_tag_videos` |
| **TikTok short links** | `api.tik_tok_links` | `resolve_tik_tok_short_link` |
| **TikTok OAuth** | `api.tik_tok_oauth` | `exchange_token`, `introspect_token`, `revoke_token`, `validate_refresh_token`, `get_user_info`, `get_public_client` |
| **TikTok request signing** | `api.tik_tok_signing` | `sign_tik_tok_url`, plus decryptors for TikTok's encrypted payloads |
| **TikTok captcha solving** | `api.tik_tok_captchas` | `complete_puzzle_captcha`, `complete_shapes_captcha`, `complete_icon_captcha`, `complete_whirl_captcha` |
| **Your account** | `api.accounts` / `api.authentication` / `api.analytics` | Account details, rate limits, API keys, JWTs and usage analytics |

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

## TikTok LIVE API included

Everything in [`TikTokLiveApiSdk`](https://pypi.org/project/TikTokLiveApiSdk/) is part of this package too:

| 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` | LIVE 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, the gift catalog, search and single-gift lookup |
| `api.tik_tok_live_rankings` | LIVE 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` | LIVE kicks, bans, mutes, sensitive words and comment toggles |
| `api.tik_tok_web_socket_api` | Your cloud WebSocket connections and their state |

## What you can build with the TikTok API

- **Creator lookups and profile tools** backed by TikTok user profiles, a creator's videos, reposts, stories and playlists, and the users catalog
- **Video tools** that fetch TikTok video details, comments, replies, captions and thumbnails by ID
- **Search and discovery** across TikTok videos, users and photos, plus the videos under a hashtag or a sound
- **"Sign in with TikTok" flows** using the OAuth token, introspection and revocation routes
- **Scrapers and data pipelines** that sign TikTok web requests through the API instead of maintaining signature code
- **Captcha handling** for your own TikTok automation: puzzle, shapes, icon and whirl solvers
- **Everything TikTok LIVE**: stream overlays, gift alerts, chat bots, moderation tools and LIVE monitoring

## Advanced usage

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

```python
import httpx
from TikTokApiSdk 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

Coming from `EulerApiSdk`? This package is the same client with everything it had, under a new name. Install it, then change `EulerApiSdk` to `TikTokApiSdk` in your imports. The modules inside keep the names they had in `EulerApiSdk` 0.6.

```bash
pip install TikTokApiSdk
```

The old package can stay installed while you switch, because the two share no files. Remove it with `pip uninstall EulerApiSdk` once nothing imports it.
## Other languages

The TikTok API SDK is also available for [Node.js / TypeScript](https://www.npmjs.com/package/tiktok-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 call the TikTok API over plain HTTP.

## Links

- Website: [eulerstream.com](https://www.eulerstream.com)
- TikTok API 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

