クリップは、視聴者がTwitchの配信から切り出した短いハイライトで、X、Reddit、Discordで共有されるのはこのクリップです。印象的な場面をアーカイブしたり、クリップがどこまで広がったかを測定したり、転載時に正しいチャンネルをクレジット表記したりするには、クリップのデータと動画ファイルを、コードで保存できる形で取得する必要があります。
2026-11-17、SocQはTwitch Clip Downloader APIを、既存のTwitch ProfileとUser Videosのエンドポイントと並べてTwitchのプラットフォームページに追加しました。このガイドでは、返す内容、リクエスト、料金、そして事前に考慮しておくべき制限を解説します。
結論:
{"url": "<clip URL>"}をPOST https://api.socq.ai/v1/twitch/clipに送信します。返されたtask_idを保存し、statusがsucceededになるまでGET /v1/tasks/{task_id}をポーリングしてから、data.results.items内の1件のレコードを読み取ります。各リクエストは0.5クレジット($0.0025)です。動画ファイルのリンクは約1日で期限切れになるため、早めにダウンロードしてください。
エンドポイントが返す内容
1 SocQクレジット = $0.005です。
| エンドポイント | 返す内容 | 料金 |
|---|---|---|
| Twitch Clip Downloader API | 1件のクリップ:タイトル、再生回数、長さ、作成日時、アバター付きの配信者、動画ファイル、サムネイル | 1回の呼び出しあたり0.5クレジット($0.0025) |
レコードはSocQの標準の動画スキーマを使います。クリップで重要なフィールドは次のとおりです。
| フィールド | 意味 |
|---|---|
id | Twitchの数値のクリップID |
shortcode | URLに含まれるクリップのスラッグ |
url | クリップのURL |
text | クリップのタイトル |
published_at | クリップが作成された日時(ISO 8601) |
duration_seconds | クリップの長さ(秒) |
metrics.views_count | クリップの再生回数 |
author | 配信者:id、username、name、url、avatar_url、is_verified |
media[0].url | クリップのMP4ファイル |
media[0].thumbnail_url | クリップのサムネイル |
collected_at | SocQがレコードを収集した日時 |
スキーマで定義されたフィールドは、値がない場合でもレコードに残ります。ドキュメントの例では、27秒のクリップが views_count: 69776 を返す一方で、metrics.likes_count、metrics.comments_count、hashtags、audio は null です。
認証と非同期タスクの流れ
すべてのリクエストはAPIキーで認証します。送信、タスクのステータス確認、結果の取得のいずれにも同じヘッダーを使います。
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
収集処理はすべてバックグラウンドのタスクとして実行されます。
submit -> task_id -> queued -> running -> succeeded
\-> failed
送信のリクエストは、data.task_id と data.status をすぐに返します。そのIDでタスクをポーリングします。
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
status が succeeded になると、レスポンスには result_count、credits_amount、そして data.results.items にレコードが含まれます。失敗したタスクには error_message が含まれます。クライアント側でタイムアウトしてもタスクはキャンセルされないため、再送信せずに同じタスクIDで再開してください。402 はアカウントのクレジット不足、429 はキーがレート制限またはクレジットの上限に達したことを意味します。
ほとんどのSocQエンドポイントとは異なり、Clip Downloaderのリクエストボディが受け付けるのは url だけです。callback_url は含まれていないため、タスクをポーリングしてください。
クリップをリクエストする
url にクリップのURLを1つ渡します。twitch.tv/<channel>/clip/<slug> と clips.twitch.tv/<slug> のどちらの形式も使えます。(ドキュメント)
curl -X POST "https://api.socq.ai/v1/twitch/clip" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.twitch.tv/staryuuki/clip/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"}'
各リクエストは1つのURLを受け取り、1行を返します。まとめて処理する場合は、クリップごとに1つのタスクを送信し、再試行で同じクリップを二重に送信しないよう、各 task_id をURLと対応づけて保存してください。
リンクの期限が切れる前に動画をダウンロードする
media[0].url のリンクは署名付きで、約1日で期限切れになります。クリップのコピーが必要な場合は、タスクが成功したらすぐにダウンロードし、自前のストレージに保存してください。元のリンクが必要になったときにクリップを再リクエストできるよう、レコードの id、shortcode、url をファイルとあわせて保存しておきます。
最小限のPythonの処理の流れは次のとおりです。
import os, time, requests
API = "https://api.socq.ai"
headers = {"Authorization": f"Bearer {os.environ['SOCQ_API_KEY']}"}
clip_url = "https://clips.twitch.tv/CloudySavageMarjoramRuleFive--ErzsYbE7UWvgCMQ"
task = requests.post(f"{API}/v1/twitch/clip", headers=headers,
json={"url": clip_url}).json()["data"]
while task["status"] in ("queued", "running"):
time.sleep(3)
task = requests.get(f"{API}/v1/tasks/{task['task_id']}",
headers=headers).json()["data"]
if task["status"] != "succeeded":
raise RuntimeError(task.get("error_message"))
clip = task["results"]["items"][0]
video = requests.get(clip["media"][0]["url"], timeout=60)
with open(f"{clip['shortcode']}.mp4", "wb") as f:
f.write(video.content)
大規模に実行する前に、HTTPステータスのチェック、回数を制限した再試行、ログ出力を追加してください。
使いどころ
- ハイライトのアーカイブ。 自社チャンネルや所属タレントのクリップを、元のリンクが変わる前に、タイトル、作成日時、再生回数とあわせて保存します。
- リーチの追跡。 クリップが共有された後に再実行し、
metrics.views_countを最初のスナップショットと比較します。チェック1回あたり0.5クレジットです。 - クレジット表記。
authorにはその場面を配信した配信者がプロフィールリンク付きで入るため、転載時に正しいチャンネルをクレジットできます。 - コンテンツのパイプライン。 MP4を編集、字幕付け、ショート動画への再活用に回します。
費用の見積もり: 料金は定額のため、100件のクリップで50クレジット($0.25)、1,000件で500クレジット($2.50)です。追跡中の50件のクリップについて毎週再生回数をチェックすると、1週間あたり25クレジット($0.125)です。
動画を再利用する際は、配信者とクリップに映っているすべての人の権利を尊重し、Twitchの利用規約に従ってください。
関連するTwitchエンドポイント
クリップのレコードから、誰が配信したかがわかります。そこからチャンネルの情報を取得するには、次のエンドポイントを使います。
- Twitch Profile APIは、
usernameから公開されているTwitchのプロフィールを返します。 - Twitch User Videos APIは、ユーザーの公開動画を1ページ分返し、
filter_by(archive、highlight、uploadなど)とsort_by(timeまたはviews)を指定できます。
クリップの author.username をどちらかに渡してください。ほかのプラットフォームのクリップや動画を同じ正規化された形式で取得するには、TikTokスクレイピングガイドとYouTube スクレイパーAPIおすすめ7選をご覧ください。
よくある質問(FAQ)
Twitch Clip Downloader APIの料金はいくらですか?
1リクエストあたり0.5クレジット、つまり$0.0025です。各リクエストは1件のクリップを返します。
どのような形式のクリップURLが使えますか?
https://www.twitch.tv/<channel>/clip/<slug> と https://clips.twitch.tv/<slug> です。
動画のリンクはどのくらい有効ですか?
リンクは署名付きで、約1日で期限切れになります。コピーが必要な場合は、すぐにファイルをダウンロードしてください。
1回のリクエストで複数のクリップを送信できますか?
いいえ。url が受け付けるのはクリップのURL 1つだけです。クリップごとに1つのタスクを送信してください。
クリップのいいね数やコメント数は返されますか?
レコードには再生回数が含まれます。ドキュメントの例では likes_count と comments_count が null なので、これらを前提にしないでください。