TikTok Live Room Info
TikTok 라이브 방송 정보는 진행 중인 공개 방송 하나를 특정 시점에 포착한 결과로, 제목, 상태, 방송 주인 정보, 커버 이미지, 공개된 시청자 수와 좋아요 수를 담고 있습니다. 이러한 필드는 이미 알고 있는 방송의 라이브 상태 확인, 시청자 스냅샷, 방송 정보 보강, 시각이 기록된 보고에 활용할 수 있습니다.
TikTok Live Room Info API 주요 기능
- 방 ID와 방송 주인 ID 한 쌍으로 조회알고 있는 라이브 방송 하나를 room_id와 그에 맞는 방송 주인의 user_id로 찾아, 정규화된 live_room 레코드를 최대 1건 반환합니다.
- 방송과 방송 주인 정보현재 방송 제목과 상태를 방송 주인의 공개 ID, 사용자 이름, 표시 이름과 함께 반환합니다.
- 시청자 수와 커버 스냅샷공개된 시청자 수, 좋아요 수, 공개 커버 이미지, 수집 시각을 담아 특정 시점의 상태로 해석할 수 있게 합니다.
TikTok Live Room Info API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
room_id | 필수 | 라이브 방송 식별자로, 비어 있지 않아야 하는 필수 값입니다. 현재 TikTok 라이브 세션을 확인할 수 있는 출처에서 얻은 숫자 식별자를 문자열로 전달하세요. |
user_id | 필수 | 방송 주인의 TikTok 숫자 사용자 식별자로, 비어 있지 않아야 하는 필수 값입니다. 문자열로 전달하며 같은 방송과 한 쌍이어야 합니다. |
TikTok Live Room Info API 사용 방법
진행 중인 방송 하나의 식별자를 한 쌍으로 준비해 비동기 조회를 제출한 뒤, 작업 결과에서 정규화된 스냅샷을 읽습니다.
- 현재 TikTok 라이브 세션을 확인할 수 있는 출처에서 room_id를 얻고, 같은 맥락이나 TikTok Profiles 결과에서 그에 맞는 방송 주인의 user_id를 얻습니다.
- 비어 있지 않은 문자열인 두 식별자를 /v1/tiktok/live-room-info로 POST합니다.
- status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- /v1/tasks/{task_id}?limit=50에서 data.results.items를 읽습니다. 조회된 방송은 레코드를 최대 1건 만들며, 표준 next_cursor는 results.has_more가 true일 때만 적용됩니다.
curl -X POST "https://api.socq.ai/v1/tiktok/live-room-info" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"room_id":"7523685855395842871","user_id":"6742945285876515845"}'
# Poll GET /v1/tasks/{task_id}, then read data.results.items from /v1/tasks/{task_id}?limit=50.TikTok Live Room Info API 추천 활용 사례
- 특정 시점의 라이브 상태 확인: 반환된 status, 제목, 방 ID, collected_at 값으로 알고 있는 방송에서 확인할 수 있는 스냅샷을 검증합니다.
- 시청자 스냅샷 보고: viewers_count와 likes_count를 collected_at과 함께 기록해, 하나의 방송에서 서로 다른 시각에 관찰한 값을 비교합니다.
- 라이브 방송 정보 보강: 기존 라이브 방송 레코드에 방송 주인의 ID, 사용자 이름, 표시 이름, 방송 제목, 상태, 커버 이미지를 추가합니다.
TikTok Live Room Info API 활용 팁
- room_id는 같은 활성 세션의 방송 주인 user_id와 한 쌍으로 유지하세요. 방과 사용자가 맞지 않으면 레코드가 반환되지 않거나 입력에 따른 원본 오류가 발생할 수 있습니다.
- TikTok의 큰 숫자 ID가 클라이언트나 데이터베이스에서 반올림되지 않도록 두 식별자를 모두 문자열로 보존하세요.
- 방송이 진행 중일 것으로 예상될 때 조회하고, 결과가 비어 있으면 오프라인 방송 레코드를 찾은 것이 아니라 종료, 사용 불가, 잘못된 입력 또는 불일치로 해석하세요.
- 상태와 수치의 관찰 시각으로는 collected_at을 사용하세요. 정규화된 레코드에서 created_at은 null이고 url은 비어 있습니다.
관련 API
TikTok Live Room Info API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
- TikTok Hashtags API — 지정한 해시태그의 공개 동영상, 크리에이터, 미디어, 사운드, 참여도를 수집합니다.
- TikTok Search API — 키워드로 공개 동영상을 검색하며, 지원되는 정렬 및 게시 기간 필터를 사용할 수 있습니다.
- TikTok User Videos API — 사용자 이름으로 공개 프로필 피드 동영상을 수집하며, 캡션, 크리에이터, 미디어, 타임스탬프, 참여도, 출처 계정 맥락을 포함합니다.
- TikTok Search Users API — 키워드로 공개 TikTok 계정을 검색합니다.
- TikTok Top Search API — 키워드로 동영상과 이미지 게시물을 검색하며, 캡션, 크리에이터, 상호작용 수를 포함합니다.
- TikTok Comments API
- TikTok Videos API
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok User Live API
- TikTok Audience Demographics API
- TikTok Similar Accounts API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Ranking API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API