TikTok 트렌딩 영상 검색 API: 리서치용 순위 메타데이터

Sume의 트렌딩 영상 검색 POST /v1/trending-videos/search는 브랜드, 제품, 크리에이터, 키워드 질의에 대해 공개 TikTok 영상의 메타데이터를 순위대로 반환합니다. 시청 URL, 작성자 handle, 지표, 관련도 점수가 담깁니다. 생성 모델이 아니라 유료 리서치 유틸리티이며, 영상을 내려받거나 미러링하지 않습니다.

아래 내용은 모두 트렌딩 영상 문서에서 가져왔으며, 프로덕션 API 기준입니다.

TikTok 트렌딩 영상은 어떻게 검색하나요?

query를 보내세요. 프로덕션에서는 필수입니다. 나머지 필드는 모두 선택입니다. 아래 요청은 키워드로 이번 주 TikTok 영상을 최대 10개까지 요청하며, 영상마다 가벼운 요약을 붙입니다.

curl -X POST "https://api.sume.com/v1/trending-videos/search" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cold brew",
    "platform": "tiktok",
    "window": "this-week",
    "limit": 10,
    "summary_mode": "metadata"
  }'

어떤 필드를 보낼 수 있나요?

각 결과에는 무엇이 담기나요?

응답에는 순위가 매겨진 영상 목록이 공개 시청 URL, 선택적 커버 썸네일, 작성자 handle, 지표, 관련도 점수, 선택적인 가벼운 요약과 함께 담깁니다. 원본 TikTok 영상 CDN URL은 반환하지 않습니다. 프로덕션에서는 추가 관련도나 조회수 하한이 없는 일반 랭커로 순위를 매깁니다. 정확한 스키마는 라이브 OpenAPI 문서에 있습니다.

일반적인 영상 항목에는 다음이 담깁니다.

• url: 정식 공개 TikTok 시청 URL.
• cover_url: 선택적인 표시용 썸네일이며, 내려받을 수 있는 영상이 아닙니다.
• description, created_at, region 필드.
• author.handle과 author.nickname.
• metrics, relevance, scores 필드.
• summary_mode가 none이 아닐 때의 summary.

트렌딩 검색이 하지 않는 일은 무엇인가요?

이 기능을 바탕으로 개발하기 전에 다음 한계를 알아 두세요.

• 미디어를 생성하지 않습니다. 리서치 유틸리티입니다.
• 영상을 내려받거나 미러링하지 않으며, 현재 페이스 스왑(Beta)이나 자막에 쓸 수 있는, 내려받을 수 있는 원본 파일도 반환하지 않습니다.
• 파일이 아니라 링크를 반환합니다. url은 공개 시청 URL이고 cover_url은 표시용 썸네일입니다.
• 아직 전사 텍스트를 반환하지 않습니다. summary_mode: "transcript"는 메타데이터와 함께 미지원 경고를 반환합니다.
• TikTok만 검색합니다.

영상 워크플로에서는 어떻게 쓰나요?

문서는 두 단계 패턴을 설명합니다. 트렌딩 검색으로 리서치한 다음, 직접 준비한 공개 HTTPS 미디어 입력으로 Avatar나 다른 생성기를 써서 생성합니다. 예를 들어 제품 키워드로 무엇이 트렌딩인지 확인한 뒤 말하는 아바타 영상의 스크립트를 쓰거나, 직접 보유한 영상에 자막을 입힐 수 있습니다.

검색 비용은 얼마인가요?

접수된 호출마다 호출당 고정 금액의 Sume 사용량이 예약되고 확정되며, summary_mode: "metadata"도 같은 호출 단가에 포함됩니다. 문서는 현재 가격을 GET /v1/catalog에서 확인하라고 안내합니다. API 요금과 Sume 요금제는 어떻게 동작하나요도 참고하세요.