Supertone API를 통해 텍스트를 음성으로 변환하려면 특정 보이스 ID와 함께 텍스트, 언어, 스타일 등의 정보를 API로 전달해야 합니다. 이 문서는 Text-to-Speech 기능의 전체 호출 구조와 파라미터 설정 방법, 응답 형태, 음성 조정 옵션까지 단계별로 안내합니다.

​
1. 호출 엔드포인트와 기본 구조

POST /v1/text-to-speech/{voice_id}

​
필수 헤더

x-sup-api-key: [YOUR_API_KEY]
Content-Type: application/json

​
경로 파라미터

  • voice_id: 사용할 보이스의 고유 ID

​
쿼리 파라미터

  • output_format (선택): 생성할 오디오 형식. wav(기본값), mp3 중 선택 가능

​
2. 요청 본문

요청은 JSON 형식으로 전달되며, 다음 필드를 포함할 수 있습니다.
필드필수 여부설명
text✅음성으로 변환할 텍스트 (최대 300자)
language✅텍스트의 언어. 보이스가 지원하는 언어 내에서 선택 (ko, en, ja)
style❌적용할 감정 스타일 (neutral, happy 등). 미입력 시 디폴트 스타일 사용, 가장 앞에 오는 값이 디폴트 스타일
model❌사용할 음성 모델 (sona_speech_1). 생략 시 자동 적용
voice_settings❌음성의 높낮이, 억양, 속도를 조절하는 고급 옵션 (아래 참고)

​
3. 전체 요청 예시

POST /v1/text-to-speech/91992bbd4758bdcf9c9b01?output_format=mp3
x-sup-api-key: [YOUR_API_KEY]
Content-Type: application/json

{
  "text": "안녕하세요, 수퍼톤 API입니다.",
  "language": "ko",
  "style": "neutral",
  "model": "sona_speech_1",
  "voice_settings": {
    "pitch_shift": 0,
    "pitch_variance": 1,
    "speed": 1
  }
}

​
4. voice_settings 선택

voice_settings는 생성되는 음성의 발화 느낌을 미세하게 조정하고 싶을 때 사용할 수 있는 고급 옵션입니다.
파라미터설명허용 범위기본값
pitch_shift음정의 높낮이를 조정합니다.
0은 원래 보이스의 음정이며, ±12단계까지 가능합니다. 1단계는 반음입니다.		-12 ~ +120
pitch_variance발화 중 억양의 변화 정도를 조절합니다.
작을수록 평탄한 억양, 클수록 풍부한 억양을 생성합니다.		0.1 ~ 21
speed발화 속도를 조절합니다.
1보다 작으면 느려지고, 크면 빨라집니다.		0.5 ~ 21

​
5. 응답

성공 시 오디오 스트림(audio/wav 또는 audio/mpeg)으로 응답됩니다.
오디오 길이는 헤더를 통해 확인할 수 있습니다. 
X-Audio-Length: 3.42
위 예시는 3.42초 분량의 음성이 생성되었음을 의미합니다.

​
6. 입력 텍스트에 대한 주의사항

  • 텍스트는 최대 300자까지 입력할 수 있습니다.
  • 너무 짧은 문장은 발화가 부자연스러울 수 있습니다.
  • 한글, 영어, 일본어만 지원되며, 이 외 언어는 예기치 않은 결과가 발생할 수 있습니다.
  • 이모지, 특수 기호 등은 음성으로 읽히지 않거나 무시됩니다.

​
7. 모델 선택

현재 지원하는 모델은 sona_speech_1 하나입니다.
이 파라미터는 선택 사항이며, 미입력 시 기본 모델이 자동으로 적용됩니다.

​
8. Predict Duration API로 발화 길이를 먼저 확인하기

음성 생성 없이도, 입력 텍스트가 몇 초 분량의 발화를 유도할지 예측할 수 있습니다. 
POST /v1/predict-duration/{voice_id}
  • 요청 방식은 TTS와 동일
  • 응답 예시:
{
  "duration": 2.87
}
이 API는 크레딧을 차감하지 않습니다. 사용량 예측이나 미리보기 UI 구현 시 유용하게 활용할 수 있습니다.

​
9. Stream Text-to-Speech

AI 챗봇·캐릭터 챗과 같이 실시간성이 중요한 서비스를 위한 스트리밍 TTS 입니다. 스트리밍 TTS를 사용하면 텍스트 전체의 음성 생성이 완료될 때까지 기다리지 않고, 빠르게 생성된 음성을 받을 수 있습니다. 자세한 사용 방법은 아래 가이드를 참고하시기 바랍니다.