Twitch Profile
공개 Twitch 프로필에는 사용자 이름, 표시 이름, 소개글, 프로필 이미지, 웹사이트, 인증·비공개 신호, 위치 정보, 공개된 계정 수치가 노출될 수 있습니다. 정규화된 계정 레코드는 크리에이터 정보 보강, 프로필 확인, 반복 가능한 공개 데이터 스냅샷에 활용할 수 있으며, 채널 관리나 로그인이 필요한 계정 작업은 제공하지 않습니다.
Twitch Profile API 주요 기능
- 정확한 사용자 이름 조회지원되는 문자 1~64자로 이루어진 사용자 이름 하나를 필수로 제출하며, 맨 앞에 @를 하나만 붙일 수 있습니다.
- 정규화된 공개 계정 정보AccountItem 사양에 맞춰 프로필 ID, 공개 URL, 사용자 이름, 표시 이름, 소개글, 아바타, 커버 이미지, 웹사이트를 확인할 수 있는 범위에서 읽어 옵니다.
- 계정 상태 신호제공처가 노출하지 않는 값을 추정하지 않고, 인증·비공개 속성은 확인 가능한 경우에만 null 허용 필드로 보존합니다.
- 공개된 프로필 수치팔로워·팔로잉·게시물 수를 각각 별도의 선택 수치로 제공하며, 모두 수집 시점과 함께 기록됩니다.
- 비동기 작업 흐름사용자 이름을 제출하고 task_id를 저장한 뒤 공용 작업 조회로 폴링하면, 성공 후 저장된 정규화 결과를 가져올 수 있습니다.
- 고정 요청 요금성공한 작업은 선택 필드의 제공 여부와 관계없이 SocQ 0.19 크레딧이 고정으로 차감됩니다.
Twitch Profile API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
username | 필수 | 필수 Twitch 사용자 이름입니다. 앞뒤 공백을 제거한 뒤 맨 앞에 @를 하나 붙일 수 있으며, 그 뒤에는 ASCII 영문자, 숫자, 마침표, 밑줄, 하이픈이 1~64자 들어가야 합니다. |
Twitch Profile API 사용 방법
지원되는 Twitch 사용자 이름 하나를 제출하고, 비동기 작업을 추적한 뒤, 공용 커서 응답에서 저장된 프로필 결과 하나를 읽습니다.
- 지원되는 문자 규칙에 맞는 공개 Twitch 사용자 이름을 하나 고릅니다.
- username을 /v1/twitch/profile로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패가 보고될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽습니다. 프로필 조회는 원본 레코드를 최대 1건 만들지만, 저장된 결과 엔벨로프에는 has_more와 next_cursor가 그대로 포함됩니다.
curl -X POST "https://api.socq.ai/v1/twitch/profile" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"ninja"}'
# Poll GET /v1/tasks/{task_id}
# Read the normalized account in data.results.itemsTwitch Profile API 추천 활용 사례
- 크리에이터 레코드 정보 보강: 이미 알고 있는 크리에이터 레코드에 확인 가능한 Twitch 계정 정보, 소개글, 이미지, 웹사이트, 계정 속성, 공개 수치를 추가합니다.
- 사용자 이름 검증 워크플로: 제출된 핸들을 정규화된 공개 프로필로 조회한 뒤, 내부 엔티티나 조사 대상과 연결합니다.
- 공개 계정 비교: 따로 제출한 사용자 이름들의 공개 팔로워·팔로잉·게시물 수를 동일한 AccountItem 형태로 비교합니다.
- 프로필 변경 모니터링: null 허용 계정 정보 필드와 수치를 collected_at과 함께 저장해, 이후 실행분과 구분되는 공개 스냅샷으로 남깁니다.
Twitch Profile API 활용 팁
- Twitch 채널 URL이 아니라 사용자 이름을 제출하세요. 이 엔드포인트는 url과 results_limit 요청 필드를 받지 않습니다.
- 맨 앞의 @는 하나만 사용하세요. 공백, 슬래시, 비ASCII 문자, 중복된 @는 런타임 사용자 이름 규칙에 맞지 않아 실패합니다.
- 원본 프로필 레코드는 0건 또는 1건입니다. 작업 조회의 limit 매개변수로 프로필을 동영상이나 팔로워로 확장할 수 있다고 생각하지 마세요.
- ID, URL, 소개글, 이미지, 웹사이트, 계정 속성, 위치, 각 수치는 모두 null일 수 있다고 보고 처리하며, 스냅샷 비교를 위해 collected_at을 보존하세요.
- 동영상이나 클립이 필요하면 제공되는 별도의 Twitch 콘텐츠 엔드포인트를 사용하세요. 이 엔드포인트는 읽기 전용 프로필 조회이며 로그인, 게시, 운영 관리, 채널 관리를 하지 않습니다.
관련 API
Twitch Profile API 외에 Twitch의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitch User Videos API
- Twitch Clip Downloader API — 클립 URL로 공개 Twitch 클립 하나를 가져와 제목, 조회수, 길이, 생성 시각, 스트리머 프로필, 내려받을 수 있는 MP4 링크와 썸네일을 반환합니다.