tiktok/
user-videos

하나 이상의 사용자 이름에서 공개 TikTok 동영상을 수집하고, 캡션, 크리에이터, 미디어, 타임스탬프, 공개된 참여도를 계정과 연결된 정규화 레코드로 반환합니다.

TikTok User Videos API

알고 있는 계정의 피드
사용자 이름 일괄 처리
출처 계정 정보
결과당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

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

알고 있는 공개 사용자 이름을 비동기 작업으로 제출하고, 계정과 연결된 정규화 동영상을 결과 커서 페이지네이션으로 읽습니다.

  1. 공개 TikTok 사용자 이름을 하나 이상 준비하고, 최신순 또는 인기순 정렬, 선택 사항인 두 글자 지역, 사용자 이름별 results_limit을 정합니다.
  2. usernames와 선택 옵션을 /v1/tiktok/user-videos로 POST하고, 반환된 task_id를 저장합니다.
  3. status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. /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이 영구적이라고 가정하지 마세요.

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

TikTok User Videos API — 자주 묻는 질문

TikTok User Videos API는 하나 이상의 TikTok 사용자 이름에서 공개 프로필 피드의 동영상을 수집하는 프로그래밍 인터페이스입니다. 정규화된 동영상 식별 정보, 캡션, 크리에이터 및 미디어 정보, 타임스탬프, 공개된 참여도, 출처 사용자 이름을 반환합니다.

usernames를 비어 있지 않은 배열로 보냅니다. 앞의 @는 허용되지만, 제출하기 전에 핸들을 정규화하고 중복을 제거하면 같은 계정을 두 번 이상 처리하는 일을 피할 수 있습니다.

results_limit은 사용자 이름별 최댓값으로 20~2,000 사이이며 기본값은 100입니다. 프로필 피드는 각각 독립적으로 순회되며, 그 최댓값에 이르기 전에 끝날 수도 있습니다.

latest는 기본 프로필 피드 정렬이고, popular는 원본이 매긴 순위대로 결과를 요청합니다. popular는 SocQ가 계산한 점수가 아니므로, 작업 결과를 비교할 때는 선택한 정렬을 함께 보관하세요.

region은 선택 사항인 두 글자 코드를 받으며, 원본이 어떤 동영상을 제공하는지에 영향을 줄 수 있습니다. 동영상이 제작된 곳이나 시청자가 있는 곳을 확정해 주지는 않습니다.

레코드에는 동영상 식별 정보와 URL, 캡션과 언어, 크리에이터 정보, 공개된 참여도, 미디어와 재생 시간, 해시태그, 멘션, 음악, 타임스탬프, 공개 콘텐츠 플래그, extra.input_username이 포함될 수 있습니다.

공개 프로필 피드로 노출되는 동영상만 반환할 수 있습니다. 비공개, 제한, 삭제 또는 숨겨진 동영상은 빠질 수 있으며, 피드가 끝나거나 커서가 더 이상 진행되지 않거나 100페이지 상한에 도달해도 수집이 멈춥니다.

저장된 정규화 동영상 1건당 0.5 크레딧이 차감되며 작업 기본 요금은 없습니다. 처음 예상 금액은 results_limit 또는 기본값에 사용자 이름 수를 곱해 계산하고, 최종 사용량은 실제로 저장된 레코드를 따르며, 저장된 동영상이 없으면 결과 요금도 없습니다.