---
title: 비디오 트림
description: Sume 호스트 클립 하나에서 [start, end) 구간을 잘라 새 MP4를 만듭니다. 타임라인 배치가 아니라 소재 준비입니다.
---

> **현재 SoT.** Media L2 구간 컷(`sume/video-trim-1.0`, #5953). dest와
> prod. **클립 검사가 아닙니다** — 검사는
> [비디오 검사](/models/video-inspect)입니다. **조립이 아닙니다** —
> 시퀀스, 트랜지션, 오디오 스파인은
> [Timeline 1.0](/models/timeline)에 남습니다.

Video trim 1.0은 워크스페이스의 **하나의** `media.sume.com` 클립과
구간을 받아 `[start, end)`만 담은 **새** MP4 아티팩트를 반환합니다.
소스는 건드리지 않습니다. 서버가 워커 미디어 런타임에서 ffmpeg를
컴파일합니다(`apps/api/src/routes.ts` `createVideoTrimV1` /
`submitSumeVideoTrimJob`).

```text
POST /v1/video-trim
POST /v1/models/sume/video-trim-1.0/runs   # 같은 본문, 추가 `model` 필드 없음
```

**`GET /v1/video-trim/:id`는 없습니다.** Job 봉투로 폴링하세요:

```text
GET /v1/jobs/:id/status
GET /v1/jobs/:id/result
```

호스티드 MCP: `video_trim`(`packages/mcp-server/src/mcp.ts`). 쓰기는
`idempotency_key`가 필요합니다(OAuth에서는 `mcp:write`). 흐름:
`video_trim` → `jobs_wait` → `jobs_result`.

## 트림 만들기

필수: `video_url`(이 워크스페이스의 `media.sume.com` 아티팩트 또는
에셋), `start`(초, ≥ 0), 그리고 `end` 또는 `duration` **정확히 하나**.
공개 인터넷 fetch는 없습니다. 먼저 가져오세요
(`POST /v1/media-imports`). `Idempotency-Key`는 필수입니다.

선택: `precision`, `audio`, `output`(exact만), 평소의 `mode` /
`webhook_url` / `wait_timeout_seconds` 통신 필드입니다.

기본 `mode`는 **`async`**입니다(`readCommunicationOptions`). `mode:
"sync"`를 주면 최대 **30초** 기다리고 끝난 Job을 `200`으로 주거나,
`202`로 폴링합니다.

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

성공한 submit은 Job을 반환합니다(`request_id`가 Job id). `result_ready`이면
`GET /v1/jobs/:id/result`는 `kind: video_trim`이고 `video_url`(새
`artf_`, 소스가 아님), `duration_seconds`, `actual_start_seconds`,
`precision`, `audio`, `output`, 선택적 `warnings[]`를 담습니다. 그
MP4를 `timeline_create` `video[]`에 `source_in` 0으로 넣으세요.

공개 요금: **Job당 $0.02**(`VIDEO_TRIM_PUBLIC_PRICING`; 라이브는
`GET /v1/catalog`). 프로바이더 추론 없음 — 워커 ffmpeg만.

## 프로그램

| 필드 | 효과 |
|---|---|
| `start` | 인포인트, 소스 시작부터 초. 필수. |
| `end` | 아웃포인트, 초. `end` / `duration` 정확히 하나. 소스를 넘으면 **클램프**하고 결과에 `trim_clamped_to_source` 경고. |
| `duration` | 컷 길이, 초. `0.2`–`900`. `end` / `duration` 정확히 하나. |
| `precision` | `exact`(기본): 프레임 정확 재인코딩(`libx264`, `yuv420p`). `keyframe`: 스트림 카피. GOP 앞에서 시작할 수 있으니 `actual_start_seconds`로 다시 잡으세요. |
| `audio` | `keep`(기본) 또는 `drop`. exact는 유지 오디오를 AAC로 리먹스합니다. |
| `output` | 나가는 길에 선택적 `{ width, height, fps }` 컨폼. **exact만.** width/height 256–2160; `fps` `24` \| `25` \| `30` \| `60`. 생략하면 소스를 상속합니다. |

상한(`packages/api-contract/src/index.ts`): 소스 ≤ **1800**초; 출력 ≤
**900**초; 출력 ≥ **0.2**초.

## 거절(안정 코드)

| 코드 | 언제 |
|---|---|
| `video_trim_range_required` | `end`도 `duration`도 없음. |
| `video_trim_range_conflict` | `end`와 `duration` 둘 다. |
| `video_trim_range_empty` | `end` ≤ `start`, 또는 구간이 900초보다 김. |
| `video_trim_output_requires_exact` | `output`과 `precision: "keyframe"`. |
| `ffmpeg_fields_rejected` | 클라이언트가 `vf` / `filter` / `ffmpeg` / `cmd` / `codec` / `crf` 등을 보냄. 서버가 ffmpeg를 컴파일합니다. |
| `unsupported_media_source` | `video_url`이 Sume 미디어 호스트가 아님. |
| `source_not_found` | 죽은 또는 다른 워크스페이스 `media.sume.com` URL. |
| `unsupported_media_type` | HEAD가 비디오가 아님. |
| `source_duration_exceeded` | 소스가 1800초보다 김(워커). |

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

## 이 표면이 아닌 것

| 필요한 일 | 쓸 것 |
|---|---|
| 프로브 / 스틸 / 선택적 STT | [비디오 검사](/models/video-inspect) |
| 오디오 트랙을 내구성 wav / mp3로 | [오디오 분리](/models/audio-detach) |
| 여러 클립 시퀀스 | [Timeline 1.0](/models/timeline) |
| 픽셀 패스(dim / crop) | [비디오 필터](/models/video-filter) |
| `t`의 소스 크기 프레임 | [비디오 프레임](/models/video-frames) |

## 관련 문서

- [비디오 검사](/models/video-inspect)
- [비디오 프레임](/models/video-frames)
- [오디오 분리](/models/audio-detach)
- [비디오 필터](/models/video-filter)
- [Timeline 1.0](/models/timeline)
- [미디어 입력](/workflows/asset-library)
- [Job과 결과](/workflows/jobs-and-results)
- [MCP 도구와 게이트](/mcp/tools-and-gates)