트렌딩 비디오
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
트렌딩 비디오 검색은 순위가 매겨진 공개 TikTok 비디오 메타데이터를 반환합니다. 생성 모델이 아니라 유료 리서치 유틸리티입니다.
재구축된 둘러보기 피드(질의 없는 기본 그리드, 더 높은 한도, 품질 필터)는
DEV에서 켜집니다 (api.dev / Railway development, Assets 페이지는
www.dev). 프로덕션은 SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED 또는
NEXT_PUBLIC_SUME_COM_TRENDING_VIDEOS_UI_ENABLED가 정확히 1 또는 true일
때까지 OFF입니다. 프로덕션은 기존 계약을 유지합니다. query 필수, 한도
1~50(기본 10).
검색과 둘러보기
프로덕션(플래그 OFF)에서는 query가 필수입니다. 선택: platform, window,
limit, region, summary_mode, download, download_limit. query는
api.dev이거나 SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED가 켜진 경우에만 생략할 수 있습니다.
Search trending TikTok videos
POST /v1/trending-videos/search
Required
필드
| 필드 | 설명 |
|---|---|
platform | MVP는 tiktok만 지원합니다(기본값). |
query | 프로덕션에서는 필수입니다. 브랜드, 제품, 크리에이터, 키워드입니다(최대 200자). api.dev이거나 SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED가 켜진 경우에만 생략할 수 있습니다. |
window | yesterday, this-week, this-month, last-3-months, last-6-months, all-time입니다. 프로덕션 일반 질의는 this-month가, 알려진 SaaS 프로필은 last-3-months가 기본값입니다. |
limit | 프로덕션: 110. 재구축 플래그 ON: 120, 둘러보기 기본값 48. |
region | 선택 사항인 두 글자 국가 코드입니다. 지역을 지정하지 않은 둘러보기는 US, GB, KR 트렌딩 피드를 합칩니다. |
summary_mode | none(기본), metadata, transcript입니다. transcript는 현재 메타데이터와 함께 미지원 경고를 반환합니다. |
download / download_limit | 향후 미러링 워크플로를 위해 예약된 필드입니다. MVP는 비디오를 내려받거나 미러링하지 않으며, 0보다 큰 값은 미지원 경고를 반환합니다. |
재구축 플래그가 켜진 경우에만 검색 결과는 질의어(캡션, 해시태그, 멘션, 작성자)와 맞아야 하고 최소 참여 기준을 넘어야 합니다. 주제와 어긋나거나 오래된 결과는 요청한 한도까지 채우지 않습니다. 프로덕션(플래그 OFF)은 기존 일반 순위 로직을 유지하며 추가 관련도·조회수 하한을 두지 않습니다.
응답 형태
응답에는 순위가 매겨진 비디오와 함께 공개 시청 URL, 선택적인 커버 썸네일, 작성자 handle, 지표, 관련도 점수, 그리고 선택적인 가벼운 요약이 담깁니다. 원본 TikTok 비디오 CDN URL은 포함되지 않습니다.
일반적인 비디오 항목 필드는 다음과 같습니다.
url— 정식 공개 TikTok 시청 URLcover_url— 선택적인 표시용 썸네일(내려받을 수 있는 비디오가 아님)description,created_at,regionauthor.handle/author.nicknamemetrics,relevance,scoressummary_mode가none이 아닐 때의summary
재구축 플래그가 켜진 경우에만 params.mode는 query가 없으면 browse,
있으면 search입니다. params.cached는 인프로세스 피드 캐시가 응답을
냈을 때 true입니다. 프로덕션(플래그 OFF)에서는 이 필드가 없습니다.
Assets → 트렌딩 페이지(/trending-videos)는 www.dev에서 켜지고
(NEXT_PUBLIC_APP_URL이 DEV 호스트일 때), 프로덕션 www는
NEXT_PUBLIC_SUME_COM_TRENDING_VIDEOS_UI_ENABLED가 정확히 1 또는
true일 때까지 꺼져 있습니다.
정확한 스키마는 라이브 OpenAPI에 있습니다.
가격 참고
접수된 호출마다 Sume 사용량 0.10 USD가 예약되고 확정됩니다.
summary_mode: metadata는 같은 호출 단가에 포함됩니다. 반복된 둘러보기는
캐시에서 나와 ScrapeCreators를 다시 치지 않을 수 있습니다. 실제 가격은
GET /v1/catalog에서 확인하세요.
워크플로에서의 위치
트렌딩 검색으로 리서치한 다음, 직접 준비한 공개 HTTPS 미디어 입력으로 Avatar 등 다른 생성기를 실행하세요. 오늘 이 엔드포인트가 페이스 스왑이나 캡션용으로 내려받을 수 있는 원본 파일을 반환할 것이라고 기대하지 마세요.