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

트렌딩 비디오 검색은 질의어에 대해 순위가 매겨진 공개 TikTok 비디오
**메타데이터**를 반환합니다. 생성 모델이 아니라 유료 리서치 유틸리티입니다.

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

## 검색

필수: `query`. 선택: `platform`, `window`, `limit`, `region`, `summary_mode`,
`download`, `download_limit`.

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

### 필드

| 필드 | 설명 |
|---|---|
| `platform` | MVP는 `tiktok`만 지원합니다(기본값). |
| `query` | 브랜드, 제품, 크리에이터, 키워드입니다(1~200자). |
| `window` | `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`입니다. 알려진 SaaS 프로필은 `last-3-months`가, 그 외 질의는 `this-month`가 기본값입니다. |
| `limit` | 1~50이며 기본값은 `10`입니다. 알려진 프로필 필터에서는 더 적게 돌아올 수 있습니다. |
| `region` | 선택 사항인 두 글자 국가 코드입니다. |
| `summary_mode` | `none`(기본), `metadata`, `transcript`입니다. `transcript`는 현재 메타데이터와 함께 미지원 경고를 반환합니다. |
| `download` / `download_limit` | 향후 미러링 워크플로를 위해 예약된 필드입니다. MVP는 비디오를 내려받거나 미러링하지 않으며, 0보다 큰 값은 미지원 경고를 반환합니다. |

## 응답 형태

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

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

- `url` — 정식 공개 TikTok 시청 URL
- `description`, `created_at`, `region`
- `author.handle` / `author.nickname`
- `metrics`, `relevance`, `scores`
- `summary_mode`가 `none`이 아닐 때의 `summary`

정확한 스키마는 라이브 [OpenAPI](https://api.sume.com/reference/json)에
있습니다.

## 가격 참고

접수된 검색마다 Sume 사용량 **0.10 USD**가 예약되고 확정됩니다.
`summary_mode: metadata`는 같은 검색 단가에 포함됩니다. 실제 가격은
`GET /v1/catalog`에서 확인하세요.

## 워크플로에서의 위치

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

## 관련 문서

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