TikHub API Python SDK

English | 中文 | Français | Español | 日本語

The official Python SDK for the TikHub 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.

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.

Why TikHub?

• 1000+ endpoints across 16 platforms through a single API key
• Real-time data — video details, user profiles, comments, search results, live streams, trending content, and e-commerce analytics
• RESTful & OpenAPI-native — every endpoint is documented in the OpenAPI spec and testable via Swagger UI
• MCP integration — connect AI agents (Claude, LangChain, Coze, n8n) directly to social media data via Model Context Protocol
• Datasets available — 1B+ pre-collected, structured records for training and research

Why This SDK?

• 100% endpoint coverage — 1048 / 1048 endpoints from OpenAPI spec V5.3.2 (deprecated endpoints excluded), mechanically generated and verified
• Sync + async — TikHub and AsyncTikHub clients with identical APIs
• Production-ready — automatic retries with exponential backoff, rate-limit handling, structured error hierarchy with full debugging context
• Type-safe — mypy --strict clean, built on httpx + pydantic v2
• Zero config — flat kwargs, no config objects; set one env var and go

Version: 2.1.1 — Requires Python 3.9+

Supported Platforms

Install

pip install tikhub

Requires Python 3.9+.

From source

git clone https://github.com/TikHub/TikHub-API-Python-SDK.git
cd TikHub-API-Python-SDK
pip install -e ".[dev]"
pytest -q

Get your API Key

1. Go to https://user.tikhub.io/login and sign up / log in.
2. Copy your API key from the dashboard.
3. Set it as an environment variable or pass it directly:

export TIKHUB_API_KEY="YOUR_API_KEY"

Quickstart

from tikhub import TikHub

client = TikHub(api_key="YOUR_API_KEY")

# 1:1 with the OpenAPI spec — resource = tag, method = path basename
video = client.douyin_web.fetch_one_video(aweme_id="7251234567890123456")
print(video.aweme_detail.desc)

client.close()

Or with the recommended context manager:

with TikHub(api_key="YOUR_API_KEY") as client:
    health = client.health_check.check()
    print(health.status)

Async

import asyncio
from tikhub import AsyncTikHub

async def main():
    async with AsyncTikHub(api_key="YOUR_API_KEY") as client:
        video = await client.douyin_web.fetch_one_video(aweme_id="...")
        print(video.aweme_detail.desc)

asyncio.run(main())

Configuration

The constructor takes one required argument and a small handful of optional kwargs:

TikHub(
    api_key=None,        # str | None — defaults to $TIKHUB_API_KEY
    timeout=30,          # float | None — total request timeout in seconds
    base_url=None,       # str | None — only override for a private mirror

    # Advanced (rare):
    max_retries=3,
    proxy=None,
    user_agent=None,
    parse_response=True,
    http_client=None,    # bring your own httpx.Client
)

That's the entire configuration surface. There is no ClientConfig object — knobs are flat kwargs.

Naming rules

The SDK is mechanically derived from the TikHub OpenAPI spec. Two rules:

1. Resource attribute = OpenAPI tag, lowercased, dashes → underscores, -API stripped. Douyin-Web-API → client.douyin_web. TikTok-App-V3-API → client.tiktok_app_v3.
2. Method name = the last segment of the API path, verbatim. /api/v1/douyin/web/fetch_one_video → client.douyin_web.fetch_one_video(...).

Parameter names match the OpenAPI spec verbatim. If you can read the TikHub API docs, you already know how to use the SDK.

Status

100% endpoint coverage against TikHub OpenAPI spec V5.3.2.

The resource layer is mechanically generated from spec/openapi.json. To refresh after a TikHub spec update:

python scripts/refresh_spec.py        # pulls latest openapi.json, prints diff
python scripts/generate_resources.py  # regenerates all 51 resource files + clients
python scripts/generate_docs.py       # regenerates docs/reference.md
python scripts/verify_coverage.py     # asserts 100% coverage
pytest -q                             # 110 tests

CLI

A small console wrapper ships in the cli extra:

pip install "tikhub[cli]"
export TIKHUB_API_KEY="YOUR_API_KEY"

tikhub health                                 # ping the API
tikhub fetch https://v.douyin.com/abc/        # universal video URL parser
tikhub user info                              # plan + quota
tikhub user usage                             # today's request count

Every command prints JSON to stdout — pipe to jq or any other formatter.

Documentation

Full docs (mkdocs-material): authentication, async, errors, pagination, retries, logging, CLI, migration guide, naming rules, and the auto-generated reference for all 1048 endpoints.

pip install -e ".[docs]"
mkdocs serve            # http://127.0.0.1:8000

License

MIT.