Sume API로 긴 영상을 짧은 클립으로 나누기

Sume API로 긴 영상을 짧은 클립으로 나누려면 transcribe: true로 POST /v1/video-inspect를 실행해 타이밍이 붙은 단어와 문장을 받고, 자를 구간을 고른 뒤 구간마다 POST /v1/video-trim으로 보내세요. 트림은 Sume에 호스팅된 최대 1,800초 길이의 소스에서 클립마다 새 MP4를 반환합니다. 쇼츠에 필요하다면 그다음 클립마다 크롭과 자막을 적용하세요.

아래 내용은 2026-09-26에 확인한 영상 검사, 영상 트림, 영상 필터, 영상 캡션 문서와 Sume API 레퍼런스를 기준으로 합니다.

긴 영상을 쇼츠로 만드는 파이프라인은 어떤 호출을 하나요?

검사, 트림, 필터는 이전 Sume Job의 출력처럼 여러분 워크스페이스에 있는 media.sume.com 아티팩트나 에셋만 읽습니다. 공개 인터넷에서 가져오는 기능은 없고, 생성 요청마다 Idempotency-Key가 필요합니다. 자막은 공개 HTTPS 영상 URL을 받습니다.

어디를 자를지 어떻게 찾나요?

검사에 전사문을 요청하세요. words[]에는 영상 시작부터 잰 초 단위의 단어별 타이밍이 담기고, segmentation.mode: "sentence"를 주면 갭 없는 문장 segments[]가 더해집니다. 각 문장에는 index, text, start, end, duration_seconds가 있습니다. 선택 사항인 silence_split_seconds(0.2–3)로 문장이 끊기는 위치를 조정할 수 있습니다. frames: false를 주면 스틸을 건너뜁니다.

과금되는 것은 전사문뿐이며 오디오 분당 과금됩니다. duration_seconds는 그 예약에 쓰이는 힌트일 뿐이고 최대 600입니다. 과금, 폴링, 거부 사유는 영상 검사 API에서 다룹니다.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webinar-transcript-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/webinar.mp4",
    "frames": false,
    "transcribe": true,
    "segmentation": { "mode": "sentence" },
    "duration_seconds": 600
  }'

트림은 exact와 keyframe 중 어떤 정밀도로 해야 하나요?

클립마다 트림 하나를 보내고, start와 end는 전사문에서 가져오세요. 클립 하나의 길이는 0.2–900초입니다. 트림 계약 전체는 트림, 필터, 오디오 분리에 있습니다. 전사문을 기준으로 자를 때 중요한 선택은 precision입니다.

• "exact"(기본값)는 프레임 단위로 정확하게 재인코딩하므로(libx264, yuv420p) 클립이 전사문이 가리킨 지점에서 시작합니다. output 컨폼을 받는 정밀도는 이것뿐입니다.
• "keyframe"은 스트림 카피입니다. 재인코딩도 화질 손실도 없지만, 컷이 최대 한 GOP만큼 일찍 시작될 수 있습니다. 전사문의 시각을 actual_start_seconds 기준으로 다시 맞추고, 이 정밀도에는 output을 보내지 마세요(video_trim_output_requires_exact).
• 현재 exact 트림은 HDR 소스를 hdr_source_unsupported로 거부하고 keyframe을 쓰도록 안내합니다.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webinar-clip-03" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/webinar.mp4",
    "start": 312.4,
    "end": 356.9
  }'

각 클립을 세로 화면에 맞게 리프레임하려면 어떻게 하나요?

클립마다 영상 필터의 crop op를 실행하세요. 필터 소스는 300초가 상한이므로, 크롭할 클립은 그 이하 길이로 유지하세요. 9:16 크롭 비율은 가로 영상을 세로로 변환하기에서 단계별로 계산합니다. 트림의 output 컨폼은 스케일만 하고 크롭은 하지 않습니다. 현재 width와 height를 모두 지정하면 클립이 정확히 그 크기로 스케일되므로, 1080×1920으로 컨폼한 16:9 클립은 리프레임되는 것이 아니라 왜곡됩니다.

클립마다 자막은 어떻게 입히나요?

클립의 video_url을 공개 HTTPS 영상 URL을 받는 POST /v1/video-captions로 보내세요. 트림한 클립은 media.sume.com 아티팩트로 반환되며, 자막 문서도 자체 예제에서 이런 URL을 사용합니다. 독립 실행형 자막 Job은 60초 이하 영상에 대한 고정 추정치로 가격이 매겨지고, 현재 자막 워커는 그보다 긴 소스를 duration_out_of_range로 거부합니다. 그러니 자막을 입힐 클립은 60초 이하로 유지하세요. 워커는 오디오 스트림이 없는 소스도 거부하므로(missing_audio_stream), 트림의 audio는 기본값인 keep으로 두세요.

이미 받은 전사문을 재사용하려면 그 단어들을 words로 넘기세요. 각 항목에는 text, start, end가 필요하고 API 레퍼런스는 이 시각의 상한을 60초로 두므로, 시각을 클립의 actual_start_seconds 기준으로 다시 맞추세요. 검사 전사문은 이 필드를 word라고 부르고, 자막은 text라고 부릅니다. words를 주면 음성 인식을 건너뛰고 정확히 그 단어들을 그 시각에 입힙니다. 스타일은 영상에 자막을 입히는 방법에서 다룹니다.

한도는 어떻게 되나요?

긴 영상을 쇼츠로 나누는 작업에는 다음 상한이 적용됩니다.

• 검사와 트림 소스: ≤ 1,800초. 트림한 클립: 0.2–900초. 필터 소스: ≤ 300초. 자막 소스: 60초 이하 기준으로 가격이 매겨지며, 현재는 그보다 길면 거부됩니다.
• 음성으로 만드는 자막에는 들리는 음성이 필요합니다. 무음 클립은 caption_no_speech로 실패합니다.
• 호스팅 MCP 서버에서는 script_run이 프로그램 하나 안에서 video_trim을 호출해 같은 형태의 컷을 여러 개 만들 수 있습니다. 그 안의 유료 생성 요청에도 각각 idempotency_key가 필요합니다.