Metadata-Version: 2.5
Name: tiktok-private-api
Version: 0.1.0
Summary: Unofficial TikTok Private API SDK — 50+ endpoints, full mobile signing, Android + iOS
Project-URL: Homepage, https://github.com/molkex/tiktok-private-api
Project-URL: Documentation, https://github.com/molkex/tiktok-private-api#endpoints
Project-URL: Issues, https://github.com/molkex/tiktok-private-api/issues
Project-URL: Telegram, https://t.me/tiktok_private_api
Author: molkex
License-Expression: MIT
License-File: LICENSE
Keywords: private-api,reverse-engineering,social-media-api,tiktok,tiktok-api,tiktok-bot,tiktok-scraper,tiktok-sdk,unofficial-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: curl-cffi>=0.7
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# tiktok-private-api

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/tiktok-private-api.svg)](https://pypi.org/project/tiktok-private-api/)

**Unofficial TikTok Private API SDK for Python.** Full mobile signing, 50+ endpoints, Android + iOS.

```bash
pip install tiktok-private-api
```

```python
from tiktokflow import TikTokAPI

api = TikTokAPI(api_key="sk_your_key")

feed = api.feed.for_you(count=5)
for video in feed["aweme_list"]:
    print(video["desc"], video["statistics"]["digg_count"], "likes")
```

**Real output:**
```
Got 8 videos:
  [1] @Nancy Ryan🥀: Welcome to Chicago, the dream city 🤍 (2,021,357 likes)
  [2] @Khabane lame: I had the whole day to charge it… 😭 (5,655,444 likes)
  [3] @marry_cutie: #OOTD #ootdfashion #views (78,053 likes)
  [4] @HSSTECH: Stop Charging Your Samsung Phone Everyday! (61,644 likes)
```

---

## Why This SDK

| | tiktok-private-api | Official TikTok API | Web scrapers |
|---|---|---|---|
| **Endpoints** | 50+ (feed, user, video, search, comment, social, DM, music, live) | ~10 (Display + Content Posting) | 5-10 |
| **Write actions** | Like, follow, comment, block, delete | Post only | None |
| **Auth required** | No OAuth app needed | OAuth app + review | No |
| **Rate limits** | Mobile-grade (high) | Strict quotas | IP-based bans |
| **TLS fingerprint** | Real device (curl_cffi) | N/A | Browser detected |
| **Signing** | Full stack (Gorgon + Argus + Ladon + Guard) | N/A | None |

---

## How It Works

```mermaid
flowchart LR
    A["Your Code"] -->|"api.feed.for_you()"| B["tiktok-private-api\n(SDK)"]
    B -->|"POST /v1/sign"| C["Signing Server\n(cloud)"]
    C -->|"signed headers"| B
    B -->|"GET /aweme/v1/feed/"| D["TikTok\nServers"]
    D -->|"JSON response"| B
    B -->|"parsed data"| A

    style C fill:#1a1a2e,stroke:#e94560,color:#fff
    style D fill:#1a1a2e,stroke:#00d2ff,color:#fff
```

- **Your IP → TikTok directly.** The signing server only computes cryptographic headers.
- It never sees TikTok's responses or your data.
- Full signing stack: X-Gorgon, X-Argus, X-Ladon, ECDSA Device Guard, Ticket Guard.

---

## Endpoints

### Feed
| Method | Description |
|--------|-------------|
| `api.feed.for_you()` | For You page |
| `api.feed.following()` | Following feed |
| `api.feed.user_posts(sec_user_id)` | User's videos |
| `api.feed.hashtag(ch_id)` | Hashtag feed |
| `api.feed.music(music_id)` | Music/sound feed |

### User
| Method | Description |
|--------|-------------|
| `api.user.info(sec_user_id)` | User profile |
| `api.user.profile_self()` | Own profile |
| `api.user.followers(sec_user_id)` | Follower list |
| `api.user.following(sec_user_id)` | Following list |
| `api.user.search(keyword)` | Search users |
| `api.user.block_list()` | Blocked users |

### Video
| Method | Description |
|--------|-------------|
| `api.video.detail(aweme_id)` | Video info + stats |
| `api.video.multi_detail(ids)` | Batch video info |
| `api.video.my_posts()` | Own posted videos |
| `api.video.favorites()` | Liked videos |
| `api.video.delete(aweme_id)` | Delete own video |

### Social Actions
| Method | Description |
|--------|-------------|
| `api.social.like(aweme_id)` | Like a video |
| `api.social.unlike(aweme_id)` | Unlike |
| `api.social.follow(user_id)` | Follow a user |
| `api.social.unfollow(user_id)` | Unfollow |
| `api.social.block(user_id)` | Block a user |
| `api.social.unblock(user_id)` | Unblock |

### Comments
| Method | Description |
|--------|-------------|
| `api.comment.list(aweme_id)` | Get comments |
| `api.comment.replies(comment_id)` | Get replies |
| `api.comment.publish(aweme_id, text)` | Post comment |
| `api.comment.delete(comment_id)` | Delete comment |
| `api.comment.like(comment_id)` | Like comment |

### Search
| Method | Description |
|--------|-------------|
| `api.search.general(keyword)` | General search |
| `api.search.users(keyword)` | Search users |
| `api.search.videos(keyword)` | Search videos |
| `api.search.music(keyword)` | Search music |
| `api.search.hashtags(keyword)` | Search hashtags |
| `api.search.live(keyword)` | Search lives |

### Music
| Method | Description |
|--------|-------------|
| `api.music.detail(music_id)` | Music/sound info |
| `api.music.videos(music_id)` | Videos using sound |

### Direct Messages
| Method | Description |
|--------|-------------|
| `api.dm.conversations()` | Conversation list |
| `api.dm.messages(conversation_id)` | Read messages |
| `api.dm.unread_count()` | Unread count |

### Live
| Method | Description |
|--------|-------------|
| `api.live.search(keyword)` | Search live streams |
| `api.live.enter(room_id)` | Enter live room |

### Account
| Method | Description |
|--------|-------------|
| `api.passport.email_login(email, pw)` | Email login |
| `api.passport.sms_login(phone, code)` | SMS login |
| `api.passport.register(email, pw)` | Register account |
| `api.passport.logout()` | Logout |

---

## Setup

### 1. Install

```bash
pip install tiktok-private-api
```

### 2. Get an API key

Write me on Telegram — [@mxmtkchk](https://t.me/mxmtkchk).

Free keys available for testing. Paid plans for production use.

### 3. Use

```python
from tiktokflow import TikTokAPI

api = TikTokAPI(api_key="sk_your_key_here")

feed = api.feed.for_you(count=5)
print(f"Got {len(feed['aweme_list'])} videos")
```

---

## Advanced Usage

### Proxy rotation

```python
api = TikTokAPI(
    api_key="sk_...",
    proxies=["socks5://user:pass@proxy1:1080", "socks5://user:pass@proxy2:1080"],
    proxy_rotate="round_robin",  # or "random"
)
```

### iOS device fingerprint

```python
api = TikTokAPI(api_key="sk_...", platform="ios")
```

### Rate limiting

```python
api = TikTokAPI(api_key="sk_...", rate_limit=2.0)  # max 2 req/sec
```

### Session persistence

```python
api.device.save("my_session.json")

# Later:
from tiktokflow.android import Device
device = Device.load("my_session.json")
api = TikTokAPI(api_key="sk_...", device=device)
```

### Async

```python
from tiktokflow.android import AsyncAndroidClient, Device, RemoteSigner

signer = RemoteSigner("http://...", "sk_...")
async with AsyncAndroidClient(Device(), signer=signer) as api:
    feed = await api.feed.for_you(count=10)
```

---

## Examples

See [examples/](examples/):

- [`quickstart.py`](examples/quickstart.py) — Feed + user lookup + like
- [`bulk_scraper.py`](examples/bulk_scraper.py) — Scrape videos with pagination

---

## SDK vs Competitors

| Feature | tiktok-private-api | TikTok-Api (davidteather) | tiktok-scraper |
|---------|-------------------|--------------------------|----------------|
| Write endpoints | **Yes** (like, follow, comment) | No | No |
| Mobile signing | **Full** (Gorgon+Argus+Ladon+Guard) | Partial (browser) | None |
| Android + iOS | **Yes** | No | No |
| Proxy rotation | **Built-in** | Manual | Manual |
| DM access | **Yes** | No | No |
| Account login | **Yes** | No | No |
| Maintained | **Yes (2026)** | Sporadic | Archived |
| Anti-detection | **TLS impersonation** | Browser automation | HTTP only |

---

## Contributing

Contributions welcome! Open an issue first to discuss.

## Contact

**Telegram:** [@mxmtkchk](https://t.me/mxmtkchk) — support, API keys, feature requests

## License

MIT. See [LICENSE](LICENSE).

---

*This project is not affiliated with TikTok or ByteDance. Use responsibly.*
