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

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

## Step 1 — Clone a voice from a sample

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

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

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

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

## Step 2 — List your custom voices

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

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

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

> **[Create cloned voice](/en/api-reference/endpoints/create-cloned-voice)**
>
> Full upload schema and constraints.

> **[Voices](/en/docs/core-concepts/voices)**
>
> How preset and custom voices fit together.


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