Sume API로 영상의 오디오를 교체하거나 제거하기

Sume API로 영상의 오디오를 교체하려면 클립을 Timeline 1.0 렌더(POST /v1/timeline-1.0/render)의 유일한 video[] 슬롯으로 넣고, 새 트랙을 audio.url로 넘기세요. 출력의 소리는 클립이 아니라 그 스파인에서 나옵니다. 오디오를 제거하려면 POST /v1/video-trim에 audio: "drop"을 지정해 클립을 자르세요.

아래 내용은 2026-09-26에 확인한 영상 트림, 오디오 분리, Timeline 1.0 문서와 Sume API 레퍼런스의 필드 설명을 기준으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 오디오 분리 자체의 필드는 영상 트림, 필터, 오디오 분리에서 다룹니다.

어떤 호출이 필요한가요?

각 도구는 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋인 클립(앞서 실행한 Sume Job의 출력 등)을 받아 새 아티팩트를 반환하며, 소스는 건드리지 않습니다. 모든 생성 요청에는 Idempotency-Key가 필요합니다.

영상에서 오디오를 어떻게 제거하나요?

audio: "drop"으로 클립 전체를 트림하세요. start: 0으로 두고 end를 클립 길이로 지정합니다. 소스 길이를 넘는 end는 소스 끝으로 제한되고 trim_clamped_to_source 경고가 붙지만, 트림 한 번으로 남길 수 있는 길이는 최대 900초이며 더 긴 구간은 video_trim_range_empty로 거부됩니다. 트림의 다른 옵션은 영상 트림, 필터, 오디오 분리에서 다룹니다.

오디오 트랙을 아예 없애는 대신 무음 트랙을 두고 싶다면, 클립을 audio.mode: "silence"로 렌더링하세요.

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-mute-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
    "start": 0,
    "end": 42,
    "audio": "drop"
  }'

오디오를 새 트랙으로 어떻게 교체하나요?

audio.url에는 앞서 실행한 Sume Job에서 나온 TTS 마스터처럼 Sume에 호스팅된 새 트랙을, audio.duration_seconds(1–1800)에는 출력 길이를 지정하세요. 클립은 start: 0과 스파인을 덮는 duration으로 video[0]에 넣습니다. 현재 컴파일러에서는 클립 자체의 오디오가 전혀 믹싱되지 않습니다.

• 화면 구성을 그대로 유지하세요. Timeline의 기본 출력은 1080×1920이고 기본 fit은 cover입니다. 현재 코드에서 cover는 모양이 다른 클립을 화면에 꽉 차게 스케일하고 나머지를 잘라 냅니다. output.width와 output.height(256–2160 사이의 짝수 정수)를 클립 크기에 맞추세요.
• 새 오디오가 클립보다 길 때: Sume API 레퍼런스에 따르면 render.pad_mode가 슬롯을 채웁니다. auto(기본값)는 긴 정지 화면을 유지하는 대신 짧은 소스를 루프하고, loop는 소스를 다시 재생하며, freeze는 마지막 프레임을 유지합니다. 문서는 패딩되거나 루프된 짧은 소스를 실패가 아닌 소프트 경고로 설명합니다.
• 클립이 오디오보다 길 때: 슬롯을 줄이세요. 문서상 영상 커버리지는 스파인 끝을 최대 0.5초까지만 넘을 수 있으며, 현재 코드에서는 그보다 늦게 끝나는 슬롯이 invalid_segment_timing으로 거부됩니다.
• 스파인에 알맞은 품질의 파일을 쓰세요. 출력은 스파인의 샘플레이트와 채널을 그대로 이어받으며, 영상 검사가 음성 인식용으로 만드는 16 kHz 오디오처럼 32 kHz 미만인 스파인은 audio_spine_low_fidelity 경고를 냅니다.
• 새 음성을 넣어도 입 모양은 바뀌지 않습니다. Sume의 모델 문서에 따르면 영상 모델은 나중에 입힌 보이스오버에 맞춰 립싱크하지 않습니다. 말하는 얼굴에 새 대사를 넣으려면 립싱크 클립을 만드세요.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-replace-audio-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/new-voice.wav",
      "duration_seconds": 30
    },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 30 }
    ],
    "render": { "pad_mode": "freeze" }
  }'

기존 오디오를 더 크게 또는 작게 하려면 어떻게 하나요?

POST /v1/audio-detach로 클립의 오디오를 분리하세요. 기본 출력인 wav가 audio.url이 기대하는 형식이며, 오디오 트랙이 없는 클립은 detach_source_has_no_audio로 실패합니다. 그다음 그 파일 위에 클립을 렌더링하면서, 스파인에 적용되는 audio.gain_db를 −60에서 12 dB 사이로 지정하세요. 기본값은 0이며 silence와는 함께 쓸 수 없습니다. 목소리 아래에 음악도 깔려면 배경 음악을 넣는 방법을 참고하세요.

비용은 얼마이고, 요청은 왜 거부되었나요?

API 요금에 나온 렌더의 공개 요율은 출력 분당 $0.10이며, 예약되는 분량은 ceil(audio.duration_seconds / 60)분입니다. 트림과 오디오 분리의 요율은 GET /v1/catalog에서 실시간으로 확인하라고 문서가 안내합니다.

• audio_url_required / audio_url_and_parts_exclusive: 스파인도 silence도 없거나, url과 parts를 함께 보냈습니다.
• silent_audio_takes_no_url / _parts / _gain / _source_in: silence와 함께 스파인 필드를 보냈습니다.
• unsupported_media_source / source_not_found: 호스트 밖 URL이거나 죽은 URL입니다.