> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 보이스 설정

> `voice_settings` 필드로 피치, 억양, 속도를 비롯한 발화 파라미터를 세밀하게 조정합니다.

> [!NOTE]
>
> 이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/text-to-speech/voice-settings)을 함께 확인해 주세요.

`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**

```python theme={"dark"}
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,
    },
)
```

**TypeScript**

```typescript theme={"dark"}
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,
    },
  },
});
```

**cURL**

```bash theme={"dark"}
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`가 높을수록 텍스트의 감정 톤에 맞춰 발화가 변화합니다.

## 레시피

**차분하고 느린 내레이션:**

```json theme={"dark"}
{ "pitch_variance": 0.7, "speed": 0.9 }
```

**들뜨고 빠른 발화:**

```json theme={"dark"}
{ "pitch_shift": 1, "pitch_variance": 1.5, "speed": 1.15 }
```

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

```json theme={"dark"}
{ "duration": 6 }
```

## 관련 문서

> **[모델](/ko/docs/core-concepts/models)**
>
> 어떤 모델이 어떤 보이스 설정을 지원하는지 확인하세요.

> **[API 레퍼런스](/ko/api-reference/endpoints/text-to-speech)**
>
> 전체 요청 및 응답 스키마입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.