API로 영상 보이스오버 번역하기: STT, TTS, Timeline

Sume API로 영상의 보이스오버를 번역하려면 POST /v1/video-inspect로 원래 음성을 전사하고, 대사를 직접 또는 Agent Completions로 번역한 뒤, POST /v1/tts-1.0/generate와 그 language 필드로 번역문을 음성으로 만들고, POST /v1/timeline-1.0/render로 새 오디오 위에 영상을 렌더링하세요. TTS는 보낸 transcript를 그대로 읽으므로 번역은 여러분의 몫이며, 화자의 입술은 새 음성에 맞춰 움직이지 않습니다.

아래 내용은 2026-09-27에 확인한 Sume의 영상 검사, Timeline 1.0, Agent Completions, Models 개요 (영문) 문서와 Sume API 레퍼런스의 TTS 스키마를 바탕으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 음성 대신 자막을 번역하려면 영상 자막 번역 API를 참고하세요.

원래 대사와 타이밍은 어떻게 받나요?

POST /v1/video-inspect로 한 번 전사하세요. transcribe: true, segmentation: { "mode": "sentence" }, 그리고 힌트로 language_code를 보냅니다. segments[]의 각 문장에는 index, text, 초 단위의 start와 end가 있습니다. 모든 start를 보관하세요. 렌더에서 그 문장의 source_in이 되기 때문입니다. 영상은 앞서 실행한 Sume Job의 출력처럼 이미 워크스페이스의 media.sume.com에 있어야 합니다.

텍스트는 누가 번역하나요?

여러분이 직접 하거나, 여러분이 시작한 Sume 에이전트 실행이 합니다. 번역 도구에는 문장 텍스트만 보내고, 각 start와 end는 직접 작성한 코드에 보관한 뒤, 줄 수가 여전히 맞는지 확인하세요.

Sume 안에서 처리하려면 대사를 input으로 담고 번역된 줄을 받을 output_schema를 붙여 POST /v1/agent/completions로 보내세요. 이 요청은 영상 자막 번역 API에 나와 있습니다. 음성 합성 비용을 내기 전에 번역된 줄을 검토하세요.

번역문은 어떻게 음성으로 만드나요?

번역된 줄을 최대 20,000자의 transcript 하나로 묶어, 음성과 목표 language와 함께 보내세요. 음성은 목소리가 준비된 아바타의 avatar_id나 avatar_handle, 또는 voice.id로 지정합니다. 영어가 아닌 대본에는 항상 language를 지정하세요. 생략하면 영어가 기본값이며, 보조 수단으로 한글로만 된 대본은 한국어로, 가나로만 된 대본은 일본어로 추론합니다. timestamps.words: true와 segmentation.mode: "sentence"를 함께 주면 새 타이밍이 담긴 갭 없는 문장 segments[]를 반환합니다.

현재 코드에서는 language: "ko"인데 대본에 한글 음절이 하나도 없으면 400 tts_language_script_mismatch로 거부됩니다. 번역되지 않은 대본을 이 단계에서 걸러 낼 수 있습니다.

curl -X POST https://api.sume.com/v1/tts-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dub-ko-001" \
  -d '{
    "transcript": "오늘은 새 대시보드를 소개합니다. 설정은 1분이면 끝납니다.",
    "avatar_handle": "product_host",
    "language": "ko",
    "output_format": { "container": "wav", "encoding": "pcm_s16le", "sample_rate": 44100 },
    "timestamps": { "words": true },
    "segmentation": { "mode": "sentence" }
  }'

음성의 언어가 다르면 어떻게 되나요?

현재 코드에서 TTS는 Sume에 음성의 주 언어가 기록되어 있으면 이를 요청 언어와 비교합니다. 요청 언어는 보낸 language이고, 없으면 대본에서 추론한 ko나 ja, 그것도 아니면 en입니다. 둘이 다르면 제출은 409와 error.code tts_voice_language_mismatch로 실패합니다. error.details에는 voice_language와 request_language가 담기고, 메시지는 발음이 부자연스럽게 들릴 수 있다고 경고합니다. 이 시점에는 Job도 요금도 생기지 않은 상태입니다.

사용자가 확인하면 같은 요청과 같은 Idempotency-Key에 confirm_language_mismatch: true를 더해 다시 보내세요. API 레퍼런스에 따르면 확인한다고 해서 요청한 음성이나 언어가 바뀌지는 않습니다. 기록된 언어가 없는 음성은 검사하지 않습니다.

새 음성은 영상에 어떻게 입히나요?

새 오디오 위에 원본 영상을 렌더링하세요. audio.url은 Job 결과에 나온 TTS 파일의 media.sume.com URL이고, audio.duration_seconds는 그 길이입니다. 현재 코드는 timestamps.words가 켜져 있으면 이 길이를 결과의 duration_seconds로 알려 줍니다. 화면이 새 타이밍을 따라가도록 문장마다 video[] 슬롯을 하나씩 주세요.

• source_url은 원본 영상이고, source_in은 원래 문장의 start입니다.
• start와 duration은 번역된 문장의 TTS 세그먼트에서 가져옵니다. 현재 코드에서 첫 세그먼트는 0에서 시작하므로, video[0].start가 0이어야 한다는 조건에 맞습니다.
• transition은 빼고, output.width와 output.height를 소스 크기에 맞추세요(기본값은 1080×1920). 슬롯 상한이 200개이므로 렌더 한 번에 문장은 최대 200개라는 점도 기억하세요.
• 현재 컴파일러에서 렌더는 스파인과 선택적인 soundtrack만 재생하므로, 원래 음성과 그 아래에 깔린 음악은 모두 사라집니다. Sume에 호스팅된 배경음이 있다면 soundtrack으로 넣으세요.
• 새 음성은 누구의 입술도 움직이지 않습니다. Sume의 모델 문서에 따르면 영상 모델은 나중에 입힌 보이스오버에 맞춰 립싱크하지 않습니다. 카메라에 나오는 화자라면 스틸과 오디오로 말하는 클립을 만드는 VEED Fabric 1.0으로 새 말하는 샷을 만드세요. 이 모델의 audio_url은 Sume에 호스팅된 최대 10 MB 오디오를 받으며 보통 TTS 세그먼트를 넣고, wav 컨테이너를 쓰면 TTS 세그먼트마다 자체 audio_url이 붙습니다. 립싱크 API를 참고하세요.

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: dub-ko-render-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/tts-ko.wav", "duration_seconds": 7.4 },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4", "start": 0, "duration": 3.9, "source_in": 0 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4", "start": 3.9, "duration": 3.5, "source_in": 3.2 }
    ]
  }'

비용은 얼마이고, 한도는 어떻게 되나요?

각 단계는 따로 과금되며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 합성된 오디오가 1,200초를 넘으면 tts_duration_exceeded로 실패하며, 크레딧은 확정되지 않습니다.