텍스트 음성 변환(TTS) API: 아바타 목소리로 음성 생성하기

Sume API로 텍스트를 음성으로 변환하려면 최대 20,000자의 transcript와 음성을 담아 POST /v1/tts-1.0/generate를 보내세요. 음성은 목소리가 준비된 아바타의 avatar_id나 avatar_handle, 또는 voice.id로 지정합니다. TTS 1.0은 Job으로 실행되며, 오디오를 Sume에 호스팅된 파일로 반환하고 단어별 타임스탬프와 문장별 클립도 선택적으로 제공합니다.

세부 내용은 Sume API 레퍼런스의 TTS 요청 스키마에서 가져왔으며, 2026-09-26에 확인했습니다. 이 레퍼런스는 API 레퍼런스 문서의 바탕이 되는 OpenAPI 문서입니다. 가격은 API 요금 페이지를 만드는 코드에서 읽었습니다. 스크립트로 완성된 말하는 영상을 만들려면 대신 말하는 아바타 영상 API를 쓰세요.

음성은 어떻게 고르나요?

찾아서 쓸 수 있는 음성은 아바타의 음성입니다. GET /v1/avatar-1.0/avatars는 내 아바타 목록을 반환하며, 각 요약에는 processing, ready, failed 중 하나인 voice.status가 들어 있습니다(음성이 없는 아바타는 voice가 null입니다). 준비된 아바타의 avatar_id나 avatar_handle을 voice 안이 아니라 본문 최상위에 넣으면, Sume가 제출 시점에 그 아바타의 음성을 찾아 적용합니다. 아바타를 만드는 방법은 재사용 가능한 AI 아바타 만들기에서 다룹니다.

이미 Sume 음성 ID가 있다면 voice.id로 보내세요. 음성 UUID나 Voices 라이브러리 ID(voi_ 뒤에 hex 문자 32개)를 넣습니다. 다른 형식은 Job이 큐에 들어가거나 크레딧이 예약되기 전에 400과 invalid_voice_id로 실패합니다. 아바타와 voice.id를 함께 보내면 둘이 일치해야 하며, 그렇지 않으면 요청이 400으로 실패합니다.

텍스트 음성 변환 요청은 어떤 형태인가요?

아래 요청은 준비된 아바타의 목소리로 한 줄을 읽어 44,100 Hz pcm_s16le wav로 만들며, 단어별 타이밍과 문장마다 오디오 조각 하나씩을 함께 받습니다.

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: tts-welcome-001" \
  -d '{
    "transcript": "Welcome back. Today we test the new travel mug.",
    "avatar_handle": "product_host",
    "language": "en",
    "output_format": { "container": "wav", "encoding": "pcm_s16le", "sample_rate": 44100 },
    "timestamps": { "words": true },
    "segmentation": { "mode": "sentence" }
  }'

어떤 필드로 오디오를 조정하나요?

transcript와 음성 선택 필드 하나가 최소 요건입니다. 나머지는 모두 선택 사항입니다.

단어별 타임스탬프와 문장별 오디오는 어떻게 받나요?

옵션 두 개를 쓰면 한 번의 합성 결과를 자막을 달거나 자를 수 있도록 타이밍이 붙은 조각으로 나눌 수 있습니다. Sume 미디어 호스트에 있는 문장 클립은 스틸 이미지 립싱크에 넣는 audio_url로도 흔히 쓰입니다.

• timestamps: { "words": true }는 완료된 Job 결과에 words[]를 추가합니다. 시작과 끝이 초 단위로 표시된, 단조 증가하는 단어별 타이밍입니다.
• segmentation: { "mode": "sentence" }는 timestamps.words: true가 있어야 하며, 빈틈없는 segments[]를 반환합니다. 각 세그먼트는 다음 세그먼트가 시작하는 지점에서 정확히 끝납니다. v1에서 모드는 sentence 하나뿐입니다.
• boundary_lead_ms(0–500, 기본값 70)는 문장의 마지막 단어에서 그만큼의 밀리초 뒤에 컷을 둡니다. 그 뒤의 쉼은 다음 세그먼트가 흡수합니다.
• emit_audio(기본값 true)가 켜져 있고 wav나 raw 컨테이너를 쓰면 각 세그먼트에 샘플 단위까지 정확한 audio_url이 붙습니다. mp3에서는 세그먼트별 오디오 없이 타이밍만 받습니다.

언제 TTS Router를 대신 써야 하나요?

TTS 1.0에는 엔진 선택 기능이 없으며, 본문에 model이나 model_id를 넣으면 400으로 거부됩니다. 엔진을 고르려면 필수 필드 model을 담아 POST /v1/tts-router/generate를 호출하세요. 쓸 수 있는 값은 sonic-3.6, sonic-3.5, sonic-3, sonic-latest, sonic-preview입니다. 음성 선택, 대본 규칙, 과금은 TTS 1.0과 같습니다. job.model에는 보낸 ID가 그대로 담기며, 알 수 없는 ID는 400 model_not_found로 실패합니다.

GET /v1/tts-router/models는 이 ID들을 모델별 capabilities(text_to_speech, max_characters), pricing, constraints와 함께 나열합니다. sonic-preview 항목의 제약 조건은 이 모델을 공급사의 베타 채널로 표시하며, 베타 채널의 출력과 가용성은 예고 없이 바뀔 수 있습니다. GET /v1/tts-router/models/{model_id}는 모델 하나를 반환하고, 모르는 ID에는 404를 반환합니다.

제한은 무엇이고, 비용은 얼마인가요?

TTS 1.0의 요금은 1,000자당 $0.0475이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. TTS Router도 같은 방식으로 과금합니다. 사용량은 공백과 문장 부호를 포함한 대본 글자 수로 매겨지므로, 20,000자를 꽉 채운 대본은 수수료 전 $0.95입니다.

• 합성된 오디오가 1,200초를 넘으면 tts_duration_exceeded로 실패하며, 크레딧은 확정되지 않습니다.
• 영어가 아닌 대본에는 항상 language를 지정하세요. 생략하면 영어가 기본값이며, 보조 수단으로 한글로만 된 대본은 한국어로, 가나로만 된 대본은 일본어로 추론합니다.
• 이 경로는 스트리밍 방식이 아닙니다. sync와 subscribe는 최대 30초 동안 대기하며, result_ready가 true가 될 때까지 /result는 409 job_not_completed를 반환합니다.
• 최상위 speed enum(slow, normal, fast)은 지원 중단되었습니다. generation_config.speed를 쓰세요.