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

# カスタムボイスを使う

> オーディオサンプルからボイスをクローンし、プリセットボイスと同じようにTTS呼び出しで使用します。

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

カスタムボイスは、お使いのアカウントに紐づくクローンボイスです。一度登録すれば、プリセットボイスとまったく同じように扱えます — 同じ`text_to_speech`エンドポイント、同じパラメータ、同じレスポンス形式です。

このサンプルでは一連の流れを通して説明します: オーディオサンプルのアップロード、カスタムボイスの一覧取得、新しいクローンを使った音声生成までを実行します。

<Note>
  APIによるボイスクローン作成はFreeプランではご利用いただけません。サンプルオーディオは**WAVまたはMP3で3 MB未満**、ボイス名は**100文字以下**にしてください。
</Note>

## ステップ1 — サンプルからボイスをクローンする

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

    with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
        with open("voice_sample.wav", "rb") as f:
            response = client.custom_voices.create_cloned_voice(
                files={"file_name": "voice_sample.wav", "content": f.read()},
                name="Hana — narrator voice",
                description="Calm, mid-pitch female voice for audiobook narration.",
            )

        print("Created custom voice:", response.voice_id)
    ```
  </Tab>

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

    const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });

    const audio = fs.readFileSync("voice_sample.wav");

    const response = await client.customVoices.createClonedVoice({
      files: {
        fileName: "voice_sample.wav",
        content: audio,
      },
      name: "Hana — narrator voice",
      description: "Calm, mid-pitch female voice for audiobook narration.",
    });

    console.log("Created custom voice:", response.voiceId);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl -X POST "https://supertoneapi.com/v1/custom-voices/cloned-voice" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY" \
      -F "files=@voice_sample.wav" \
      -F "name=Hana — narrator voice" \
      -F "description=Calm, mid-pitch female voice for audiobook narration."
    ```
  </Tab>
</Tabs>

レスポンスには新しい`voice_id`が含まれます。これを保存しておいてください — 以降のTTS呼び出しで渡す値です。

## ステップ2 — カスタムボイスを一覧表示する

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    result = client.custom_voices.list_custom_voices(page_size=20)
    for voice in result.items or []:
        print(voice.voice_id, voice.name, voice.description)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    const result = await client.customVoices.listCustomVoices({ pageSize: 20 });
    for (const voice of result.items ?? []) {
      console.log(voice.voiceId, voice.name, voice.description);
    }
    ```
  </Tab>
</Tabs>

名前や説明でフィルタリングしたい場合は`search_custom_voices`を使用してください。

## ステップ3 — 新しいボイスで音声を生成する

```python theme={"dark"}
response = client.text_to_speech.create_speech(
    voice_id=NEW_VOICE_ID,
    text="The first chapter begins on a quiet rainy morning.",
    language="en",
    model="sona_speech_2",
)

with open("speech.wav", "wb") as f:
    f.write(response.result.read())
```

カスタムボイスは、プリセットボイスと同じ`voice_settings`、`output_format`、`include_phonemes`、`normalized_text`の各フィールドをサポートします。

## ステップ4 — 更新または削除する

```python theme={"dark"}
# Rename or update the description
client.custom_voices.edit_custom_voice(
    voice_id=NEW_VOICE_ID,
    name="Hana — narrator (v2)",
    description="Improved take with cleaner room tone.",
)

# Permanently delete
client.custom_voices.delete_custom_voice(voice_id=NEW_VOICE_ID)
```

## ヒント

* **同一アカウントのみで利用可能です。** クローンボイスは、そのボイスを作成したアカウントからのみ呼び出せます。別アカウントと`voice_id`を共有しても`403 Forbidden`が返ります。
* **プラットフォーム間で共有されます。** [Supertone Play](https://play.supertone.ai)でクローンしたボイスは、自動的に`list_custom_voices`に表示されます。逆も同じで、API経由でクローンしたボイスはPlayでも表示されます。
* **サンプル品質。** クリーンなモノラル、単一話者のオーディオ（5〜30秒程度）が最も良いクローン結果を生み出します。BGM、複数話者の混在、強い室内ノイズは避けてください。
* **権利と開示。** アップロードするボイスをクローンする権利を持っているか必ず確認してください。AI生成音声と開示に関する各管轄区域のルールも確認しましょう。

## 関連情報

<CardGroup cols={2}>
  <Card title="クローンボイスの作成" icon="microphone" href="/ja/api-reference/endpoints/create-cloned-voice">
    アップロードの完全なスキーマと制約を確認できます。
  </Card>

  <Card title="ボイス" icon="users" href="/ja/docs/core-concepts/voices">
    プリセットボイスとカスタムボイスがどう組み合わさるかを解説します。
  </Card>
</CardGroup>