---
title: 비디오 검사
description: Sume 호스트 클립 하나를 프로브하고 스틸을 뽑고, 선택적으로 전사합니다. dest와 prod의 기본 클립 검사입니다.
---

> **현재 SoT.** 새 클립 검사는 이 표면입니다.
> [비디오 분석](/models/video-analyses)이 아닙니다.
>
> - **dest와 prod:** `POST /v1/video-inspect`(MCP `video_inspect`).
>   프로브와 스틸은 무료입니다. 기본 `mode: sync`.
> - **타입 있는 장면이 아닙니다.** 검사는 프로브 사실, 스틸, 선택적 STT를
>   반환합니다. dest에서 의미 질문/구간은 `tools_list`에 보일 때만
>   `video_analyze` / `video_segment`입니다.
> - **레거시 `POST /v1/video-analyses`:** dest는 `410
>   video_analysis_retired`, prod는 #5953 PR-C2까지 유지됩니다.

Video inspect 1.0은 워크스페이스가 이미 소유한 **하나의** `media.sume.com`
클립을 읽습니다. 소스를 다시 인코딩하지 않고 MP4를 만들지 않습니다. Job id가
리소스 id입니다(`sume/video-inspect-1.0`, 타입 `video_inspect`).

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

호스티드 MCP: `video_inspect`(`packages/mcp-server/src/mcp.ts`). 쓰기는
`idempotency_key`가 필요합니다(OAuth에서는 `mcp:write`). GET MCP 래퍼는
없습니다. submit이 `202`이면 `jobs_wait` 다음 `jobs_result`로 폴링하세요.

## 검사 만들기

필수: `video_url`(이 워크스페이스의 `media.sume.com` 아티팩트 또는 에셋).
공개 인터넷 fetch는 없습니다. 먼저 가져오세요(`POST /v1/media-imports`).
`Idempotency-Key`는 필수입니다.

선택: `frames`, `transcribe`, 그리고 `transcribe: true`일 때만
`language_code`, `segmentation`, `duration_seconds`, 평소의 `mode` /
`webhook_url` / `wait_timeout_seconds` 통신 필드입니다.

기본 `mode`는 **`sync`**입니다. 핸들러는 최대 **30초** 기다리고 끝난 검사를
`200`으로 주거나, 큐에 남은 Job을 `202`로 줍니다.

```bash
curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-inspect-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4"
  }'
```

성공하면 `request_id` = `video_inspect_id`(Job id)와 `video_inspect` 객체를
받습니다. 나중에 읽을 때:

```bash
curl https://api.sume.com/v1/video-inspect/$REQUEST_ID \
  -H "Authorization: Bearer $SUME_API_KEY"
```

준비가 되면 리소스에 `probe`, 내구 `media.sume.com` 이미지 아티팩트인
`frames[{t,url,width,height}]`, 요청했을 때의 `transcript`(`text`,
`words[]`, 선택적 문장 `segments[]`, `audio_url`), `warnings[]`가 담깁니다.

## 프레임 프로그램

| `frames` | 효과 |
|---|---|
| 생략 | **8**장의 mid-bin 스틸(클립이 8초보다 짧으면 1 fps) |
| `false` | 프로브만 — 스틸 없음 |
| `{ at: [초…] }` | 명시 타임스탬프, 1–24개, 각 ≥ 0 |
| `{ fps: n }` | 샘플링 레이트, `0 < n ≤ 2`, mid-bin, 최대 24장 |

객체는 `at[]`와 `fps` 중 **정확히 하나**를 넣어야 합니다. 그 객체에서
선택: `format`은 `jpeg`(기본) 또는 `png`; `max_edge`는 64–2160(기본
**768**). 첫 프레임을 소스 해상도로 다시 뽑을 때는 소스 변을 넣으세요.

그 객체의 `seek`는 각 스틸을 찾는 방식입니다:

| `seek` | 효과 |
|---|---|
| `precise`(기본) | 정확한 순간까지 디코드합니다. 기존 프로그램은 그대로입니다. |
| `fast` | 각 스틸을 그 순간 **이전 또는 같은** 키프레임에 맞추고 디코드를 건너뜁니다 — 최대 한 GOP(보통 0–5초)만큼 앞당겨질 수 있고, 뒤로 가진 않습니다. 화질·해상도·전사는 동일합니다. |

클립을 **훑어볼 때**는 `fast`, 타임스탬프가 맞아야 할 때(명시 `at[]`,
기본 8장 중간점)는 `precise`를 유지하세요. `fast`에서는 각 그리드에
`seek: "fast"`, 실제로 보이는 순간의 `sample_times`, 요청한 순간의
`requested_times`가 담깁니다.

상한(`packages/api-contract/src/index.ts`): 소스 ≤ **1800**초, 호출당
스틸 **24**장.

한 `t`의 소스 크기 프레임은 이 경로가 아니라
[비디오 프레임](/models/video-frames)입니다.

## 전사 (선택, 과금)

`transcribe: true`는 클립 오디오에 Sume STT 1.0을 돌립니다. 프로브와 스틸은
무료이고, 이 절반만 예약합니다.

- 공개 요금: **오디오 분당 $0.0088**(`STT_PUBLIC_PRICING`. 라이브는
  `GET /v1/catalog`에서 확인).
- `duration_seconds`를 생략하면 **1분**을 예약합니다. 힌트 최대 **600**초.
- `language_code`(예: `en`, `ko`)는 STT 힌트입니다. 생략하면 자동 감지.
- `segmentation.mode: "sentence"`는 갭 없는 문장 `segments[]`도 줍니다
  (캡션 라인 형태). 선택 `silence_split_seconds` 0.2–3.
- `transcribe: true` 없이 `language_code` / `segmentation` /
  `duration_seconds` → `400 video_inspect_transcribe_required`.
- 무음 클립 → `inspect_source_has_no_audio`. 먼저 `probe.has_audio`를
  보세요(`frames: false` 검사면 충분합니다).

## 거절 (안정 코드)

| 코드 | 언제 |
|---|---|
| `ffmpeg_fields_rejected` | 클라이언트가 `vf` / `filter` / `ffmpeg` / `cmd` / `codec` / `crf` 등을 보냄. 서버가 ffmpeg를 컴파일합니다. |
| `video_inspect_frames_program_conflict` | `frames.at[]`와 `frames.fps`를 함께 보냄. |
| `video_inspect_frames_program_required` | `frames` 객체에 `at[]`도 `fps`도 없음. |
| `video_inspect_transcribe_required` | `transcribe: true` 없이 STT 전용 필드. |
| `source_not_found` | 죽은 또는 다른 워크스페이스의 `media.sume.com` URL. |
| `frame_time_out_of_range` | `at` 값이 `[0, duration)` 밖. 오류가 duration을 알려 줍니다. |
| `inspect_source_has_no_audio` | 오디오 트랙이 없는 클립에 `transcribe: true`. |

호스트 밖 URL(`https://example.com/…`)은 접수에서 거절됩니다. 먼저
가져오세요.

## 이 표면이 아닌 것

| 필요한 일 | 쓸 것 |
|---|---|
| 타입 있는 `scenes[]` / TwelveLabs Pegasus | 레거시 [비디오 분석](/models/video-analyses) (prod는 PR-C2까지, dest는 `410`) |
| dest 의미 Q&A / 구간 | `mcp.dev.sume.com` 목록에 있을 때 `video_analyze` / `video_segment` |
| `t`의 소스 크기 프레임 | [비디오 프레임](/models/video-frames) |
| 공개 URL에 캡션 입히기 | [비디오 캡션](/models/video-captions) |
| 새 MP4 컷 | [비디오 트림](/models/video-trim) |
| 오디오 트랙을 wav / mp3로 | [오디오 분리](/models/audio-detach) |
| 픽셀 패스(dim / crop) | [비디오 필터](/models/video-filter) |
| 여러 클립 시퀀스 | [Timeline 1.0](/models/timeline) |

## 관련 문서

- [비디오 분석](/models/video-analyses) (레거시 `vana_` 리소스)
- [비디오 프레임](/models/video-frames)
- [비디오 트림](/models/video-trim)
- [오디오 분리](/models/audio-detach)
- [비디오 필터](/models/video-filter)
- [Timeline 1.0](/models/timeline)
- [비디오 캡션](/models/video-captions)
- [미디어 입력](/workflows/asset-library)
- [Job과 결과](/workflows/jobs-and-results)
- [MCP 도구와 게이트](/mcp/tools-and-gates)