> ## 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.

# ボイス

> ボイスIDを理解し、プリセットボイスライブラリを閲覧して、言語、スタイル、その他のフィルターで検索しましょう。

<Note>
  このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/docs/core-concepts/voices)もあわせてご確認ください。
</Note>

**ボイス**とは、テキストを読み上げるキャラクターのことです。すべてのTTSリクエストでは`voice_id`によって話者を指定します。Supertoneでは、別々のエンドポイントから2種類のボイスを提供しています。

* **プリセットボイス** — Supertoneが設計・提供するボイスです。[Playボイスライブラリ](https://play.supertone.ai)または`GET /v1/voices`から閲覧できます。**このページではプリセットボイスを扱います。**
* **カスタムボイス** — ご自身で作成・管理するボイスクローンです。[カスタムボイス](/ja/docs/core-concepts/custom-voices)をご覧ください。

## ボイスIDを見つける

### Supertone Playからコピーする（最速）

[Supertone Play](https://play.supertone.ai)のボイスライブラリを開き、ボイスカードにカーソルを合わせ、**Copy voice ID**をクリックしてください。IDがクリップボードにコピーされ、すぐにリクエストにペーストできます。

<Frame>
  <img src="https://mintcdn.com/supertone-b89202c8/SA49PlQfJjRe-wAv/images/supertone-play-copy-voice-id-cloned.png?fit=max&auto=format&n=SA49PlQfJjRe-wAv&q=85&s=e461510087e09e7a44233fcb3020f1f8" alt="Supertone PlayからボイスIDをコピー" width="2520" height="1576" data-path="images/supertone-play-copy-voice-id-cloned.png" />
</Frame>

### API経由でボイスを一覧取得する

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    import os
    from supertone import Supertone

    with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
        result = client.voices.list_voices(page_size=20)
        for voice in result.items or []:
            print(voice.voice_id, voice.name, voice.language)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Supertone } from "@supertone/supertone";

    const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });
    const result = await client.voices.listVoices({ pageSize: 20 });

    for (const voice of result.items ?? []) {
      console.log(voice.voiceId, voice.name, voice.language);
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl "https://supertoneapi.com/v1/voices?page_size=20" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"
    ```
  </Tab>
</Tabs>

### フィルターで検索する

`search_voices`を使用すると、言語、スタイル、性別、年齢、用途、モデルでフィルタリングできます。複数の値はカンマ区切りで指定し、OR条件として扱われます。

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    result = client.voices.search_voices(
        language="ko,en",
        style="happy",
        page_size=20,
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    const result = await client.voices.searchVoices({
      language: "ko,en",
      style: "happy",
      pageSize: 20,
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl "https://supertoneapi.com/v1/voices/search?language=ko,en&style=happy&page_size=20" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"
    ```
  </Tab>
</Tabs>

完全なパラメータリストはAPIリファレンスをご覧ください：[ボイス検索](/ja/api-reference/endpoints/search-voices)。

## ボイスオブジェクト

APIが返すボイスは、おおよそ次のような構造になっています。

```json theme={"dark"}
{
  "voice_id": "20160a4c5ba38967330c84",
  "name": "Adam",
  "description": "",
  "age": "young-adult",
  "gender": "male",
  "use_case": "meme",
  "language": ["ko", "en", "ja"],
  "styles": ["neutral"],
  "models": ["sona_speech_1"],
  "samples": [
    {
      "language": "en",
      "style": "neutral",
      "model": "sona_speech_1",
      "url": "https://.../sample.wav"
    }
  ],
  "thumbnail_image_url": "https://.../thumb.png"
}
```

| フィールド      | 意味                                                                  |
| ---------- | ------------------------------------------------------------------- |
| `voice_id` | TTSリクエストに渡す識別子。                                                     |
| `language` | このボイスが対応する言語。リクエストの`language`はこのリスト内の値である必要があります。                   |
| `styles`   | 利用可能な感情スタイル。**先頭の要素がデフォルト**です。                                      |
| `models`   | このボイスで使用可能なモデル。                                                     |
| `samples`  | `(language, style, model)`の組み合わせごとに事前生成されたプレビュー音声 — アプリ内プレビューに便利です。 |

## 重要な制約

* **3つすべてが揃っている必要があります。** TTSの呼び出しを成功させるには、`voice_id`に加えて、そのボイスが実際に対応している`(language, style, model)`の組み合わせが必要です。組み合わせが存在しない場合、APIはエラーを返します。
* **デフォルトスタイル。** `style`を省略した場合は、ボイスの`styles`配列の先頭の値が使用されます。キャラクターごとにデフォルトが異なる可能性があるため、省略する前にボイスオブジェクトをご確認ください。
* **権限。** プリセットボイスはすべてのアカウントで利用可能であり、アクセスはプランによってのみ制限されます。

## 次のステップ

<CardGroup cols={2}>
  <Card title="モデルを選ぶ" icon="layer-group" href="/ja/docs/core-concepts/models">
    ボイスに合った適切なTTSモデルを選びましょう。
  </Card>

  <Card title="カスタムボイス" icon="microphone" href="/ja/docs/core-concepts/custom-voices">
    独自のボイスをクローニングして管理しましょう。
  </Card>
</CardGroup>