tiktok/
user-live

사용자 이름으로 공개 TikTok 계정이 라이브 중인지 확인하고, 한 번의 요청으로 여러 계정의 라이브 또는 오프라인 상태와 제공되는 방송 정보를 반환합니다.

TikTok User Live API

사용자 이름으로 계정 확인
라이브·오프라인 결과
요청 한 번에 여러 계정
결과당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

TikTok User Live

TikTok 계정의 라이브 상태는 특정 시점에 방송 중인지 여부를 나타내며, 진행 중인 방송에는 방송 제목, 커버, 시청자 수가 있을 수 있습니다. 크리에이터의 식별 정보와 확인 시각을 상태와 함께 보관하면 어느 계정이 방송 중이었는지, 정보가 얼마나 최근 것인지 알 수 있습니다.

TikTok User Live API 주요 기능

  • 조회한 계정이 라이브인지 오프라인인지 확인조회에 성공할 때마다 is_live가 라이브면 true, 오프라인이면 false로 반환되므로, 방송 중이 아닌 계정도 결과에서 사라지지 않고 상태 레코드가 남습니다.
  • 진행 중인 방송의 상세 정보 확인라이브 레코드에는 방송 제목, 크리에이터 이름, 커버 이미지, 시청자 수가 포함될 수 있어, 단순한 예·아니요 상태가 아니라 방송에 대한 정보를 얻을 수 있습니다.
  • 방송 식별자 대신 계정 핸들로 시작별도의 라이브 방송 상세 조회에 필요한 room_id와 user_id를 먼저 찾지 않고도, 공개 사용자 이름 여러 개를 한 번의 요청으로 조회할 수 있습니다.

TikTok User Live API 매개변수

매개변수필수설명
usernames필수공개 계정 핸들을 하나 이상 담은 목록으로, 필수 값입니다. @는 있어도 없어도 됩니다. 플레이그라운드에서는 한 줄에 사용자 이름 하나씩 입력하고, JSON에서는 프로필 URL이 아니라 ["thejustalex", "@tiktok"] 같은 배열을 사용하세요.

TikTok User Live API 사용 방법

이 요청은 백그라운드 수집 작업을 시작하므로 첫 응답에는 완성된 데이터가 아니라 작업 ID가 담겨 있습니다. 이 ID로 진행 상황을 확인하고 결과를 가져옵니다.

  1. 프로필이나 라이브 방송 링크가 아니라 공개 사용자 이름을 하나 이상 준비합니다. 계정 프로필에서 @ 뒤의 핸들을 복사하면 됩니다.
  2. 예제를 실행하기 전에 $SOCQ_API_KEY를 자신의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래와 같이 Authorization 헤더와 함께 JSON 입력을 POST /v1/tiktok/user-live로 보내고, 응답의 task_id를 저장합니다.
  3. 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, failed이면 error_message에서 이유를 확인합니다.
  4. 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 성공적으로 확인된 계정 하나의 상태를 나타냅니다. 목록이 비어 있으면 작업은 완료되었지만 반환된 레코드가 없다는 뜻입니다.
  5. data.results.has_more가 true이면 next_cursor 값은 저장된 결과의 다른 페이지를 가리키는 표식입니다. 이 값을 그대로 GET /v1/tasks/{task_id}?cursor=...의 cursor 매개변수에 복사해 넣고, has_more가 false가 될 때까지 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok/user-live" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["thejustalex"]}'

TikTok User Live API 추천 활용 사례

  • 계정별 라이브 상태 보드 준비: 크리에이터별 라이브 또는 오프라인 상태와 수집 시각을 담은 표를 만들어, 제출한 계정 중 가장 최근 관찰 시점에 방송 중이던 계정을 확인할 수 있게 합니다.
  • 진행 중인 방송 검토 목록 만들기: is_live=true인 레코드를 골라 방 링크, 제목, 시청자 수를 조합해 열어서 검토할 진행 중인 방송 목록을 만듭니다.

TikTok User Live API 활용 팁

  • 핸들 목록을 반복해서 제출하기 전에 앞의 @를 제거하고 대소문자를 구분하지 않고 중복을 제거해, tiktok과 @TikTok이 입력 개수 예상치를 부풀리지 않게 하세요.
  • 레코드가 is_live=false이면 계정 조회가 실패했다고 보고하지 말고 오프라인으로 표시하며, 없는 방송 필드는 비워 두세요.
  • 직접 새로 고치는 상태 보드에서는 상태 옆에 collected_at을 표시해, 이전 결과가 방금 관찰한 값으로 오해되지 않게 하세요.
  • 일치하는 room_id와 user_id를 이미 가지고 있어 별도의 방송 조회가 필요하다면, 해당 ID를 usernames 필드에 제출하지 말고 TikTok Live Room Info를 사용하세요.

TikTok User Live API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
  • TikTok Videos API — 동영상 URL에서 크리에이터, 캡션, 미디어, 음악, 태그, 멘션, 참여도를 가져옵니다.
  • TikTok User Videos API — 사용자 이름으로 공개 프로필 피드 동영상을 수집하며, 캡션, 크리에이터, 미디어, 타임스탬프, 참여도, 출처 계정 맥락을 포함합니다.
  • TikTok Live Room Info API — 방 ID와 소유자 ID 쌍으로 알고 있는 라이브 방송 하나를 조회하며, 상태, 소유자 맥락, 커버 미디어, 시청자 수를 반환합니다.
  • TikTok Trending Feed API — 지역별 현재 공개 동영상 피드를 수집하며, 크리에이터, 캡션, 커버, 타임스탬프, 공개된 참여도 필드를 포함합니다.
  • TikTok Live Shopping API — LIVE 방송 쇼핑백에 담긴 상품을 현재 가격, 판매 수량과 함께 나열합니다.

다른 플랫폼 둘러보기

TikTok 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok User Live API — 자주 묻는 질문

TikTok User Live API는 사용자 이름 목록으로 공개 TikTok 계정이 라이브 중인지 확인하는 프로그래밍 인터페이스입니다. 조회에 성공한 계정마다 라이브 또는 오프라인 상태를 반환하고, 진행 중인 방송에는 크리에이터 정보와 제공되는 방송 정보도 함께 반환합니다.

확인한 시점에 계정이 방송 중이 아니었다는 뜻이며 조회가 실패했다는 뜻이 아닙니다. 성공한 오프라인 레코드는 is_live=false, status=offline이며, 방송 제목, 시청자 수 등 방송 필드는 비어 있을 수 있습니다.

아니요. thejustalex 또는 @thejustalex처럼 계정의 사용자 이름을 입력하세요. room_id와 user_id는 별도의 TikTok Live Room Info 입력에 속합니다.

아니요. 작업은 실행될 때 상태를 확인하고 끝납니다. 새로 고친 상태 보드가 필요하다면 애플리케이션에서 직접 다시 확인을 실행하고 새 수집 시각을 보관해야 합니다.

아니요. 0은 숫자 값이고, null은 측정값이 없다는 뜻입니다. 두 경우를 구분해서 다루세요. 오프라인 레코드에서는 방송 측정값이 비어 있을 것으로 예상하면 됩니다.

성공한 오프라인 결과를 포함해 반환된 상태 1건당 0.5 크레딧이 차감되며 기본 요금은 없습니다. 예를 들어 서로 다른 사용자 이름 3개의 예상 금액은 1.5 크레딧이고, 계정 2개가 오프라인이어도 상태 3건이 반환되면 1.5 크레딧이 차감됩니다.