tiktok/
live-room-info

방 ID와 방송 주인 ID를 한 쌍으로 지정해 공개 TikTok 라이브 방송 하나를 조회하고, 제목, 상태, 방송 주인 정보, 커버 이미지, 시청자 수, 좋아요 수, 수집 시각을 반환합니다.

TikTok Live Room Info API

알고 있는 라이브 방송
시청자 스냅샷
방송 주인 정보
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

진행 중인 방송 하나의 식별자를 한 쌍으로 준비해 비동기 조회를 제출한 뒤, 작업 결과에서 정규화된 스냅샷을 읽습니다.

  1. 현재 TikTok 라이브 세션을 확인할 수 있는 출처에서 room_id를 얻고, 같은 맥락이나 TikTok Profiles 결과에서 그에 맞는 방송 주인의 user_id를 얻습니다.
  2. 비어 있지 않은 문자열인 두 식별자를 /v1/tiktok/live-room-info로 POST합니다.
  3. status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. /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은 비어 있습니다.

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 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok Live Room Info API — 자주 묻는 질문

TikTok Live Room Info API는 room_id와 방송 주인의 user_id로 알고 있는 공개 라이브 방송 하나를 조회하는 프로그래밍 인터페이스입니다. 방송 제목과 상태, 방송 주인 정보, 커버 이미지, 시청자 수와 좋아요 수, 수집 시각을 특정 시점의 스냅샷으로 반환합니다.

room_id를 확인할 수 있는 라이브 세션 출처를 사용하고, 방송 주인의 숫자 user_id와 한 쌍으로 유지하세요. TikTok Profiles 결과의 정규화된 id 필드에서 user_id를 얻을 수 있지만, 현재 SocQ TikTok 카탈로그에서는 room_id를 찾을 수 없습니다.

방송이 종료되었거나, 사용할 수 없게 되었거나, 제출한 방송 주인과 더 이상 일치하지 않거나, 둘 중 하나의 식별자가 잘못되었을 수 있습니다. SocQ는 원본에서 비어 있지 않은 room_id가 확인될 때만 결과를 저장합니다.

아니요. 이미 알고 있는 방송을 한 번 조회할 뿐이며, 인기 방송 검색, 계정이 라이브를 시작할 때까지 대기, 영상 녹화, 라이브 이벤트 수집, 지속적인 모니터 생성은 하지 않습니다.

요청을 수집한 시점에 공개된 특정 시점의 값이며 곧바로 달라질 수 있습니다. 연속된 피드로 취급하지 말고 collected_at을 수치와 함께 저장하세요.

저장된 정규화 방송 레코드 1건당 0.5 크레딧이 차감되며 작업 기본 요금은 없습니다. 예상 금액은 결과 1건을 기준으로 하며, 결과가 없으면 결과 요금이 부과되지 않습니다.