Twitch User Videos
Twitch 사용자 동영상은 채널의 공개 다시보기, 하이라이트, 업로드 영상으로, 설명, 크리에이터 정보, 미디어 참조, 길이, 게시 시각, 공개된 참여 수치를 담고 있습니다. 이러한 레코드는 채널 카탈로그 구축, 포맷 비교, 게시 패턴 조사, 특정 시점의 성과 리포트에 활용할 수 있습니다.
Twitch User Videos API 주요 기능
- 사용자 이름 기준 동영상 목록공개 Twitch 사용자 이름 하나를 조회해, 한 번의 원본 요청으로 해당 채널의 동영상 레코드를 반환합니다.
- 다시보기·하이라이트·업로드 필터전체 동영상을 선택하거나, archive, highlight, upload 값(복수형 별칭 포함)으로 원본 요청 범위를 좁힐 수 있습니다.
- 시간순 또는 조회수순 정렬반환되는 원본 페이지를 시간 또는 공개 조회수 기준으로 정렬해, 최근 게시된 동영상이나 조회수가 높은 동영상을 확인합니다.
- 정규화된 동영상 레코드동영상 ID, 공개 URL, 설명, 크리에이터 정보, 미디어, 길이, 게시 시각, 오디오 메타데이터, 공개된 참여 수치를 ReelVideoItem 구조로 반환합니다.
Twitch User Videos API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
username | 필수 | 공개 Twitch 사용자 이름 하나이며, 맨 앞에 @를 붙일 수 있습니다. 영문자, 숫자, 마침표, 밑줄, 하이픈을 1~64자 사용할 수 있습니다. |
filter_by | 선택 | 선택 사항인 원본 유형입니다: all, archive, archives, highlight, highlights, upload, uploads. 단수형과 복수형 별칭은 같은 제공처 카테고리로 처리됩니다. |
sort_by | 선택 | 선택 사항인 원본 정렬 기준입니다: time 또는 views. |
Twitch User Videos API 사용 방법
Twitch 사용자 이름에 동영상 유형·정렬 옵션을 선택해 제출하고, 표준 비동기 작업 흐름으로 원본 페이지 한 개를 읽습니다.
- 공개 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을 추가하지 마세요. 제공처 호출은 한 페이지만 반환하며, 작업 결과의 cursor는 SocQ에 이미 저장된 행만 넘겨 봅니다.
- 장기간 수집한 데이터는 동영상 ID로 중복을 제거하고, 텍스트·미디어·오디오·작성자·타임스탬프·수치 필드가 null일 수 있음을 감안하세요.
관련 API
Twitch User Videos API 외에 Twitch의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitch Profile API — 공개 Twitch 사용자 이름 하나를 정규화된 계정 레코드로 변환하며, 확인 가능한 계정 정보, 소개글, 이미지, 계정 속성, 공개된 지표, 수집 맥락을 포함합니다.
- Twitch Clip Downloader API — 클립 URL로 공개 Twitch 클립 하나를 가져와 제목, 조회수, 길이, 생성 시각, 스트리머 프로필, 내려받을 수 있는 MP4 링크와 썸네일을 반환합니다.