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

# Use a custom voice

> Clone a voice from an audio sample, then use it in TTS calls just like a preset voice.

Custom voices are voice clones tied to your account. Once registered, they behave identically to preset voices — the same `text_to_speech` endpoint, the same parameters, the same response shape.

This example walks through the full flow: upload an audio sample, list your custom voices, generate speech with the new clone.

<Note>
  Voice cloning via the API is not available on the Free tier. Sample audio must be **WAV or MP3 under 3 MB**, and voice names must be **≤ 100 characters**.
</Note>

## Step 1 — Clone a voice from a sample

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

The response includes the new `voice_id`. Save it — that's what you'll pass to TTS calls.

## Step 2 — List your custom voices

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

Use `search_custom_voices` to filter by name or description.

## Step 3 — Generate speech with the new voice

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

Custom voices support the same `voice_settings`, `output_format`, `include_phonemes`, and `normalized_text` fields as preset voices.

## Step 4 — Update or delete

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

## Tips

* **Same-account only.** Cloned voices can only be called by the account that created them. Sharing a `voice_id` with another account returns `403 Forbidden`.
* **Cross-platform.** Voices cloned in [Supertone Play](https://play.supertone.ai) appear in `list_custom_voices` automatically. The opposite is also true — voices cloned via API show up in Play.
* **Sample quality.** Clean, mono, single-speaker audio (5–30 seconds) yields the best clones. Avoid background music, multiple voices, or heavy room noise.
* **Permissions and disclosure.** Make sure you have rights to clone any voice you upload. See your jurisdiction's rules around AI-generated voices and disclosure.

## Related

<CardGroup cols={2}>
  <Card title="Create cloned voice" icon="microphone" href="/en/api-reference/endpoints/create-cloned-voice">
    Full upload schema and constraints.
  </Card>

  <Card title="Voices" icon="users" href="/en/docs/core-concepts/voices">
    How preset and custom voices fit together.
  </Card>
</CardGroup>