Skip to main content

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.

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

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)
The response includes the new voice_id. Save it — that’s what you’ll pass to TTS calls.

​
Step 2 — List your custom voices

result = client.custom_voices.list_custom_voices(page_size=20)
for voice in result.items or []:
    print(voice.voice_id, 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.