> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 보이스 설정

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

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

`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       | 생성 음성에 포함되는 서브하모닉 진폭의 양을 제어합니다.               |

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

<Tabs>
  <Tab title="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,
        },
    )
    ```
  </Tab>

  <Tab title="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,
        },
      },
    });
    ```
  </Tab>

  <Tab title="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
    ```
  </Tab>
</Tabs>

## 모델별 지원

모든 모델이 모든 설정을 반영하는 것은 아닙니다. 지원되지 않는 설정은 **조용히 무시**되므로, `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 }
```

## 관련 문서

<CardGroup cols={2}>
  <Card title="모델" icon="layer-group" href="/ko/docs/core-concepts/models">
    어떤 모델이 어떤 보이스 설정을 지원하는지 확인하세요.
  </Card>

  <Card title="API 레퍼런스" icon="book-open" href="/ko/api-reference/endpoints/text-to-speech">
    전체 요청 및 응답 스키마입니다.
  </Card>
</CardGroup>