Skip to content

Commit 8e4375b

Browse files
callmeikscallmeiks
committed
update Readme
1 parent ae7365f commit 8e4375b

2 files changed

Lines changed: 203 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# TikHub API Python SDK
22

3+
English | [中文](README_CN.md)
4+
35
The official Python SDK for the [TikHub](https://tikhub.io) social media data API — a unified REST API that provides real-time access to **16+ social media platforms** including TikTok, Douyin, Instagram, YouTube, Twitter/X, Xiaohongshu (Red Note), Bilibili, Weibo, Threads, LinkedIn, Reddit, Kuaishou, WeChat, Lemon8, Zhihu, and more.
46

57
Built for developers, data scientists, and AI engineers who need structured social media data at scale — for **AI training**, **influencer analytics**, **trend monitoring**, **sentiment analysis**, **market research**, and **competitive intelligence**.
@@ -20,7 +22,7 @@ Built for developers, data scientists, and AI engineers who need structured soci
2022
- **Type-safe** — `mypy --strict` clean, built on `httpx` + `pydantic v2`
2123
- **Zero config** — flat kwargs, no config objects; set one env var and go
2224

23-
> **Version:** `2.1.0` — Requires Python 3.9+
25+
> **Version:** `2.1.1` — Requires Python 3.9+
2426
2527
## Supported Platforms
2628

@@ -45,38 +47,31 @@ Built for developers, data scientists, and AI engineers who need structured soci
4547

4648
## Install
4749

48-
### From GitHub (recommended for now)
49-
5050
```bash
51-
# Latest from the v2.1.0 branch
52-
pip install "git+https://github.com/TikHub/[email protected]"
53-
54-
# With the optional CLI extra
55-
pip install "tikhub[cli] @ git+https://github.com/TikHub/[email protected]"
56-
57-
# Pin to a specific commit (recommended for production)
58-
pip install "git+https://github.com/TikHub/TikHub-API-Python-SDK.git@<commit-sha>"
51+
pip install tikhub
5952
```
6053

61-
Once merged into `main`, the `@v2.1.0` ref can be dropped.
54+
Requires Python 3.9+.
6255

6356
### From source
6457

6558
```bash
66-
git clone -b v2.1.0 https://github.com/TikHub/TikHub-API-Python-SDK.git
59+
git clone https://github.com/TikHub/TikHub-API-Python-SDK.git
6760
cd TikHub-API-Python-SDK
6861
pip install -e ".[dev]"
6962
pytest -q
7063
```
7164

72-
### From PyPI _(coming soon)_
65+
## Get your API Key
66+
67+
1. Go to [https://user.tikhub.io/login](https://user.tikhub.io/login) and sign up / log in.
68+
2. Copy your API key from the dashboard.
69+
3. Set it as an environment variable or pass it directly:
7370

7471
```bash
75-
pip install tikhub
72+
export TIKHUB_API_KEY="YOUR_API_KEY"
7673
```
7774

78-
Requires Python 3.9+.
79-
8075
## Quickstart
8176

8277
```python

‎README_CN.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# TikHub API Python SDK
2+
3+
[English](README.md) | 中文
4+
5+
[TikHub](https://tikhub.io) 社交媒体数据 API 的官方 Python SDK — 统一的 REST API，可实时访问 **16+ 社交媒体平台**，包括 TikTok、抖音、Instagram、YouTube、Twitter/X、小红书、B站、微博、Threads、LinkedIn、Reddit、快手、微信、Lemon8、知乎等。
6+
7+
专为开发者、数据科学家和 AI 工程师打造，适用于 **AI 训练**、**达人分析**、**趋势监控**、**舆情分析**、**市场调研** 和 **竞品情报** 等场景。
8+
9+
## 为什么选择 TikHub？
10+
11+
- **1000+ 接口**，覆盖 16 个平台，只需一个 API Key
12+
- **实时数据** — 视频详情、用户资料、评论、搜索结果、直播、热门内容、电商分析
13+
- **RESTful & OpenAPI 原生** — 所有接口均在 [OpenAPI 规范](https://api.tikhub.io/openapi.json) 中有文档，可通过 [Swagger UI](https://api.tikhub.io) 在线测试
14+
- **MCP 集成** — 通过 [Model Context Protocol](https://tikhub.io) 将 AI Agent（Claude、LangChain、Coze、n8n）直接连接到社交媒体数据
15+
- **数据集** — 10 亿+ 条预采集的结构化数据，可用于训练和研究
16+
17+
## 为什么选择这个 SDK？
18+
19+
- **100% 接口覆盖** — OpenAPI 规范 V5.3.2 的 1010 / 1010 个接口，机械化生成并验证
20+
- **同步 + 异步** — `TikHub` 和 `AsyncTikHub` 客户端，API 完全一致
21+
- **生产就绪** — 自动重试（指数退避）、速率限制处理、结构化异常体系（含完整调试上下文）
22+
- **类型安全** — `mypy --strict` 通过，基于 `httpx` + `pydantic v2` 构建
23+
- **零配置** — 扁平化参数，无需配置对象；设置一个环境变量即可使用
24+
25+
> **版本：** `2.1.1` — 需要 Python 3.9+
26+
27+
## 支持的平台
28+
29+
| 平台 | 资源 | 接口数 |
30+
|---|---|---|
31+
| TikTok | `tiktok_web`, `tiktok_app_v3`, `tiktok_creator`, `tiktok_analytics`, `tiktok_ads`, `tiktok_shop_web` | 200+ |
32+
| 抖音 | `douyin_web`, `douyin_app_v3`, `douyin_search`, `douyin_billboard`, `douyin_creator`, `douyin_xingtu` | 400+ |
33+
| Instagram | `instagram_v1`, `instagram_v2`, `instagram_v3` | 80+ |
34+
| YouTube | `youtube_web`, `youtube_web_v2` | 50+ |
35+
| Twitter / X | `twitter_web` | 13+ |
36+
| 小红书 | `xiaohongshu_web`, `xiaohongshu_app`（+ v2/v3 变体） | 80+ |
37+
| B站 | `bilibili_web`, `bilibili_app` | 40+ |
38+
| 微博 | `weibo_web`, `weibo_web_v2`, `weibo_app` | 30+ |
39+
| Threads | `threads_web` | 10+ |
40+
| LinkedIn | `linkedin_web` | 10+ |
41+
| Reddit | `reddit_app` | 10+ |
42+
| 快手 | `kuaishou_web`, `kuaishou_app` | 20+ |
43+
| 微信 | `wechat_channels`, `wechat_media_platform_web` | 20+ |
44+
| Lemon8 | `lemon8_app` | 10+ |
45+
| 知乎 | `zhihu_web` | 30+ |
46+
| 其他 | `toutiao_web`, `toutiao_app`, `xigua_app_v2`, `pipixia_app`, `sora2` | 30+ |
47+
48+
## 安装
49+
50+
```bash
51+
pip install tikhub
52+
```
53+
54+
需要 Python 3.9+。
55+
56+
### 从源码安装
57+
58+
```bash
59+
git clone https://github.com/TikHub/TikHub-API-Python-SDK.git
60+
cd TikHub-API-Python-SDK
61+
pip install -e ".[dev]"
62+
pytest -q
63+
```
64+
65+
## 获取 API Key
66+
67+
1. 前往 [https://user.tikhub.io/login](https://user.tikhub.io/login) 注册 / 登录。
68+
2. 在控制台复制你的 API Key。
69+
3. 设置为环境变量或直接传入：
70+
71+
```bash
72+
export TIKHUB_API_KEY="YOUR_API_KEY"
73+
```
74+
75+
## 快速开始
76+
77+
```python
78+
from tikhub import TikHub
79+
80+
client = TikHub(api_key="YOUR_API_KEY")
81+
82+
# 与 OpenAPI 规范 1:1 对应 — 资源 = 标签, 方法 = 路径末段
83+
video = client.douyin_web.fetch_one_video(aweme_id="7251234567890123456")
84+
print(video.aweme_detail.desc)
85+
86+
client.close()
87+
```
88+
89+
推荐使用上下文管理器：
90+
91+
```python
92+
with TikHub(api_key="YOUR_API_KEY") as client:
93+
health = client.health_check.check()
94+
print(health.status)
95+
```
96+
97+
## 异步用法
98+
99+
```python
100+
import asyncio
101+
from tikhub import AsyncTikHub
102+
103+
async def main():
104+
async with AsyncTikHub(api_key="YOUR_API_KEY") as client:
105+
video = await client.douyin_web.fetch_one_video(aweme_id="...")
106+
print(video.aweme_detail.desc)
107+
108+
asyncio.run(main())
109+
```
110+
111+
## 配置
112+
113+
构造函数接受一个必需参数和少量可选参数：
114+
115+
```python
116+
TikHub(
117+
api_key=None, # str | None — 默认读取 $TIKHUB_API_KEY
118+
timeout=30, # float | None — 总请求超时时间（秒）
119+
base_url=None, # str | None — 仅在使用私有镜像时覆盖
120+
121+
# 高级选项（较少使用）：
122+
max_retries=3,
123+
proxy=None,
124+
user_agent=None,
125+
parse_response=True,
126+
http_client=None, # 传入自定义 httpx.Client
127+
)
128+
```
129+
130+
这就是全部的配置项。没有 `ClientConfig` 对象 — 所有选项都是扁平化的关键字参数。
131+
132+
## 命名规则
133+
134+
SDK 由 TikHub OpenAPI 规范机械化生成。两条规则：
135+
136+
1. **资源属性** = OpenAPI 标签，转小写，连字符转下划线，去掉 `-API` 后缀。
137+
`Douyin-Web-API` -> `client.douyin_web`。`TikTok-App-V3-API` -> `client.tiktok_app_v3`。
138+
2. **方法名** = API 路径的**最后一段，保持原样**。
139+
`/api/v1/douyin/web/fetch_one_video` -> `client.douyin_web.fetch_one_video(...)`。
140+
141+
参数名与 OpenAPI 规范完全一致。如果你能读懂 TikHub API 文档，你就已经会用这个 SDK 了。
142+
143+
## 状态
144+
145+
**100% 接口覆盖**，基于 TikHub OpenAPI 规范 V5.3.2。
146+
147+
| | |
148+
|---|---|
149+
| 资源 | **52**（每个 OpenAPI 标签一个） |
150+
| 接口 | **1010 / 1010** |
151+
| 测试 | 110 个通过 |
152+
| 类型检查 | mypy `--strict` 71 个源文件全部通过 |
153+
| 代码检查 | ruff 通过 |
154+
155+
资源层由 `spec/openapi.json` **机械化生成**。当 TikHub 规范更新后，运行以下命令刷新：
156+
157+
```bash
158+
python scripts/refresh_spec.py # 拉取最新 openapi.json，打印差异
159+
python scripts/generate_resources.py # 重新生成所有 52 个资源文件 + 客户端
160+
python scripts/generate_docs.py # 重新生成 docs/reference.md
161+
python scripts/verify_coverage.py # 验证 100% 覆盖
162+
pytest -q # 110 个测试
163+
```
164+
165+
## CLI 命令行工具
166+
167+
SDK 内置了一个轻量命令行工具：
168+
169+
```bash
170+
export TIKHUB_API_KEY="YOUR_API_KEY"
171+
172+
tikhub health # 检查 API 连通性
173+
tikhub fetch https://v.douyin.com/abc/ # 通用视频链接解析
174+
tikhub user info # 账户套餐 + 配额
175+
tikhub user usage # 今日请求量
176+
```
177+
178+
所有命令输出 JSON 到标准输出 — 可通过管道传给 `jq` 或其他格式化工具。
179+
180+
## 文档
181+
182+
完整文档（mkdocs-material）：身份认证、异步、异常处理、分页、重试、日志、CLI、迁移指南、命名规则，以及所有 1010 个接口的自动生成参考文档。
183+
184+
```bash
185+
pip install -e ".[docs]"
186+
mkdocs serve # http://127.0.0.1:8000
187+
```
188+
189+
## 许可证
190+
191+
MIT。

0 commit comments

Comments
 (0)