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

# ボイス

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

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

**ボイス**とは、テキストを読み上げるキャラクターのことです。すべての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がクリップボードにコピーされ、すぐにリクエストにペーストできます。

![Supertone PlayからボイスIDをコピー](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)

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

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

**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);
}
```

**cURL**

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

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

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

**Python**

```python theme={"dark"}
result = client.voices.search_voices(
    language="ko,en",
    style="happy",
    page_size=20,
)
```

**TypeScript**

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

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

完全なパラメータリストは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`配列の先頭の値が使用されます。キャラクターごとにデフォルトが異なる可能性があるため、省略する前にボイスオブジェクトをご確認ください。
* **権限。** プリセットボイスはすべてのアカウントで利用可能であり、アクセスはプランによってのみ制限されます。

## 次のステップ

> **[モデルを選ぶ](/ja/docs/core-concepts/models)**
>
> ボイスに合った適切なTTSモデルを選びましょう。

> **[カスタムボイス](/ja/docs/core-concepts/custom-voices)**
>
> 独自のボイスをクローニングして管理しましょう。


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