미디어 도구

Sume API로 영상에서 프레임을 추출하는 방법

POST /v1/video-frames는 Sume에 호스팅된 클립 하나에서 지정한 시각의 스틸을 소스 크기의 내구성 있는 이미지로 반환합니다. 이 호출은 과금되지 않습니다.

읽는 시간 4분Sume
전체 글

Sume로 영상에서 프레임을 추출하려면 Sume에 호스팅된 클립 하나와 타임스탬프 목록(at[]) 또는 샘플링 레이트(fps)를 POST /v1/video-frames로 보내세요. Sume는 max_edge를 지정하지 않는 한 소스 프레임 크기 그대로 내구성 있는 media.sume.com 이미지 아티팩트를 반환하며, 소스는 건드리지 않고 이 호출에는 과금하지 않습니다.

아래 내용은 2026-09-25에 확인한 영상 프레임 문서를 기준으로 합니다.

클립에서 프레임은 어떻게 추출하나요?

video_url과 함께 at[] 또는 fps 중 정확히 하나를 보내세요. URL은 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 공개 인터넷에서 가져오는 기능은 없고 호스트 밖 URL은 접수 단계에서 거부되므로, 먼저 POST /v1/media-imports로 가져오세요.

MCP 쓰기에는 Idempotency-Key가 필수입니다. REST에서도 보내세요. 그래야 재시도할 때 추출이 한 번 더 큐에 들어가지 않습니다.

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가 반환되나요?

추출은 항상 비동기로 실행됩니다. 제출 응답은 언제나 202이므로 200을 기대하고 mode: "sync"를 보내지 마세요. 응답에는 request_id가 담기며, 이 값이 video_frames_id이자 Job ID입니다. GET /v1/video-frames/:id 또는 GET /v1/jobs/:id/status를 폴링하세요. 이 도구에는 /v1/models/sume/…/runs 별칭이 없습니다.

호스팅 MCP 서버에서는 video_frames_create, jobs_wait, video_frames_get 순서로 호출합니다. 쓰기에는 idempotency_key가 필요하고, OAuth에서는 mcp:write도 필요합니다. Claude Code, Cursor, Codex를 Sume에 연결하기를 참고하세요.

결과에는 무엇이 담기나요?

resource_status가 ready가 되면 frames[{t,url,width,height}]에 내구성 있는 artf_ 이미지가 담기고, source_duration_seconds에는 워커가 프로브한 길이가 담깁니다.

  • 어느 한 시각의 추출이 실패하면 그 항목의 url은 null로 옵니다. 그래도 Job은 실패하지 않습니다.
  • 소스가 90초보다 길면 warnings[]에 low_confidence_long_video가 포함될 수 있습니다. 이 경우에도 Job은 실패하지 않습니다.

한도는 어떻게 되나요?

영상 프레임은 과금되지 않으며, 스크린샷 hop과 같은 등급입니다. 슬롯도 예약도 차지하지 않습니다.

영상 프레임 문서의 프로그램과 상한, 2026-09-25 확인.
필드 또는 상한규칙
at[]명시한 초 값: 1–24개, 각각 ≥ 0이며 모두 0 <= t < duration을 만족해야 함.
fps0 < fps ≤ 2, 구간 중간 샘플(0.5/fps, 1.5/fps, …)로 펼쳐지며 최대 24프레임.
formatjpeg(기본값) 또는 무손실 검사용 png.
max_edge선택적인 긴 변 제한, 16–2160. 생략하면 소스 크기 유지.
소스 길이≤ 300초.
호출당 프레임24장.

프레임 요청이 왜 거부되었나요?

  • 400(스키마): at[]과 fps를 둘 다 보냄, 둘 다 없음, at 값이 24개 초과, fps > 2, 또는 media.sume.com에 있지 않은 video_url.
  • frame_time_out_of_range: at 값이 [0, duration) 범위를 벗어났으며, 워커가 프로브한 뒤에 발견합니다. 오류에 프로브된 길이가 표시됩니다.
  • duration_out_of_range: 소스가 300초보다 깁니다.
  • invalid_source_url: 저장된 Job에 쓸 수 있는 video_url이 없습니다.
  • ffmpeg_fields_rejected: 요청에 vf, filter, filter_complex, select, ffmpeg, cmd, codec, crf, preset 중 하나가 들어 있습니다. 추출 컴파일은 서버가 합니다.

영상 프레임과 영상 검사 중 무엇을 써야 하나요?

원하는 시각의 정확한 스틸을 소스 크기로 받으려면 영상 프레임을 쓰세요. 클립 전체에 대한 근거, 즉 프로브, 구간 중간 스틸 여덟 장, 선택적 전사문이 필요하면 영상 검사를 쓰세요(영상 검사 API). 검사 스틸의 max_edge 기본값은 768이고, 영상 프레임은 이 제한을 두지 않습니다.

영상 프레임은 새 MP4를 만들지 않습니다. 구간 컷은 영상 트림의 몫이며, 트림, 필터, 오디오 분리에서 다룹니다.

출처

관련 글

작성자 Sume