TikTokApi Video 模块 API 全解:视频信息、字节下载、评论与相关视频的完整用法
TikTokApi Video 模块 API 全解:视频信息、字节下载、评论与相关视频的完整用法
本篇文章以仓库 Sphinx API 文档源文件 .sphinx/api/video.rst 为核心,围绕其中的
automodule指令所指向的TikTokApi.api.video模块展开。你将掌握 TikTokApi 中Video类的全部公开成员:如何用 id/url/data 三种方式构造视频对象、如何拉取完整视频数据(含两种页面内嵌 JSON 的解析路径)、如何下载或流式下载视频字节、如何分页遍历评论与相关视频,并了解数据反序列化为User/Sound/Hashtag关联对象的内部机制。文章中的所有结论均以仓库源码、测试用例与示例脚本为准,可随时回到对应文件核对。
一、Video 模块在文档体系中的定位
.sphinx/api/video.rst 是整个 Sphinx 文档体系中负责生成视频模块 API 参考的指令文件,其完整内容如下:
TikTokApi.api.video module
----------------------------
.. automodule:: TikTokApi.api.video
:members:
:undoc-members:
:show-inheritance:
它本身并非普通 prose 文档,而是一段 autodoc 指令:
.. automodule:: TikTokApi.api.video:指示 Sphinx 从TikTokApi/api/video.py模块自动提取文档;:members::列出模块的公开成员(类与函数),即使没有 docstring 也会生成条目;:undoc-members::连未写文档字符串的成员也一并收录;:show-inheritance::显示类的继承关系。
在文档树中,该文件由 .sphinx/TikTokApi.api.rst 通过 .. include:: api/video.rst 引入,与 User、Sound、Hashtag、Comment、Trending、Search 各模块并列;而 autodoc 的启用在 .sphinx/conf.py 中通过 extensions = ["sphinx.ext.autodoc", ...] 与 napoleon_google_docstring = True 配置,用于解析源码中的 Google 风格 docstring。也就是说,本指令展开后的"正文",就是 TikTokApi.api.video 模块中 Video 类的全部 API 面。
二、Video 类速览:公开属性与能力总览
Video 类是 TikTokApi 中对单个 TikTok 视频的封装,定义在 TikTokApi/api/video.py。它通过类变量 parent 持有全局的 TikTokApi 实例,从而可以调用会话管理、请求签名等底层能力。
公开属性
| 属性 | 类型 | 说明(对应源码 docstring) |
|---|---|---|
id |
Optional[str] |
TikTok 对视频分配的 ID |
url |
Optional[str] |
视频的 URL |
create_time |
Optional[datetime] |
视频的创建时间(由时间戳转换而来) |
stats |
Optional[dict] |
TikTok 返回的视频统计数据(点赞、评论、分享等) |
author |
Optional[User] |
创建该视频的用户对象 |
sound |
Optional[Sound] |
与该视频关联的背景音乐对象 |
hashtags |
Optional[list[Hashtag]] |
视频标签(challenges)列表 |
as_dict |
dict |
与该视频关联的原始数据字典 |
公开方法
| 方法 | 签名 | 用途 |
|---|---|---|
info |
async info(self, **kwargs) -> dict |
返回视频的全部关联数据 |
bytes |
async bytes(self, stream: bool = False, **kwargs) -> Union[bytes, AsyncIterator[bytes]] |
返回视频字节,支持流式 |
comments |
async comments(self, count=20, cursor=0, **kwargs) -> Iterator[Comment] |
分页遍历视频评论 |
related_videos |
async related_videos(self, count: int = 30, cursor: int = 0, **kwargs) -> Iterator[Video] |
分页遍历相关视频 |
此外还实现了 __str__/__repr__,打印结果为 TikTokApi.video(id='...') 形式(见 TikTokApi/api/video.py)。
三、构造 Video 对象:id / url / data 三种入口
Video.__init__(TikTokApi/api/video.py)签名如下:
def __init__(
self,
id: Optional[str] = None,
url: Optional[str] = None,
data: Optional[dict] = None,
**kwargs,
):
构造有三种入口,互不冲突:
- 直接给
id:最常见的方式,如官方 docstring 所示video = api.video(id='7041997751718137094'); - 给
url:库会借助extract_video_id_from_url从 URL 中解析出视频 ID。此时会先通过self.parent._get_session(**kwargs)取一个会话,用会话的headers和proxy发起请求解析,因此比直接传 id 多一次网络开销; - 给
data:当视频数据来自其他接口(如用户主页、hashtag、sound 的视频列表)时,直接传入原始字典,并立即执行__extract_from_data()完成反序列化。
如果解析后 id 仍为 None,构造函数抛出 TypeError("You must provide id or url parameter.")。
URL 解析的底层实现
extract_video_id_from_url 定义在 TikTokApi/helpers.py,其逻辑为:先用 requests.head(url, allow_redirects=True) 跟随重定向拿到最终 URL(短链 https://www.tiktok.com/t/ZT8LCfcUC/ 也能被解析),再检查 URL 中是否同时包含 @ 与 /video/ 子串,若满足则取 /video/ 之后、? 之前的片段作为 ID;否则抛出 TypeError,并提示受支持的 URL 示例 https://www.tiktok.com/@therock/video/6829267836783971589。
这一点也被测试 tests/test_video.py 验证:api.video(url="https://www.tiktok.com/@davidteathercodes/video/7074717081563942186") 解析出的 video.id 被断言等于 "7074717081563942186"。注意测试中移动端短链 https://www.tiktok.com/t/ZT8LCfcUC/ 是注释掉的状态,说明该场景在当前版本中并非受保障的路径。
四、video.info():拉取视频完整数据
info()(TikTokApi/api/video.py)返回一个包含视频全部数据的字典。它的核心特征是:这是一次针对视频页面 HTML 的 HTTP 请求,而不是直接调用结构化 JSON 接口,因此源码 docstring 明确提示"This is slow since it requires an HTTP request, avoid using this if possible."。
前置条件
调用前必须已设置 self.url,否则抛出 TypeError("To call video.info() you need to set the video's url.")。因此在实践中,应通过 api.video(url=...) 构造对象后再调用 info()。
请求与状态码校验
方法通过 requests.get(self.url, headers=session.headers, proxies=proxy) 抓取页面;若状态码非 200,则抛出 InvalidResponseException,并携带 error_code(异常基类见 TikTokApi/exceptions.py,InvalidResponseException 继承自 TikTokException,包含 raw_response、message、error_code 三个字段)。
双路径 JSON 解析
拿到 HTML 后,info() 依次尝试两种内嵌 JSON 的提取路径:
路径一:SIGI_STATE(优先)
定位 <script id="SIGI_STATE" type="application/json"> 标签,截取其中 JSON,然后直接取 data["ItemModule"][self.id] 作为视频数据。
路径二:__UNIVERSAL_DATA_FOR_REHYDRATION__(兜底)
若页面中没有 SIGI_STATE 标签,则改为查找 <script id="__UNIVERSAL_DATA_FOR_REHYDRATION__" type="application/json">;随后按 __DEFAULT_SCOPE__ → webapp.video-detail 的结构取数据:
- 若
video_detail.get("statusCode", 0) != 0,判定响应结构无效并抛InvalidResponseException; - 再取
video_detail["itemInfo"]["itemStruct"]作为video_info,若为None同样抛异常。
两条路径中任何一步找不到对应标签或 </script> 结束符,都会抛出 InvalidResponseException。
结果写入与会话 Cookie 同步
解析成功后,self.as_dict = video_info 并调用 __extract_from_data() 反序列化;随后把本次请求拿到的 cookies 通过 requests_cookie_to_playwright_cookie(TikTokApi/helpers.py)转换为 Playwright 格式,再调用 self.parent.set_session_cookies(session, cookies) 写回会话上下文(对应 TikTokApi/tiktok.py),让后续基于该会话的请求带上更新后的 Cookie。
url = "https://www.tiktok.com/@davidteathercodes/video/7106686413101468970"
video_info = await api.video(url=url).info()
测试 tests/test_video.py 中验证了 data["id"] == video_id,并断言 video.author.username == "davidteathercodes",说明 info() 返回的数据结构与作者解析均可用。
五、video.bytes():下载与流式下载视频字节
bytes()(TikTokApi/api/video.py)负责返回视频的原始字节,支持一次性下载与流式两种模式。源码 docstring 标注为 "TODO: Not implemented yet",测试 tests/test_video.py 也处于 pytest.skip("Not implemented yet") 状态,因此该接口属于实验性能力,使用前需自行验证。
下载地址与请求头
方法从 self.as_dict["video"]["downloadAddr"] 取下载地址,因此必须先让对象持有数据(通过 data= 构造或先调用 info())。随后构造请求头:
h = session.headers
h["range"] = 'bytes=0-'
h["accept-encoding"] = 'identity;q=1, *;q=0'
h["referer"] = 'https://www.tiktok.com/'
同时从会话读取 cookies 一并携带。
stream=False:一次性下载
默认模式用 requests.get(downloadAddr, headers=h, cookies=cookies) 取回全部内容,返回 bytes:
video_bytes = await api.video(id='7041997751718137094').bytes()
# Saving The Video
with open('saved_video.mp4', 'wb') as output:
output.write(video_bytes)
stream=True:流式下载
流式模式返回一个异步迭代器,内部用 httpx.AsyncClient 发起 GET 并按块产出字节,适合边下载边处理或转存大文件:
async for chunk in api.video(id='7041997751718137094').bytes(stream=True):
# Process or upload chunk
注意:由于 bytes() 依赖 as_dict["video"]["downloadAddr"],若对象是用 url= 构造且尚未调用 info(),该键会缺失并触发 KeyError。
六、video.comments():分页遍历评论
comments()(TikTokApi/api/video.py)以异步生成器返回该视频的评论:
- 参数:
count(期望返回的评论条数,默认 20)、cursor(从 0 开始的偏移量)、以及透传给make_request的headers/session_index等 kwargs; - 请求:对
https://www.tiktok.com/api/comment/list/发起请求,params 为{"aweme_id": self.id, "count": 20, "cursor": cursor}; - 分页:每页固定请求 20 条,遍历响应中的
comments列表,逐条yield self.parent.comment(data=video)转成Comment对象并累计found;当响应中has_more为假或已取够count条时结束;has_more为真时用响应的cursor继续翻页; - 异常:
make_request返回None时抛InvalidResponseException。
调用示例:
async for comment in api.video(id='7041997751718137094').comments():
# do something
make_request 的底层链路在 TikTokApi/tiktok.py:它会合并会话参数与请求参数、自动补充 msToken、通过 sign_url 生成 X-Bogus 签名(依赖页面中的 window.byted_acrawler.frontierSign,见 TikTokApi/tiktok.py),随后在 Playwright 页面里执行 fetch 脚本,并对 JSON 解析失败做最多 3 次重试(默认指数退避)。也就是说,comments() 每次翻页都完整经历"参数合并 → 签名 → 浏览器内 fetch → JSON 解码"的请求管线。
七、video.related_videos():相关视频推荐
related_videos()(TikTokApi/api/video.py)返回与当前视频相关的视频列表,同样以异步生成器分页产出:
- 参数:
count(默认 30)、cursor(默认 0)及透传 kwargs; - 请求:对
https://www.tiktok.com/api/related/item_list/发起请求,params 为{"itemID": self.id, "count": 16},即每页固定 16 条; - 产出:遍历响应中的
itemList,逐条yield self.parent.video(data=video),即直接以原始数据构造新的Video对象(数据入口,无需额外请求)。
async for related_videos in api.video(id='7041997751718137094').related_videos():
# do something
测试 tests/test_video.py 用 count=10 遍历并断言 count >= 10,确认该接口能稳定产出指定数量的相关视频。
八、数据反序列化:__extract_from_data 与关联对象构建
无论走哪条路径拿到原始数据,最终都会进入 __extract_from_data()(TikTokApi/api/video.py),把原始字典映射到 Video 的各个属性:
def __extract_from_data(self) -> None:
data = self.as_dict
self.id = data["id"]
timestamp = data.get("createTime", None)
if timestamp is not None:
try:
timestamp = int(timestamp)
except ValueError:
pass
self.create_time = datetime.fromtimestamp(timestamp)
self.stats = data.get('statsV2') or data.get('stats')
author = data.get("author")
if isinstance(author, str):
self.author = self.parent.user(username=author)
else:
self.author = self.parent.user(data=author)
self.sound = self.parent.sound(data=data)
self.hashtags = [
self.parent.hashtag(data=hashtag) for hashtag in data.get("challenges", [])
]
if getattr(self, "id", None) is None:
Video.parent.logger.error(...)
要点:
- id:强制取
data["id"],缺失时记录错误日志; - create_time:从
createTime字段(秒级时间戳)经int()容错后转换为本地datetime; - stats:优先取
statsV2,取不到则回退到stats(TikTok 不同时期字段结构有差异); - author:若
author是字符串则视为用户名(self.parent.user(username=author)),否则视为数据字典构造User; - sound:将整个视频数据字典传给
self.parent.sound(data=data),由Sound.__extract_from_data自行解析musicInfo/music字段(见 TikTokApi/api/sound.py); - hashtags:遍历
challenges列表,每个标签构造一个Hashtag对象(TikTokApi/api/hashtag.py)。
集成测试 tests/test_integration.py 恰好验证了这条关联链:遍历 hashtag funny 下的视频时,断言 video.sound 及其 id 非空、video.author 及其 user_id / sec_uid 非空,且视频的 hashtags 中确实包含 funny 标签。
九、端到端示例与测试验证
仓库中的 examples/video_example.py 给出了 Video 模块的完整使用流程:
from TikTokApi import TikTokApi
import asyncio
import os
ms_token = os.environ.get(
"ms_token", None
) # set your own ms_token, think it might need to have visited a profile
async def get_video_example():
async with TikTokApi() as api:
await api.create_sessions(ms_tokens=[ms_token], num_sessions=1, sleep_after=3)
video = api.video(
url="https://www.tiktok.com/@davidteathercodes/video/7074717081563942186"
)
async for related_video in video.related_videos(count=10):
print(related_video)
print(related_video.as_dict)
video_info = await video.info() # is HTML request, so avoid using this too much
print(video_info)
video_bytes = await video.bytes()
with open("video.mp4", "wb") as f:
f.write(video_bytes)
if __name__ == "__main__":
asyncio.run(get_video_example())
可运行方式(README 中也提到用 -m 运行示例脚本):python -m examples.video_example。运行前需要:
- 安装依赖:
pip install TikTokApi与python -m playwright install(README 要求 Python 3.9+,当前仓库 setup.py 中python_requires=">=3.9"); - 设置
ms_token环境变量:从登录 TikTok 网页后的 Cookie 中获取; TikTokApi是异步上下文管理器,create_sessions会启动 Playwright 浏览器会话池(默认 chromium,headless场景使用--headless=new参数,详见 TikTokApi/tiktok.py),结束时会自动关闭全部会话与浏览器。
对应的自动化测试集中在 tests/test_video.py,覆盖:URL 解析 ID、info() 数据一致性、related_videos() 数量与 bytes()(跳过)四个用例,可作为接入或回归验证的参考。
十、使用约束与性能注意事项
综合源码与文档,使用 Video 模块时有几点需要留意:
info()是慢操作:它抓取完整 HTML 并解析内嵌 JSON,源码 docstring 建议"避免频繁调用";批量场景应优先复用已通过data=构造的对象,或从用户、hashtag、sound 等列表接口直接获得数据字典。bytes()尚未完全就绪:源码标注 TODO 且测试被跳过,依赖as_dict["video"]["downloadAddr"],务必先确保对象持有数据。- 结构化接口走签名管线:
comments()与related_videos()经由make_request,依赖会话内的msToken与X-Bogus签名,因此必须先create_sessions且会话需拿到有效msToken;否则会打印 "Failed to get msToken ... (probably will fail)" 警告(见 TikTokApi/tiktok.py)。 - 异常统一出口:网络或结构异常统一以
InvalidResponseException(携带error_code与raw_response)抛出,可据此区分重试策略。 - 数据字段会变化:TikTok 会不定期调整页面结构与 JSON 字段(如
stats与statsV2、ItemModule与webapp.video-detail的切换),因此依赖as_dict原始字典时建议先探查实际结构。
至此,围绕 .sphinx/api/video.rst 所展开的 TikTokApi.api.video 模块 API 参考即完整呈现:从构造入口、四个公开异步方法,到数据反序列化、底层请求管线与测试验证,均可对照源码 TikTokApi/api/video.py、示例 examples/video_example.py 与测试 tests/test_video.py 逐一印证。