---
title: 트렌딩 비디오
description: 브랜드, 제품, 크리에이터, 키워드 리서치를 위해 TikTok 트렌딩 비디오 메타데이터를 검색하거나 현재 트렌딩 피드를 둘러보는 방법을 살펴보세요.
---

트렌딩 비디오 검색은 순위가 매겨진 공개 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).

```text
POST /v1/trending-videos/search
```

## 검색과 둘러보기

프로덕션(플래그 OFF)에서는 `query`가 필수입니다. 선택: `platform`, `window`,
`limit`, `region`, `summary_mode`, `download`, `download_limit`. `query`는
api.dev이거나 `SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED`가 켜진 경우에만 생략할 수 있습니다.

<!-- api-call-example:trending-videos-search -->

### 필드

| 필드 | 설명 |
|---|---|
| `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` | 프로덕션: 1~50, 기본값 `10`. 재구축 플래그 ON: 1~100, 검색 기본값 `20`, 둘러보기 기본값 `48`. |
| `region` | 선택 사항인 두 글자 국가 코드입니다. 지역을 지정하지 않은 둘러보기는 US, GB, KR 트렌딩 피드를 합칩니다. |
| `summary_mode` | `none`(기본), `metadata`, `transcript`입니다. `transcript`는 현재 메타데이터와 함께 미지원 경고를 반환합니다. |
| `download` / `download_limit` | 향후 미러링 워크플로를 위해 예약된 필드입니다. MVP는 비디오를 내려받거나 미러링하지 않으며, 0보다 큰 값은 미지원 경고를 반환합니다. |

재구축 플래그가 켜진 경우에만 검색 결과는 질의어(캡션, 해시태그, 멘션,
작성자)와 맞아야 하고 최소 참여 기준을 넘어야 합니다. 주제와 어긋나거나
오래된 결과는 요청한 한도까지 채우지 않습니다. 프로덕션(플래그 OFF)은
기존 일반 순위 로직을 유지하며 추가 관련도·조회수 하한을 두지 않습니다.

## 응답 형태

응답에는 순위가 매겨진 비디오와 함께 공개 시청 URL, 선택적인 커버
썸네일, 작성자 handle, 지표, 관련도 점수, 그리고 선택적인 가벼운 요약이
담깁니다. 원본 TikTok 비디오 CDN URL은 포함되지 않습니다.

일반적인 비디오 항목 필드는 다음과 같습니다.

- `url` — 정식 공개 TikTok 시청 URL
- `cover_url` — 선택적인 표시용 썸네일(내려받을 수 있는 비디오가 아님)
- `description`, `created_at`, `region`
- `author.handle` / `author.nickname`
- `metrics`, `relevance`, `scores`
- `summary_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](https://api.sume.com/reference/json)에
있습니다.

## 가격 참고

접수된 호출마다 Sume 사용량 **0.10 USD**가 예약되고 확정됩니다.
`summary_mode: metadata`는 같은 호출 단가에 포함됩니다. 반복된 둘러보기는
캐시에서 나와 ScrapeCreators를 다시 치지 않을 수 있습니다. 실제 가격은
`GET /v1/catalog`에서 확인하세요.

## 워크플로에서의 위치

트렌딩 검색으로 리서치한 다음, 직접 준비한 공개 HTTPS 미디어 입력으로 Avatar 등
다른 생성기를 실행하세요. 오늘 이 엔드포인트가 페이스 스왑이나 캡션용으로
내려받을 수 있는 원본 파일을 반환할 것이라고 기대하지 마세요.

## 관련 문서

- [아바타 비디오 생성](/models/avatar-videos)
- [페이스 스왑 (Beta)](/models/face-swap)
- [비디오 캡션](/models/video-captions)
- [API 레시피](/api/cookbook)