tiktok-collection-scraper

TikTok コレクションスクレイパー

TikTok ユーザーのコレクションフォルダーと動画リンクを一括で抽出します。再生数、いいね数、コメント数、シェア数も取得します。外部 API や有料サービスは不要で、curl_cffi だけで利用できます。

機能

• 🔓 ログイン不要 — 公開コレクションなら Cookie なしで動作します（約 80％をカバー）
• 🔑 Cookie があればすべて取得 — 非公開のものも含むすべてのコレクションを取得できます（100％）
• 🚀 外部 API 不要 — 必要なのは curl_cffi だけで、TikHub／RapidAPI／有料サービスは不要です
• 📥 7 種類の入力形式 — ユーザー名、@ユーザー名、プロフィール URL、動画 URL、短縮リンク、user_id、secUid
• 📊 詳細なメタデータ — 動画ごとの再生数、いいね数、コメント数、シェア数
• ⚡ 高速 — 50 件のコレクションと 300 本の動画を約 40 秒で取得できます

前提条件

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

• 公開コレクション（status=3。通常、フォルダーの約 50％、動画の約 80％）には不要です
• 非公開コレクション（status=1）には必要です。対象アカウント自身のログイン Cookie を指定する必要があります
• Cookie の形式：ブラウザーから取得した生の Cookie 文字列（セミコロン区切りの key=value ペア）

仕組み

curl_cffi を使って Chrome の TLS フィンガープリントを偽装し、TikTok の内部 Web API を利用します。

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 を参照してください。

エラー処理

• ⚠️ = 予想より動画数が少ない場合（動画が削除されている可能性があります）
• ❌ = 動画が 0 件返された場合（動画が削除されたか、API に問題があります）
• スクリプトは失敗したリクエストを 5 秒間隔で最大 3 回再試行します
• 進捗は stderr に出力され、JSON は stdout（または -o で指定したファイル）に出力されます