API로 영상에 배경 음악 넣기: 루프, 페이드, 더킹

Sume API로 영상에 배경 음악을 넣으려면 soundtrack 객체를 담아 Timeline 1.0 렌더(POST /v1/timeline-1.0/render)를 보내세요. soundtrack에는 Sume에 호스팅된 음악의 url을 넣고, 선택 필드인 gain_db, loop, fade_out_seconds, duck_db를 더할 수 있습니다. Sume는 이 배경 음악을 오디오 스파인 아래에 믹싱해 MP4 하나를 반환합니다.

아래 내용은 2026-09-26에 확인한 Timeline 1.0 문서와 Sume API 레퍼런스의 Timeline 필드 설명을 기준으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 렌더 문서의 나머지 부분은 롱폼 영상을 조립하는 방법을 참고하세요.

음성과 음악은 어디서 가져오나요?

렌더에 들어가는 모든 URL은 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 앞서 실행한 Sume Job의 출력이 그 예입니다. 다른 호스트에 있는 음악 URL은 unsupported_media_source로 거부됩니다.

• 음성 스파인: audio.url, 그리고 출력 길이를 정하는 audio.duration_seconds(1–1800)입니다. API 레퍼런스는 오디오 분리로 만든 wav나 TTS 마스터를 스파인에 알맞은 품질의 파일로 꼽습니다.
• 음악: 예를 들어 Music Router로 만든 트랙을 쓸 수 있으며, 결과 아티팩트 중 type이 audio인 것에서 읽습니다. Sume는 생성 결과를 Sume 소유의 미디어 URL로 미러링합니다.

보이스오버 아래에 배경 음악을 어떻게 믹싱하나요?

렌더 본문에서 audio, video와 나란히 soundtrack을 추가하세요. 출력 오디오는 스파인에 배경 음악을 더한 것이며, 현재 컴파일러에서는 슬롯 자체의 소리가 전혀 믹싱되지 않습니다. 클립에 이미 내레이션이 들어 있다면 오디오 분리로 추출해 그 파일을 스파인으로 넘기세요. 오디오 분리의 기본 출력인 wav가 audio.url이 기대하는 형식입니다.

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-music-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 24
    },
    "soundtrack": {
      "url": "https://media.sume.com/artifacts/artf_demo/music.mp3",
      "loop": true,
      "fade_out_seconds": 3,
      "duck_db": 8
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 24 }
    ]
  }'

gain_db, loop, fade_out_seconds, duck_db는 각각 무엇을 하나요?

필수 필드는 url뿐입니다. 음성의 레벨은 따로 정합니다. 스파인에는 audio.gain_db(−60에서 12까지, 기본값 0)가 적용됩니다.

더킹은 어떻게 동작하나요?

duck_db는 스파인의 엔벨로프를 따라가는 사이드체인 더킹이라서, 누군가 말하는 동안 배경 음악이 내려갑니다. API 레퍼런스는 이 값을 고정 게인이 아니라 말소리 레벨의 스파인에 대한 목표 깊이라고 설명하며, 현재 코드에서는 보이스오버가 조용할수록 더킹도 덜 걸립니다.

현재 코드에서 더킹은 스파인을 키 신호로 쓰며, 임계값은 −40 dBFS, 어택은 20 ms, 릴리스는 300 ms입니다. 코드 주석에 따르면 이 임계값은 TTS 보이스오버의 거의 무음인 틈에서 배경 음악이 다시 올라올 만큼 낮고, 녹음된 목소리의 룸톤 때문에 더킹이 계속 걸려 있지 않을 만큼 높습니다.

duck_db에는 실제 스파인이 필요합니다. audio.mode: "silence"에서는 더킹의 기준으로 삼을 소리가 없으므로 요청이 duck_requires_audio_spine으로 거부됩니다.

음성 없이 음악만 있는 영상도 만들 수 있나요?

네. audio.mode: "silence"와 audio.duration_seconds를 설정하고 url, parts, gain_db, source_in은 넣지 않은 채 soundtrack을 추가하세요. 이때는 배경 음악이 오디오 트랙 전체가 되므로, API 레퍼런스는 작게 깔려는 경우가 아니라면 soundtrack.gain_db를 0으로 설정하라고 안내합니다. 생략하면 여전히 −16 dB로 렌더링됩니다. duck_db는 넣지 마세요. 이렇게 만드는 사진 몽타주는 이미지 슬라이드쇼 API에서 다룹니다.

비용은 얼마이고, 무엇이 잘못될 수 있나요?

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

• unsupported_media_source: 음악 URL이 Sume 미디어 호스트에 있지 않습니다.
• soundtrack_fade_exceeds_output: 배경 음악의 페이드가 출력보다 깁니다.
• duck_requires_audio_spine: 무음 스파인에 duck_db를 지정했습니다.
• soundtrack_shorter_than_spine은 실패가 아니라 경고입니다. 이 경고는 렌더만 보고할 수 있습니다. 과금되지 않는 plan 사전 검사는 미디어를 내려받지 않으므로 배경 음악의 길이를 알 수 없습니다.