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

# カスタムボイス

> ご自身のアカウントに登録・管理するボイスクローン — 作成、一覧、検索、更新、削除について。

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

**カスタムボイス**とは、アカウントに紐付くボイスクローンのことです。一度登録すれば、プリセットボイスとまったく同じように動作します。同じTTSエンドポイント、同じパラメータが使えますが、専用のエンドポイント群を介して扱われ、作成元のアカウントからのみ呼び出すことができます。

カスタムボイスは、2つの方法で作成できます。

* **[Supertone Play](https://play.supertone.ai)で作成** — サンプルをアップロードし、UIからクローニングします。
* **API経由で作成** — オーディオファイルを添えて`POST /v1/custom-voices/cloned-voice`を呼び出します。

どちらの方法でも同じ種類のボイスが生成されます。Playで作成したクローンボイスは`list_custom_voices`に表示され、API経由で作成したボイスはPlayにも表示されます。同期処理は不要です。

<Note>
  **API経由**のボイスクローニングは、Freeプランではご利用いただけません。Play上でのクローニングは、すべての有料プランで利用可能です。
</Note>

## エンドポイント概要

| エンドポイント                               | 目的                                 |
| ------------------------------------- | ---------------------------------- |
| `POST /v1/custom-voices/cloned-voice` | アップロードされたオーディオサンプルから新しいクローンを作成します。 |
| `GET /v1/custom-voices`               | アカウント上のすべてのカスタムボイスを一覧取得します。        |
| `GET /v1/custom-voices/search`        | 名前や説明でカスタムボイスをフィルタリングします。          |
| `GET /v1/custom-voices/{voice_id}`    | 単一のカスタムボイスを取得します。                  |
| `PATCH /v1/custom-voices/{voice_id}`  | 名前または説明を更新します。                     |
| `DELETE /v1/custom-voices/{voice_id}` | カスタムボイスを完全に削除します。                  |

## クローンを作成する

クローニングしたいボイスの、ノイズの少ないオーディオサンプルをアップロードします。

<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呼び出しに渡す値となりますので、保存しておいてください。

### アップロードの制約

* **形式：** WAVまたはMP3
* **サイズ：** 3 MB未満
* **名前：** 最大100文字

クリーンでモノラルかつ単一話者のオーディオ（5〜30秒）が最も良いクローン結果につながります。BGM、複数話者、強いルームノイズは避けてください。

## 一覧と検索

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

    # Search by name or description
    result = client.custom_voices.search_custom_voices(name="narrator")
    ```
  </Tab>

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

    // Search by name or description
    const search = await client.customVoices.searchCustomVoices({ name: "narrator" });
    ```
  </Tab>

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

    # Search
    curl "https://supertoneapi.com/v1/custom-voices/search?name=narrator" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"
    ```
  </Tab>
</Tabs>

## TTSでカスタムボイスを使用する

クローンが登録されたら、プリセットボイスとまったく同じ要領で`text_to_speech.create_speech`を呼び出してください。カスタムの`voice_id`を渡すだけです。

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

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

## 更新と削除

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

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

```typescript theme={"dark"}
// Rename / update description
await client.customVoices.editCustomVoice({
  voiceId: CUSTOM_VOICE_ID,
  name: "Hana — narrator (v2)",
  description: "Improved take with cleaner room tone.",
});

// Permanently delete
await client.customVoices.deleteCustomVoice({ voiceId: CUSTOM_VOICE_ID });
```

## 重要な制約

* **アカウントスコープ。** カスタムボイスは作成元のアカウントからのみ呼び出せます。IDを知っていても、他人のカスタムボイスを呼び出すと`403 Forbidden`が返ります。
* **クレジット消費は同じ。** カスタムボイスの呼び出しは、プリセットボイスと同じレートでクレジットを消費します。
* **権限と開示。** アップロードするボイスをクローニングする権利を必ずお持ちであることをご確認ください。お使いの地域でのAI生成音声およびエンドユーザーへの開示に関する規則も併せてご確認ください。

## 関連項目

<CardGroup cols={2}>
  <Card title="プリセットボイス" icon="users" href="/ja/docs/core-concepts/voices">
    Supertoneのプリセットボイスライブラリを閲覧・検索しましょう。
  </Card>

  <Card title="エンドツーエンドの例" icon="lightbulb" href="/ja/docs/examples/custom-voice-tts">
    カスタムボイスのクローニング、一覧取得、TTSでの利用までを通して試します。
  </Card>

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

  <Card title="コストと使用量" icon="credit-card" href="/ja/docs/production/cost-and-usage">
    コストを見積もり、ボイスごとの使用量を監視しましょう。
  </Card>
</CardGroup>