Use a custom voice - Supertone API Documentation

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.

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

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)

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

result = client.custom_voices.list_custom_voices(page_size=20)
for voice in result.items or []:
    print(voice.voice_id, voice.name, voice.description)

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

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

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

Create cloned voice

Full upload schema and constraints.

Voices

How preset and custom voices fit together.

​Step 1 — Clone a voice from a sample

​Step 2 — List your custom voices

​Step 3 — Generate speech with the new voice

​Step 4 — Update or delete

​Tips

​Related

Create cloned voice

Voices

Step 1 — Clone a voice from a sample

Step 2 — List your custom voices

Step 3 — Generate speech with the new voice

Step 4 — Update or delete

Tips

Related