TikTok APIs 是一个面向学习与技术研究目的的 Python 库，提供对 TikTok Web 端数据读取、用户互动、Creator 发布及实时消息接口的程序化访问。
项目明确声明非官方、不鼓励生产使用，要求使用者自备账号与浏览器会话，严格遵守平台规则，禁止提交 Cookie、私钥或抓包文件。已实现功能涵盖内容/用户信息获取、评论互动、Creator Studio 视频/图集发布（默认仅自己可见）、直播 WebSocket 事件接收、私信收发及 TikTok Shop 商品/评价读取。
架构分层清晰（api/builder/signing/utils），Web 签名纯 Python 计算，直播/私信/Shop 签名依赖本地 Node.js SDK；所有请求必须来自同一真实浏览器会话的完整上下文，缺失字段时直接拒绝而非伪造。
核心能力矩阵
| 场景 | 已实现入口 | 关键限制 |
|---|---|---|
| 内容与用户 | 作品详情、主页列表、推荐流、搜索、关注/粉丝、收藏夹、通知 | 详情页取自 hydration 数据，非猜测 API |
| 评论与互动 | 评论/楼中楼读取、翻页、发评/回复、点赞、收藏、关注 | 需 referer + root_referer 页面证据 |
| Creator Studio | creator_publish（视频）、creator_publish_photos（图集） | 默认仅自己可见；需完整 Creator Studio 浏览器状态 |
| 直播 | Feed、房间/用户/礼物列表、protobuf 拉取、WebSocket 聊天/点赞/礼物 | 迭代器模式，调用方自管重连与退出 |
| 私信 | HTTP 会话/消息拉取、文本发送、WebSocket 推送接收 | 未完成跨账号端到端验收（缺测试消息） |
| TikTok Shop | 商品详情、首屏+后续评价读取 | 不含任何电商写操作 |
技术架构与签名机制
- 分层设计：
api（接口封装）→builder（请求构建）→signing（签名计算）→utils（工具函数） - Web/Creator HTTP 签名：纯 Python 从当前请求参数实时计算，无硬编码常量
- WebSocket/Shop 签名：通过仓库内 SDK 调用本地 Node.js 运行器生成
frontierSign/ BSID - 严格会话一致性：Cookie、storage、UA、header 顺序、body 必须源自同一次真实浏览器会话
- 零容忍伪造：必需字段缺失、签名集合不符或长度异常时直接拒绝请求，绝不补齐/截断/复用旧值
快速开始与环境要求
依赖
- Python ≥ 3.11
- Node.js ≥ 18（仅直播/私信 WebSocket 与 Shop BSID 签名需要）
安装
python -m pip install -r requirements.txt
认证与初始化
import os
from builder.auth import TiktokAuth
from api.tiktok_web import TiktokWebAPI
# ⚠️ Cookie 等敏感信息仅从环境变量读取，严禁写入代码或提交 Git
auth = TiktokAuth.from_cookie(
os.environ["TIKTOK_COOKIE"],
local_storage={"g_exp": "当前浏览器 g_exp"},
session_storage={"msToken": "当前浏览器 msToken"},
# device_id, browser_metrics, security-sdk storage 等按需补充
# 缺失时直接报错，不会伪造默认值
)
api = TiktokWebAPI(auth)
⚠️ 关键提醒：
- 唯一认证方式为
TiktokAuth.from_cookie；账密/二维码/短信登录仅为占位接口（抛出NotImplementedError）- 浏览器 Cookie 不足以单独工作，必须同步提供
device_id、local_storage、session_storage、document_cookie、browser_metrics及写操作所需的 CSRF/ticket-guarddemo.py仅作私密发布本地预检示例，非生产脚本
常用调用示例
# 用户作品列表
posts = api.get_user_posted("用户 secUid")
# 全部评论（含翻页）
comments = api.get_all_comments("作品 ID")
# 楼中楼回复（需页面证据）
replies = api.get_all_comment_replies(
"作品 ID", "一级评论 ID",
referer="当前视频页面 URL",
root_referer="当前标签页根导航 URL",
)
# Creator 发布（默认仅自己可见）
result = api.creator_publish("video.mp4", "视频文案")
photos = api.creator_publish_photos(["1.jpg", "2.jpg"], "图集文案")
# 直播事件接收（迭代器）
for event in iter_live_ws_events(live_id, room_id, ...):
handle(event)
# 私信接收（迭代器，未完成跨账号验收）
for msg in iter_im_ws_messages(...):
process(msg)
