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로 진행 상황을 확인하고 결과를 가져옵니다.
- 프로필이나 라이브 방송 링크가 아니라 공개 사용자 이름을 하나 이상 준비합니다. 계정 프로필에서 @ 뒤의 핸들을 복사하면 됩니다.
- 예제를 실행하기 전에 $SOCQ_API_KEY를 자신의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래와 같이 Authorization 헤더와 함께 JSON 입력을 POST /v1/tiktok/user-live로 보내고, 응답의 task_id를 저장합니다.
- 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, failed이면 error_message에서 이유를 확인합니다.
- 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 성공적으로 확인된 계정 하나의 상태를 나타냅니다. 목록이 비어 있으면 작업은 완료되었지만 반환된 레코드가 없다는 뜻입니다.
- 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를 사용하세요.
관련 API
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 Hashtags API
- TikTok Comments API
- TikTok Search API
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok Top Search 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 Fake Views Checker API
- TikTok Comment Keywords API