Twitch User Videos
Twitchユーザーの動画は、チャンネルで公開されている過去の配信、ハイライト、アップロード動画で、説明文、クリエイター情報、メディア参照、再生時間、公開日時、表示中のエンゲージメントを含みます。これらのレコードは、チャンネルの動画カタログ作成、形式の比較、公開傾向の調査、特定時点のパフォーマンスレポートに活用できます。
Twitch User Videos API の主な機能
- ユーザー名単位の動画一覧公開Twitchユーザー名を1件照会し、1回のソースリクエストでそのチャンネルについて返された動画レコードを取得します。
- 過去の配信・ハイライト・アップロードのフィルターすべての動画を対象にするか、使用可能な archive、highlight、upload の値(および複数形のエイリアス)でソースリクエストを絞り込みます。
- 公開日時または視聴数での並べ替え返されるソースページを公開日時または表示中の視聴数で並べ替え、最近公開された動画や視聴数の多い動画を確認できます。
- 正規化された動画レコード動画ID、公開URL、説明文、クリエイター情報、メディア、再生時間、公開日時、音声メタデータ、表示中のエンゲージメントを ReelVideoItem 構造で返します。
Twitch User Videos API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
username | 必須 | 公開Twitchユーザー名を1件指定します。先頭に @ を付けることもでき、英字、数字、ドット、アンダースコア、ハイフンで構成される1〜64文字です。 |
filter_by | 任意 | 任意。ソースの種類で、all、archive、archives、highlight、highlights、upload、uploads のいずれかです。単数形と複数形のエイリアスは同じ提供元カテゴリに対応します。 |
sort_by | 任意 | 任意。ソースの並び順で、time または views を指定します。 |
Twitch User Videos API の使い方
Twitchユーザー名を、任意の動画種類と並び順の指定とともに送信し、標準の非同期タスクの流れで1ページ分のソース結果を読み取ります。
- 公開Twitchユーザー名を選び、ソースページの対象をすべての動画にするか、使用可能な動画種類のいずれかにするかを決めます。
- username、filter_by、sort_by を /v1/twitch/user-videos に POST し、返されたタスクIDを保存します。
- タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。タスクIDを取得した後は再送信しないでください。
- results.items から ReelVideoItem レコードを読み取り、next_cursor は保存済みのタスク結果の行をページ送りする場合にのみ使用します。
curl -X POST "https://api.socq.ai/v1/twitch/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"ninja","filter_by":"all","sort_by":"time"}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50Twitch User Videos API の主なユースケース
- チャンネル動画のカタログ作成: 動画ID、公開URL、説明文、メディア参照、再生時間、クリエイター情報を使い、既知のチャンネルの最新の動画一覧を作成します。
- 動画形式の構成比の確認: 使用可能な種類フィルターごとに個別に実行し、過去の配信、ハイライト、アップロード動画のレコードを公開日時や再生時間で比較します。
- 公開状況と視聴数のスナップショット: 公開日時のタイムスタンプを、表示中の視聴数・再生数の指標や collected_at と組み合わせ、特定時点のチャンネルのスナップショットを記録します。
Twitch User Videos API 活用のヒント
- ユーザー名を指定する際はプロフィールURLを取り除き、任意の @ と、使用可能な1〜64文字のユーザー名だけを残してください。
- 返されたソースページ内で、最近の公開状況を確認するには time を、視聴数の多いレコードを確認するには views を使用してください。
- 単数形と複数形のエイリアスはそれぞれ同じ上流カテゴリに対応するため、保存するリクエスト定義ではどちらか一方に統一してください。
- 送信ペイロードに cursor や results_limit を追加しないでください。提供元の呼び出しは1ページを返し、タスク結果のカーソルはSocQがすでに保存した行をページ送りするだけです。
- 長期にわたる取得結果は動画IDで重複を排除し、テキスト、メディア、音声、投稿者、タイムスタンプ、指標の各フィールドが null になる場合に備えてください。
関連API
Twitch User Videos API 以外に別の種類の公開Twitchデータが必要な場合は、これらのAPIをご利用ください。
- Twitch Profile API — 公開Twitchユーザー名1件から正規化されたアカウントレコードを取得し、取得可能なアカウント情報、プロフィール文、画像、アカウント属性、表示中の指標、取得情報を返します。
- Twitch Clip Downloader API — クリップURLから公開Twitchクリップを1件取得し、タイトル、再生数、長さ、作成日時、配信者プロフィール、ダウンロードできるMP4リンクとサムネイルを返します。