Sume API로 영상 트림, 필터, 오디오 분리하기

Sume로 영상을 트림하거나 필터를 적용하거나 오디오를 분리하려면 세 가지 API 중 하나를 호출하세요. 영상 트림은 [start, end) 구간을 잘라 새 MP4를 만들고, 영상 필터는 dim, crop 또는 허용 목록에 있는 filtergraph를 적용해 새 MP4를 만들며, 오디오 분리는 오디오 트랙을 내구성 있는 wav나 mp3로 추출합니다. 세 API 모두 Sume에 호스팅된 클립 하나를 받고 소스는 건드리지 않습니다.

아래 내용은 2026-09-25에 확인한 영상 트림, 영상 필터, 오디오 분리 문서를 기준으로 합니다.

트림, 필터, 오디오 분리의 공통점은 무엇인가요?

문서는 트림과 필터를 “Material preparation, not timeline placement”(타임라인 배치가 아니라 소재 준비)라고 부릅니다. 시퀀스, 트랜지션, 오디오 스파인은 Timeline 1.0이 맡습니다(롱폼 영상을 조립하는 방법 참고). 세 API에는 다음 규칙이 공통으로 적용됩니다.

• video_url은 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 호스트 밖 URL은 접수 단계에서 거부되니 먼저 POST /v1/media-imports로 가져오세요.
• 모든 생성 요청에는 Idempotency-Key가 필요합니다. 기본 mode는 async이며, mode: "sync"는 완료된 Job을 200으로 받기 위해 최대 30초 기다리고, 그렇지 않으면 202를 받아 폴링합니다.
• 도구별 GET은 없습니다. GET /v1/jobs/:id/status와 GET /v1/jobs/:id/result를 폴링하세요. 호스팅 MCP 서버에서는 video_trim, video_filter, audio_detach 중 하나를 호출한 뒤 jobs_wait와 jobs_result를 호출합니다.
• ffmpeg 컴파일은 서버가 합니다. filter, ffmpeg, cmd, codec 같은 ffmpeg 필드를 보내면 ffmpeg_fields_rejected가 반환됩니다.
• 각각 Job당 과금되며, 프로바이더 추론 없이 워커의 ffmpeg만 실행합니다. 필터 검사는 무료입니다. 요율은 API 요금에 있으니 GET /v1/catalog에서 확인하세요.

클립은 어떻게 트림하나요?

video_url, start(초, ≥ 0), 그리고 end와 duration(0.2–900) 중 정확히 하나를 보내세요. 소스 길이를 넘는 end는 소스 끝으로 제한되고, 결과에 trim_clamped_to_source 경고가 붙습니다.

precision: "exact"(기본값)는 프레임 단위로 정확한 재인코딩(libx264, yuv420p)입니다. "keyframe"은 스트림 카피라서 컷이 한 GOP 먼저 시작될 수 있으니, actual_start_seconds를 기준으로 다시 맞추세요. audio는 keep(기본값) 또는 drop입니다. 선택 사항인 output({ width, height, fps })은 exact 정밀도에서만 동작하며, 너비와 높이는 256–2160, fps는 24, 25, 30, 60 중 하나입니다.

결과(kind: video_trim)에는 소스가 아닌 새 video_url과 actual_start_seconds가 담깁니다. 그 MP4를 source_in 0으로 timeline_create의 video[]에 넣으세요.

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

클립에 dim이나 crop을 적용하고, 프로그램을 먼저 검사하려면 어떻게 하나요?

필터 프로그램은 ops[], 필터만 담은 filtergraph, 또는 둘 다로 구성되며, ops[]가 먼저 실행됩니다. 프로그램이 바꾸지 않는 한 출력은 소스의 기하 정보, 프레임레이트, 오디오를 그대로 이어받습니다.

먼저 검증하려면 프로그램을 POST /v1/video-filter/check로 보내세요. 인코딩과 같은 스키마, op 및 filtergraph 허용 목록, 소스 프리플라이트를 실행하고, 400 대신 진단 결과를 반환합니다. 반환값은 valid, diagnostics[], 유효할 때의 estimate, next_action(submit_video_filter 또는 fix_program_and_recheck)입니다. Job을 만들지 않고, 크레딧을 예약하지 않으며, Idempotency-Key도 필요 없습니다. 검사를 통과한 프로그램도 실행 박스에서 실패할 수 있으며(잘못된 식, 메모리, 시간), 이때는 구조화된 Job 오류로 나타납니다.

• dim: 클립 전체의 루마에 값을 곱합니다. amount는 (0, 1] 범위입니다. 0.45는 더 어둡고, 1은 변화가 없으며, 검은색은 검은색으로 남습니다.
• crop: 소스 프레임에 대한 비율로 나타낸 사각형입니다. x와 y는 [0, 1], width와 height는 [0.05, 1] 범위이며, x+width ≤ 1, y+height ≤ 1이어야 합니다.
• op는 최대 8개입니다.
• filtergraph: 최대 2048자, 이름 있는 필터 최대 32개이며, 입력, 출력, 경로는 넣을 수 없습니다. 허용 목록에 있는 톤, 블러, 기하, 페이드, 내부 합성 필터만 쓸 수 있고, trim, setpts, drawtext, subtitles, movie, lut3d와 파일이나 소켓을 읽는 모든 필터는 목록에 없습니다.

curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "ops": [{ "op": "dim", "amount": 0.45 }]
  }'

영상에서 오디오 트랙은 어떻게 분리하나요?

POST /v1/audio-detach의 기본 출력은 샘플 단위로 정확한 wav(pcm_s16le)로, timeline_create의 audio.url, POST /v1/timeline-1.0/audio, 음성 인식이 원하는 형태입니다. 결과로 새 audio_url을 반환합니다.

• format: wav(기본값) 또는 mp3(128 kbps).
• range: 초 단위의 선택적 { start, end? }입니다. 트랙이 900초를 넘지 않는다면 생략해서 트랙 전체를 쓸 수 있습니다.
• channels: source(기본값) 또는 mono. sample_rate: 16000, 44100, 48000 중 하나이며, 16000에 mono를 조합하면 STT에 맞는 형태입니다.
• 오디오 트랙이 없는 소스는 detach_source_has_no_audio로 실패합니다. 먼저 영상 검사로 probe.has_audio를 확인하세요(frames: false면 충분합니다).
• 한 트랙에서 여러 구간이 필요하면 한 번 분리한 뒤 타임라인 오디오로 나누세요.

트림, 필터, 오디오 분리가 왜 거부되었나요?

• 트림: video_trim_range_required(end도 duration도 없음), video_trim_range_conflict(둘 다 있음), video_trim_range_empty(end ≤ start, 또는 900초 초과), video_trim_output_requires_exact, source_duration_exceeded(소스가 1800초보다 김).
• 필터: video_filter_ops_empty, video_filter_too_many_ops, unsupported_filter_op(dim과 crop만 가능), video_filter_amount_out_of_range, video_filter_crop_out_of_bounds, invalid_filtergraph, source_too_large, output_duration_exceeded(소스가 300초보다 김).
• 오디오 분리: audio_detach_range_empty, detach_source_has_no_audio, detach_start_past_source.
• 세 도구 공통: unsupported_media_source(Sume 미디어 호스트에 있지 않음), source_not_found(죽었거나 다른 워크스페이스에 속한 media.sume.com URL), unsupported_media_type(HEAD 결과가 영상이 아님).