> ## 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       | 半音単位のピッチシフトです。±12 で 1 オクターブ分にあたります。    |
| `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 オクターブ上がります。自然な調整には小さい値（±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="/ja/docs/core-concepts/models">
    どのモデルがどの Voice settings に対応しているかを確認します。
  </Card>

  <Card title="API リファレンス" icon="book-open" href="/ja/api-reference/endpoints/text-to-speech">
    リクエストとレスポンスの完全なスキーマ。
  </Card>
</CardGroup>