tiktok-collection-scraper

TikTok 收藏夹抓取工具

批量提取 TikTok 用户的收藏夹及其中的视频链接，包括播放量、点赞数、评论数和分享数。无需外部 API，无需付费服务，只需 curl_cffi。

功能

• 🔓 无需登录 — 无需 Cookie 即可访问公开收藏夹（覆盖率约为 80%）
• 🔑 使用 Cookie 获取完整访问权限 — 获取所有收藏夹，包括私密收藏夹（覆盖率 100%）
• 🚀 无需外部 API — 只需 curl_cffi，无需 TikHub/RapidAPI/付费服务
• 📥 支持 7 种输入格式 — 用户名、@用户名、个人资料 URL、视频 URL、短链接、user_id、secUid
• 📊 丰富的元数据 — 每个视频的播放量、点赞数、评论数和分享数
• ⚡ 速度快 — 约 40 秒可抓取 50 个收藏夹和 300 个视频

前置条件

确保已安装 curl_cffi：

pip install curl_cffi

快速开始

运行随附的脚本。以下所有路径均相对于此技能目录。

# Guest mode (public collections, no cookie needed)
python3 scripts/scrape_collections.py <target> -o /tmp/result.json

# Login mode (all collections, 100% coverage)
python3 scripts/scrape_collections.py <target> --cookie /path/to/cookie.txt -o /tmp/result.json

支持的输入格式

格式	示例
用户名	chengfeng_yulin
@用户名	@chengfeng_yulin
个人资料 URL	https://www.tiktok.com/@chengfeng_yulin
视频 URL	https://www.tiktok.com/@user/video/7602514407133941000
短链接	https://vm.tiktok.com/ZMkVKQxsb/
用户 ID	6811802142106764293
secUid	MS4wLjABAAAA...

输出格式

JSON 结构如下：

{
  "target": "chengfeng_yulin",
  "secUid": "MS4wLjAB...",
  "uid": "68118...",
  "uniqueId": "chengfeng_yulin",
  "mode": "guest",
  "totalCollections": 50,
  "totalVideos": 308,
  "elapsedSeconds": 40.0,
  "collections": [
    {
      "collectionId": "760379...",
      "name": "收藏夹名称",
      "expected": 3,
      "actual": 3,
      "items": [
        {
          "id": "760251...",
          "url": "https://www.tiktok.com/@author/video/760251...",
          "desc": "Video description...",
          "author": "author_username",
          "plays": 2000000,
          "likes": 25100,
          "comments": 632,
          "shares": 85000
        }
      ]
    }
  ]
}

Cookie

• 公开收藏夹无需 Cookie（status=3，通常约占文件夹的 50%、视频的 80%）
• 私密收藏夹需要 Cookie（status=1）——必须使用目标账号本人的登录 Cookie
• Cookie 格式：从浏览器获取的原始 Cookie 字符串（以分号分隔的 key=value 键值对）

工作原理

使用 TikTok 内部 Web API，并通过 curl_cffi 模拟 Chrome TLS 指纹：

1. 解析用户 — 任意输入格式 → secUid（通过 TikTok 自身的重定向和页面解析）
2. 获取收藏夹 — GET /api/user/collection_list/（无需身份验证）
3. 获取视频 — GET /api/collection/item_list/，使用 sourceType=113（未公开的关键参数）

sourceType=113 是通过拦截浏览器请求发现的未公开参数。如果不传此参数，API 会返回成功响应，但结果为空。

完整 API 文档请参阅 references/api-notes.md。

错误处理

• ⚠️ = 返回的视频数量少于预期（可能有视频已删除）
• ❌ = 未返回任何视频（视频已移除或 API 出现问题）
• 脚本最多重试失败的请求 3 次，每次间隔 5 秒
• 进度输出到 stderr；JSON 输出到 stdout（或使用 -o 输出到文件）