비디오 검사

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

현재 SoT. 새 클립 검사는 이 표면입니다. 비디오 분석이 아닙니다.

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).

호스티드 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로 줍니다.

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

준비가 되면 리소스에 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의 소스 크기 프레임은 이 경로가 아니라 비디오 프레임입니다.

전사 (선택, 과금)

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	레거시 비디오 분석 (prod는 PR-C2까지, dest는 `410`)
dest 의미 Q&A / 구간	`mcp.dev.sume.com` 목록에 있을 때 `video_analyze` / `video_segment`
`t`의 소스 크기 프레임	비디오 프레임
공개 URL에 캡션 입히기	비디오 캡션
새 MP4 컷	비디오 트림
오디오 트랙을 wav / mp3로	오디오 분리
픽셀 패스(dim / crop)	비디오 필터
여러 클립 시퀀스	Timeline 1.0