TikTok User Videos
TikTok 사용자 동영상은 캡션, 크리에이터 식별 정보, 미디어·사운드 맥락, 게시 정보, 공개된 참여도를 담은 공개 프로필 피드의 게시물입니다. 이처럼 계정과 연결된 콘텐츠 레코드는 크리에이터별 콘텐츠 목록 관리, 게시 현황 비교, 크리에이티브 조사, 성과 스냅샷에 활용할 수 있습니다.
TikTok User Videos API 주요 기능
- 알고 있는 계정의 프로필 피드TikTok 사용자 이름을 하나 이상 받아 공개 동영상 피드를 각각 독립적으로 순회하며, 키워드나 해시태그 탐색이 아니라 선택한 계정으로 결과 범위를 한정합니다.
- 동영상 및 크리에이터 상세 정보동영상 ID와 URL, 캡션, 언어, 크리에이터 식별 정보, 미디어 참조, 재생 시간, 해시태그, 멘션, 음악, 공개 콘텐츠 플래그를 반환합니다.
- 시각이 기록된 참여도 신호공개된 조회수, 좋아요 수, 댓글 수, 공유 수, 저장 수, 리포스트 수를 게시 시각 및 수집 시각과 함께 담아, 특정 시점의 계정 동영상 레코드를 만듭니다.
- 계정별 순회 제어사용자 이름마다 최신순 또는 인기순 정렬과 선택 사항인 지역을 적용하고, 동영상 ID 중복을 제거하며 요청한 계정별 한도를 지킵니다.
TikTok User Videos API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
usernames | 필수 | 공개 TikTok 사용자 이름을 하나 이상 담은 목록으로, 필수 값입니다. 각 값의 앞에 붙는 @는 있어도 없어도 됩니다. |
results_limit | 선택 | 사용자 이름마다 요청할 동영상의 최대 개수입니다. 기본값은 100이며 20~2,000 사이의 정수를 허용합니다. |
sort_by | 선택 | 프로필 피드 정렬 기준이며 선택 사항입니다. 기본값은 latest이고, popular를 지정하면 원본이 매긴 순위대로 반환됩니다. |
region | 선택 | 원본의 제공 범위에 영향을 주기 위해 대문자로 전달하는 두 글자 지역 코드이며 선택 사항입니다. |
TikTok User Videos API 사용 방법
알고 있는 공개 사용자 이름을 비동기 작업으로 제출하고, 계정과 연결된 정규화 동영상을 결과 커서 페이지네이션으로 읽습니다.
- 공개 TikTok 사용자 이름을 하나 이상 준비하고, 최신순 또는 인기순 정렬, 선택 사항인 두 글자 지역, 사용자 이름별 results_limit을 정합니다.
- usernames와 선택 옵션을 /v1/tiktok/user-videos로 POST하고, 반환된 task_id를 저장합니다.
- status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- /v1/tasks/{task_id}?limit=50에서 data.results.items를 읽고, results.has_more가 true인 동안 results.next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["@loganpaul"],"results_limit":20,"sort_by":"latest"}'
# Poll GET /v1/tasks/{task_id}, then read data.results.items and follow results.next_cursor.TikTok User Videos API 추천 활용 사례
- 크리에이터 동영상 목록 관리: 선택한 계정을 동영상 ID, 정식 URL, 캡션, 미디어, 게시 시각, extra.input_username으로 색인해 추적 가능한 공개 콘텐츠 카탈로그를 유지합니다.
- 게시 현황 및 참여도 비교: 알고 있는 계정들의 created_at과 공개된 조회수, 좋아요 수, 댓글 수, 공유 수, 저장 수, 리포스트 수를 비교하되, collected_at을 스냅샷 시각으로 보관합니다.
- 크리에이티브 형식 조사: 캡션, 언어, 재생 시간, 해시태그, 멘션, 음악, 미디어 유형, 공개 콘텐츠 플래그로 선택한 프로필 피드에서 반복되는 크리에이티브 패턴을 비교합니다.
TikTok User Videos API 활용 팁
- creator와 @creator는 같은 계정을 가리키지만 따로 처리될 수 있으므로, 제출하기 전에 모든 핸들을 한 가지 형태로 정규화하고 중복을 제거하세요.
- 한도와 초기 크레딧 예상치는 제출한 계정마다 독립적으로 적용되므로, 사용자 이름 수를 고려해 results_limit을 정하세요.
- 최신 게시물 위주로 수집하려면 latest를 사용하고, popular는 SocQ가 계산한 점수가 아니라 원본의 정렬로 취급하세요.
- region은 제공 범위를 조절하는 용도로만 사용하고, 반환된 동영상이 해당 지역에서 제작되었다는 증거로 해석하지 마세요.
- 반복 실행한 작업을 합칠 때는 동영상 id로 중복을 제거하되, 계정 귀속과 스냅샷 시점을 위해 extra.input_username과 collected_at을 보관하세요.
- 선택 사항인 크리에이터, 참여도, 미디어, 음악, 콘텐츠 플래그 필드는 null일 수 있다고 보고 처리하고, 공개 캡션은 표시하기 전에 이스케이프 처리하며, 원본 미디어 URL이 영구적이라고 가정하지 마세요.
관련 API
TikTok User Videos API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
- TikTok Comments API — 공개된 최상위 댓글, 작성자, 참여도, 멘션, 크리에이터 상호작용 플래그를 수집합니다.
- TikTok Videos API — 동영상 URL에서 크리에이터, 캡션, 미디어, 음악, 태그, 멘션, 참여도를 가져옵니다.
- TikTok Trending Feed API — 지역별 현재 공개 동영상 피드를 수집하며, 크리에이터, 캡션, 커버, 타임스탬프, 공개된 참여도 필드를 포함합니다.
- TikTok Video Transcript API — 공개 동영상 URL에서 제공되는 스크립트 텍스트, 언어, 형식, 출처 맥락을 추출합니다.
- TikTok Song API — 클립 ID 또는 음악 URL로 공개 사운드 메타데이터를 가져옵니다.
- TikTok Hashtags API
- TikTok Search API
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok Live Room Info API
- TikTok Search Users API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok Top Search 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