---
title: 비디오 프레임
description: Sume 호스트 클립 하나에서 지정한 시각의 스틸을 뽑습니다. 소스 크기 내구성 이미지 아티팩트. 무료.
---

> **현재 SoT.** Media L2 정확 프레임 추출(`video_frames`, #5831). dest와
> prod. **클립 검사가 아닙니다** — 그건
> [비디오 검사](/models/video-inspect)(프로브 + 샘플 스틸 + 선택적 STT)
> 입니다. **새 MP4가 아닙니다** — 구간 컷은
> [비디오 트림](/models/video-trim)입니다.

Video frames는 **하나의** 워크스페이스 `media.sume.com` 클립과 프로그램
(`at[]` 또는 `fps`)을 받아 **내구성** `media.sume.com` 이미지 아티팩트를
반환합니다. 소스는 그대로입니다. 서버가 워커 미디어 런타임에서 ffmpeg를
컴파일합니다(`apps/api/src/routes.ts` `submitVideoFramesJob` /
`getVideoFrames`; `apps/api/src/schemas.ts` `createVideoFramesSchema`;
`apps/worker/src/video-frames-executor.ts`).

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

이 계열에는 **`/v1/models/sume/…/runs` 별칭이 없습니다.** 리소스 id가
job id입니다(`request_id` = `video_frames_id`).

제출은 항상 **`202`**입니다. `submitVideoFramesJob`이
`communicationMode: "async"`로 고정합니다. `mode: "sync"`를 보내도
`200`을 기대하지 마세요. 이 GET(또는 `GET /v1/jobs/:id/status`)으로
폴링하세요.

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

무료입니다(스크린샷 hop과 같은 등급 — 좌석·예약 없음).

## 추출 만들기

필수: `video_url`(이 워크스페이스의 `media.sume.com` 아티팩트 또는
에셋) **그리고 `at[]` 또는 `fps` 중 정확히 하나**. 오픈 인터넷 fetch는
없습니다. 먼저 가져오세요(`POST /v1/media-imports`). MCP 쓰기에는
`Idempotency-Key`가 필요합니다. REST에서도 보내야 재시도가 두 번째
추출을 넣지 않습니다.

선택: `format` `jpeg`(기본) 또는 `png`; `max_edge` **16–2160**(긴 변
클램프; 생략하면 소스 프레임 크기).

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

성공한 제출은 `202`이며 `request_id` = `video_frames_id`(job id)와
`video_frames` 객체를 반환합니다. 나중에 읽으세요:

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

`resource_status`가 `ready`이면 `frames[{t,url,width,height}]`는 내구성
`artf_` 이미지입니다. 한 시각의 추출이 실패하면 그 칸의 `url`은
`null`이고, **job은 실패하지 않습니다.** `source_duration_seconds`는
워커가 프로브한 길이입니다.

## 프로그램

| 필드 | 효과 |
|---|---|
| `at[]` | 명시 초. **1–24**개, 각각 ≥ 0. 모든 값은 `0 <= t < duration`이어야 하며 아니면 워커가 `frame_time_out_of_range`로 실패하고 프로브된 duration을 이름합니다. |
| `fps` | 목록 대신 샘플 레이트. `0 < fps ≤ 2`. 중간 빈 샘플(`0.5/fps`, `1.5/fps`, …)로 펼치고 **24**프레임에서 자릅니다. |
| `format` | `jpeg`(기본) 또는 `png`(무손실 검사). |
| `max_edge` | 선택 긴 변 클램프, **16–2160**. 생략하면 소스 크기(리스테이지 경로). |

`at[]` 또는 `fps` **중 정확히 하나**. 상한: 소스 ≤ **300**초
(`VIDEO_ANALYSIS_HARD_MAX_DURATION_SECONDS`); 호출당 **24**프레임.

클립 전체 증거(프로브, 8장 중간 빈 스틸, 선택적 STT)는
[비디오 검사](/models/video-inspect)입니다. inspect 스틸의 기본
`max_edge`는 **768**이고, 이 경로는 그 클램프를 생략합니다.

## 거절(안정 코드)

| 코드 | 언제 |
|---|---|
| `ffmpeg_fields_rejected` | 클라이언트가 `vf` / `filter` / `filter_complex` / `select` / `ffmpeg` / `cmd` / `codec` / `crf` / `preset`를 보냄. 서버가 추출을 컴파일합니다. |
| `400`(스키마) | `at[]`와 `fps`를 같이, 둘 다 없음, `at` 24개 초과, `fps > 2`, 또는 `video_url`이 `media.sume.com`이 아님. |
| `frame_time_out_of_range` | `at` 값이 `[0, duration)` 밖(워커, 프로브 후). |
| `duration_out_of_range` | 소스가 300초보다 김(워커). |
| `invalid_source_url` | 저장된 job에 쓸 수 있는 `video_url`이 없음(워커). |

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

소스가 90초보다 길면 `warnings[]`에 `low_confidence_long_video`가 올 수
있습니다(프로브 재사용). 그 때문에 job이 실패하지는 않습니다.

## 이 표면이 아닌 것

| 필요한 일 | 쓸 것 |
|---|---|
| 프로브 / 샘플 스틸 / 선택적 STT | [비디오 검사](/models/video-inspect) |
| 새 MP4 컷 | [비디오 트림](/models/video-trim) |
| 오디오 트랙을 내구성 wav / mp3로 | [오디오 분리](/models/audio-detach) |
| 픽셀 패스(dim / crop) | [비디오 필터](/models/video-filter) |
| 여러 클립 시퀀스 | [Timeline 1.0](/models/timeline) |
| 렌더 전 HyperFrames 구성 보기 | `hyperframes_check` 다음 `hyperframes_snapshot` |

## 관련 문서

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