미디어 도구

영상 검사 API: 클립 프로브, 스틸 샘플링, 전사문 받기

POST /v1/video-inspect는 Sume에 호스팅된 클립 하나를 읽어 프로브 정보, 샘플링한 스틸, 선택적 전사문을 반환합니다. 프로브와 스틸은 과금되지 않습니다.

읽는 시간 5분Sume
전체 글

Sume의 영상 검사 API(POST /v1/video-inspect)는 Sume에 호스팅된 클립 하나를 읽고 프로브 정보, 내구성 있는 이미지 파일로 저장한 샘플 스틸, 그리고 요청한 경우 음성 인식 전사문을 반환합니다. 프로브와 스틸은 과금되지 않고 전사만 과금되며, 검사는 소스를 다시 인코딩하거나 MP4를 만들지 않습니다.

아래 내용은 모두 2026-09-25에 확인한 영상 검사 문서를 기준으로 합니다.

클립은 어떻게 검사하나요?

video_url을 보내세요. 이 값은 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 공개 인터넷에서 가져오는 기능은 없으며, 호스트 밖 URL은 접수 단계에서 거부되므로 먼저 POST /v1/media-imports로 가져오세요(미디어 입력과 출력 참고). Idempotency-Key는 필수입니다.

기본 mode는 sync입니다. 핸들러는 최대 30초 기다린 뒤 완료된 검사를 200으로 돌려주거나, 폴링할 큐 대기 Job을 202로 돌려줍니다. 응답에는 request_id가 담기며, 이 값이 video_inspect_id이자 Job ID입니다. 나중에 GET /v1/video-inspect/:id로 조회하세요.

호스팅 MCP 서버의 도구는 video_inspect입니다. GET 래퍼는 없으므로 제출 결과가 202이면 jobs_wait, jobs_result 순서로 폴링하세요. 쓰기에는 idempotency_key가 필요하고, OAuth에서는 mcp:write도 필요합니다.

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

검사는 무엇을 반환하나요?

준비가 끝나면 리소스에 다음 필드가 담깁니다. 타입이 지정된 장면(scene)은 반환하지 않습니다. 검사가 주는 것은 프로브 정보, 스틸, 선택적 음성 인식입니다.

  • probe: probe.has_audio를 포함한 파일 정보.
  • frames[{t,url,width,height}]: 내구성 있는 media.sume.com 이미지 아티팩트로 저장된 스틸.
  • transcript(요청한 경우): text, words[], 선택적 문장 segments[], audio_url.
  • warnings[].

받을 스틸은 어떻게 고르나요?

frames 필드가 프로그램을 정합니다. 객체로 보낼 때는 at[] 또는 fps 중 정확히 하나를 넣어야 하고, format(기본값 jpeg, 또는 png)과 max_edge(64–2160, 기본값 768)도 지정할 수 있습니다. 상한은 소스 길이 최대 1800초, 호출당 스틸 24장입니다.

기본값인 seek: "precise"는 정확한 순간까지 디코드합니다. seek: "fast"는 각 스틸을 그 순간 또는 그 이전의 키프레임에 맞추고 디코드를 건너뜁니다. 그래서 최대 한 GOP(일반적인 소스에서 대략 0–5초)만큼 앞당겨질 수 있지만, 뒤로 밀리지는 않습니다. 훑어볼 때는 fast를 쓰고, 타임스탬프가 정확히 맞아야 할 때는 precise를 유지하세요.

영상 검사 문서의 프레임 프로그램, 2026-09-25 확인.
`frames`결과
생략구간 중간(mid-bin) 스틸 8장(클립이 8초보다 짧으면 1 fps).
false프로브만, 스틸 없음.
{ at: [seconds…] }명시한 타임스탬프: 값 1–24개, 각각 ≥ 0.
{ fps: n }샘플링 레이트 0 < n ≤ 2, 구간 중간 샘플, 최대 24장.

전사문은 어떻게 받고, 비용은 얼마인가요?

transcribe: true를 설정하면 클립의 오디오에 Sume STT 1.0이 실행됩니다. 예약이 걸리는 것은 이 부분뿐이고, 프로브와 스틸은 그대로 과금되지 않습니다. 전사는 API 요금에 나온 요율로 오디오 분당 과금되며, 문서는 GET /v1/catalog에서 실시간으로 확인하라고 안내합니다.

  • duration_seconds를 생략하면 1분이 예약됩니다. 힌트의 최댓값은 600초입니다.
  • language_code(예: en, ko)는 힌트입니다. 생략하면 언어를 자동으로 감지합니다.
  • 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 객체에 둘 중 어느 것도 없습니다.
  • frame_time_out_of_range: at 값이 [0, duration) 범위를 벗어났습니다. 오류에 영상 길이가 표시됩니다.
  • source_not_found: 죽었거나 다른 워크스페이스에 속한 media.sume.com URL입니다.

다른 미디어 도구는 언제 써야 하나요?

검사는 클립을 읽기만 하며, 다시 인코딩하지 않습니다. 다른 작업에는 각자의 경로가 있습니다.

출처

관련 글

작성자 Sume