---
title: 비디오 분석
description: 레거시 장면 분석 리소스입니다. dest 생성은 폐지(410)이고, 프로덕션은
---

> **현재 SoT.** 이 표면으로 새 작업을 시작하지 마세요.
>
> - **dest와 prod 기본:** [비디오 검사](/models/video-inspect) —
>   `POST /v1/video-inspect`(MCP `video_inspect`)로 프로브 + 스틸 + 선택적
>   전사. 프로브와 스틸은 무료입니다. 기본 `mode: sync`.
> - **Dest (`api.dev.sume.com`):** `SUME_COM_VIDEO_ANALYSIS_ENABLED=false`.
>   `POST /v1/video-analyses`는 `410 video_analysis_retired`. MCP
>   `video-analyses_*`는 `tools_list`에서 빠집니다. 저장된 `vana_` 행은 GET으로
>   읽습니다. dest에서 의미 질문/구간은 `tools_list`에 보일 때만
>   `video_analyze` / `video_segment`(신뢰 origin `api.dev.sume.com` +
>   TwelveLabs 키 — 프로덕션 불가).
> - **Prod (`api.sume.com`):** #5953 PR-C2까지 생성을 받습니다. dest의 `410`은
>   프로덕션 장애가 아닙니다.

이 페이지는 레거시 `video_analysis` / `vana_` 리소스(타입 있는 `scenes[]`)를
설명합니다. 트렌드 발굴이나 바이럴 예측이 아니며, 비디오를 **생성하지도
않습니다**. 클립 구조로 Format을 만드는 일은 리믹스 작업입니다.

생성이 켜진 환경에서는 비디오 이해 모델(TwelveLabs Pegasus)이 MP4를 장면으로
나누고, ffmpeg가 장면의 매 초마다 JPEG 스틸을 추출합니다(`keyframes`). 장면
대표 스틸은 `keyframe_url`입니다. 현재 `analysis_version`은 `1.1`입니다.

```text
POST /v1/video-analyses          # dest: 410; prod는 PR-C2까지
GET  /v1/video-analyses/:id      # 저장된 행, 양쪽 환경
GET  /v1/video-analyses          # 저장된 행, 양쪽 환경
```

원격 MCP 래퍼 `video-analyses_create` / `_get` / `_list`도 같은 플래그를
따릅니다. 프로덕션은 PR-C2까지 목록에 있고 dest에서는 빠집니다. 남은 Job은
`jobs_wait`로 폴링하세요(일반적인 실행 시간은 **3~5분**, **30~60초**마다).

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

## 분석 Job 만들기 (프로덕션, PR-C2까지)

dest 호출자는 POST하지 마세요. [비디오 검사](/models/video-inspect)를
쓰고, 목록에 있을 때만 dest 전용 `video_analyze` / `video_segment`를
쓰세요.

필수: `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 스틸 — 장면 길이의 40%에 가장 가까운 1초 샘플, 1초 미만
장면은 기존 40% 지점. 미러링에 실패하면 `keyframe_mirror_failed:scene_N`
경고와 함께 `null`), `keyframes`(그 장면의 매 정수 초를 덮는 `{ t, url }`
배열. 한 초가 실패해도 장면 전체가 빠지지 않으며 해당 행은 `url: null`과
`keyframe_mirror_failed:scene_N:t_T` 경고), `confidence`(0~1)가 들어
있습니다. 300초 하드 길이 제한이 스틸 수 상한(~300장)이기도 합니다.
별도의 1초 텍스트/컨텍스트 트랙은 없습니다.

## 스코프

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

## 관련 문서

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