비디오 프레임
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
현재 SoT. Media L2 정확 프레임 추출(
video_frames, #5831). dest와 prod. 클립 검사가 아닙니다 — 그건 비디오 검사(프로브 + 샘플 스틸 + 선택적 STT) 입니다. 새 MP4가 아닙니다 — 구간 컷은 비디오 트림입니다.
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).
이 계열에는 /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(긴 변
클램프; 생략하면 소스 프레임 크기).
성공한 제출은 202이며 request_id = video_frames_id(job id)와
video_frames 객체를 반환합니다. 나중에 읽으세요:
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)는
비디오 검사입니다. 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 | 비디오 검사 |
| 새 MP4 컷 | 비디오 트림 |
| 오디오 트랙을 내구성 wav / mp3로 | 오디오 분리 |
| 픽셀 패스(dim / crop) | 비디오 필터 |
| 여러 클립 시퀀스 | Timeline 1.0 |
| 렌더 전 HyperFrames 구성 보기 | hyperframes_check 다음 hyperframes_snapshot |