---
title: 비디오 분석
description: 기존 공개 비디오 URL을 타이밍, 비주얼, 키프레임이 담긴 타입 있는 장면으로 나눠 분석하는 방법을 살펴보세요.
---

비디오 분석은 공개 HTTPS 비디오 URL을 받아 Job 기반의 장면별 분해 결과를
반환합니다. 에이전트가 기존 클립을 *읽어야* 할 때(구조, 훅, B롤 삽입 지점)
사용하세요. 트렌드 발굴이나 바이럴 예측 도구가 아니며, 비디오를 **생성하지도
않습니다** — 구조를 따라 만든 리믹스가 필요하면 생성 Format과 함께 사용하세요.

내부적으로는 비디오 이해 모델(TwelveLabs Pegasus)이 MP4를 보고 설명과 대사가
담긴 타입 있는 장면으로 나눈 뒤, ffmpeg가 장면마다 JPEG 스틸 한 장을
추출합니다(`keyframe_url`). 현재 `analysis_version`은 `1.1`입니다.

```text
POST /v1/video-analyses
GET  /v1/video-analyses/:id
GET  /v1/video-analyses
```

원격 MCP 래퍼는 `video-analyses_create`, `video-analyses_get`,
`video-analyses_list`입니다. `jobs_wait`로 폴링하세요(일반적인 실행 시간은
**3~5분**이며 **30~60초**마다 폴링합니다).

**정확도 주의:** 긴 비디오일수록 정확도가 떨어집니다. 짧은 클립이 가장 믿을
만한 결과를 줍니다.

## 분석 Job 만들기

필수: `video_url`. 선택: `max_scenes`(2~40, 기본 24),
`include_transcript`(`true`이면 각 장면의 `audio`에 해당 장면의 대사
`speech`가 담기고, 아니면 `audio`는 `null`입니다), 그리고 평소의 `mode` /
`webhook_url` / `wait_timeout_seconds` 통신 필드입니다.

```bash
curl -X POST https://api.sume.com/v1/video-analyses \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-analysis-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/ad.mp4",
    "max_scenes": 24
  }'
```

제출에 성공하면 `202`와 함께 `vana_…` 리소스 id, `video_analysis`
Job(`request_id`), 그리고 `status_url` / `result_url`이 돌아옵니다.

미디어 임포트(`POST /v1/media-imports`)로 만든 내구성 있는 `media.sume.com`
URL이나 완료된 Sume 생성 산출물을 사용하세요. Higgsfield 방식의 `media_id`
반입 게이트는 없습니다.

## 가격 참고

접수된 분석마다 현재 고정 추정 기준으로 Sume 사용량 **0.30 USD**가 예약되고
확정됩니다. 실제 가격은 `GET /v1/catalog`와 OpenAPI에서 확인하세요.

## 길이 제한

| 상한 | 동작 |
|---|---|
| 소프트(약 90초) | Job은 성공합니다. 응답에 `low_confidence_long_video` 경고가 포함될 수 있습니다. |
| 하드(300초) | 프로브 이후 안정적인 길이 오류로 거부됩니다. |

## 지원하지 않는 입력

| 입력 | 결과 |
|---|---|
| YouTube URL | `422 unsupported_source` |
| HTTPS가 아니거나 사설·localhost | 접수 단계에서 거부됩니다 |
| 비디오가 아닌 에셋 | 에이전트가 읽을 수 있는 안정적인 코드로 실패합니다 |

## 폴링하고 읽기

```bash
curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/video-analyses/vana_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

curl "https://api.sume.com/v1/video-analyses?limit=20" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

준비되면 리소스에는 비디오 전체 메타데이터와 타입이 정해진 `scenes[]` 배열이
담깁니다. 각 장면에는 연속된 `start_seconds` / `end_seconds`,
`duration_seconds`, `summary`, `visual`, 선택적인 `shot_type` /
`camera_motion`, `on_screen_text`, `audio`(`include_transcript`를 요청했으면
`{ speech, has_speech, has_music }`, 아니면 `null`), `keyframe_url`(장면별
JPEG 스틸, 미러링에 실패하면 `keyframe_mirror_failed:scene_N` 경고와 함께
`null`), `confidence`(0~1)가 들어 있습니다.

## 스코프

| 스코프 | 오퍼레이션 |
|---|---|
| `video_analyses:write` | `POST /v1/video-analyses` |
| `video_analyses:read` | `GET /v1/video-analyses`, `GET /v1/video-analyses/:id` |

## 관련 문서

- [비디오 캡션](/models/video-captions)
- [트렌딩 비디오](/models/trending-videos) (발굴 메타데이터일 뿐 분석이 아닙니다)
- [Job과 결과](/workflows/jobs-and-results)
- [미디어 입력](/workflows/asset-library)