보이스 설정

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.

voice_settings는 모든 TTS 요청에서 선택적으로 사용할 수 있는 객체로, 오디오가 어떻게 전달되는지를 조정합니다. 피치, 억양, 속도, 그리고 플래그십 모델용 고급 파라미터를 다룹니다.

빠른 레퍼런스

Setting	Range	Default	What it does
`pitch_shift`	-24 → 24	0	반음(semitone) 단위의 피치 이동입니다. ±12는 한 옥타브에 해당합니다.
`pitch_variance`	0 → 2	1	피치 변동 정도입니다. 낮을수록 평탄해지고, 높을수록 표현이 풍부해집니다.
`speed`	0.5 → 2	1	재생 속도 배수입니다. `duration` 이후에 적용됩니다.
`duration`	0 → 60	0	생성된 오디오를 목표 길이(초)에 맞춥니다(0 = 목표 없음).
`similarity`	1 → 5	3	생성 음성이 원본 캐릭터 보이스와 얼마나 유사한지 제어합니다.
`text_guidance`	0 → 4	1	텍스트 내용에 따라 발화 특성이 얼마나 민감하게 적응할지 제어합니다.
`subharmonic_amplitude_control`	0 → 2	1	생성 음성에 포함되는 서브하모닉 진폭의 양을 제어합니다.

보이스 파라미터 설정하기

Python
TypeScript
cURL

VOICE_ID = "20160a4c5ba38967330c84"  # replace with your voice ID

response = client.text_to_speech.create_speech(
    voice_id=VOICE_ID,
    text="Let me tell you a story.",
    language="en",
    model="sona_speech_1",
    voice_settings={
        "pitch_shift": 2,
        "pitch_variance": 1.3,
        "speed": 0.95,
    },
)

const VOICE_ID = "20160a4c5ba38967330c84"; // replace with your voice ID

const response = await client.textToSpeech.createSpeech({
  voiceId: VOICE_ID,
  apiConvertTextToSpeechUsingCharacterRequest: {
    text: "Let me tell you a story.",
    language: "en",
    model: "sona_speech_1",
    voiceSettings: {
      pitchShift: 2,
      pitchVariance: 1.3,
      speed: 0.95,
    },
  },
});

VOICE_ID="20160a4c5ba38967330c84"

curl -X POST "https://supertoneapi.com/v1/text-to-speech/$VOICE_ID" \
  -H "x-sup-api-key: $SUPERTONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Let me tell you a story.",
    "language": "en",
    "model": "sona_speech_1",
    "voice_settings": {
      "pitch_shift": 2,
      "pitch_variance": 1.3,
      "speed": 0.95
    }
  }' \
  --output speech.wav

모델별 지원

모든 모델이 모든 설정을 반영하는 것은 아닙니다. 지원되지 않는 설정은 조용히 무시되므로, supertonic_api_3에 subharmonic_amplitude_control 값을 전달해도 오류는 발생하지 않습니다. 다만 출력에 반영되지 않을 뿐입니다.

Setting	`sona_speech_2`	`sona_speech_2_flash`	`supertonic_api_3`	`supertonic_api_1`	`sona_speech_1`
`pitch_shift`	✅	✅	—	—	✅
`pitch_variance`	✅	✅	—	—	✅
`speed`	✅	✅	✅	✅	✅
`duration`	✅	✅	—	—	✅
`similarity`	✅	—	—	—	✅
`text_guidance`	✅	—	—	—	✅
`subharmonic_amplitude_control`	—	—	—	—	✅

파라미터 간 상호작용

pitch_shift는 반음 단위입니다. +12는 보이스를 한 옥타브 높입니다. 자연스러운 조정을 위해서는 작은 값(±1~±4)을 사용해 주십시오. 값이 커질수록 로봇 같은 소리가 납니다.
pitch_variance는 표현력을 제어합니다. 0으로 설정하면 단조롭게(설명형, 뉴스 낭독 스타일에 적합), 최대 2로 설정하면 매우 표현이 풍부한 발화가 됩니다.
duration 적용 후 speed. 둘 다 설정된 경우, 엔진은 먼저 duration초를 목표로 한 뒤 speed를 배수로 적용합니다. duration=5에 speed=2를 설정하면 약 10초 분량의 오디오가 생성됩니다.
**similarity와 text_guidance**는 클론드 보이스 및 sona_speech_2 / sona_speech_1에서 가장 유용합니다. similarity가 높을수록 소스 보이스를 더 엄격하게 따르며, text_guidance가 높을수록 텍스트의 감정 톤에 맞춰 발화가 변화합니다.

레시피

차분하고 느린 내레이션:

{ "pitch_variance": 0.7, "speed": 0.9 }

들뜨고 빠른 발화:

{ "pitch_shift": 1, "pitch_variance": 1.5, "speed": 1.15 }

목표 클립 길이에 맞추기(예: 6초짜리 장면 더빙):

{ "duration": 6 }

모델

어떤 모델이 어떤 보이스 설정을 지원하는지 확인하세요.

API 레퍼런스

전체 요청 및 응답 스키마입니다.

시작하기

핵심 개념

Text-to-Speech

SDK

예제

프로덕션 운영

리소스

빠른 레퍼런스

보이스 파라미터 설정하기

모델별 지원

파라미터 간 상호작용

레시피

관련 문서

모델

API 레퍼런스

시작하기

핵심 개념

Text-to-Speech

SDK

예제

프로덕션 운영

리소스

Documentation Index

​빠른 레퍼런스

​보이스 파라미터 설정하기

​모델별 지원

​파라미터 간 상호작용

​레시피

​관련 문서

모델

API 레퍼런스

빠른 레퍼런스

보이스 파라미터 설정하기

모델별 지원

파라미터 간 상호작용

레시피

관련 문서