Voice cloning

Overview

Voice cloning lets you create a custom voice from a short reference clip and then use it anywhere a built-in voice name is accepted. Like the built-in voices, a cloned voice works across all 60+ supported languages and keeps a consistent identity when switching languages.

The lifecycle of a cloned voice is:

1. Create the voice by uploading a short reference audio clip.
2. Wait for Soniox to process it. Processing is asynchronous and per model.
3. Use the voice in Text-to-Speech requests by its voice ID.
4. Recompute the voice when a new Text-to-Speech model is released, to make it usable with that model.

Create a voice

The easiest way to create and manage voices is in the Soniox Console:

1. Open your project and go to Voices.
2. Click Create voice and upload a reference clip.
3. Give the voice a name (unique within the project) and confirm.

The voice appears in the list right away and begins processing in the background.

You can also create a voice programmatically with the voice API, see Manage voices with the API.

Reference clip requirements

• Keep it short, up to 20 seconds. Longer clips are accepted at upload but fail during processing with voice_audio_too_long.
• Use clean audio. A clear recording of a single speaker with little background noise gives the best results. Unsupported or corrupted files fail with voice_invalid_audio.
• Keep the audio consistent. The AI mimics everything it hears: the speaking speed, inflections, accent, tonality, breathing pattern and strength, as well as any noise and mouth clicks. Keep the tone, performance, and audio quality consistent throughout the clip. Highly dynamic audio, with wide fluctuations in pitch and volume, yields less predictable results.
• Stay within 10 MB. Larger uploads are rejected.
• Names are unique per project. Reusing a name is rejected; pick a different name or delete the existing voice first.

Wait for the voice to be ready

Creating a voice only uploads the clip; Soniox then processes it before you can use it, which typically completes within seconds.

In the Soniox Console, a voice is ready as soon as you can play it. A voice that failed to process instead shows a grayed-out play button with an error message; fix the reference clip and create a new voice.

Use a cloned voice

Once the voice is ready for the model you are using, reference it by its voice ID in the voice field, exactly where you would otherwise pass a built-in voice name. This works for both the real-time WebSocket API and the REST API:

{
  "model": "tts-rt-v1",
  "language": "en",
  "voice": "21b9c8e2-1c3a-4d5e-9f8a-123456789abc"
}

Soniox detects that the voice value is a UUID and resolves it to your cloned voice; a non-UUID value is treated as a built-in voice name.

If the voice is not usable when the request starts, it fails with voice_not_found, voice_not_ready, voice_not_prepared, or voice_failed. See the Errors reference for details.

Prepare a voice for a new model

A voice is processed for the Text-to-Speech models that exist at the time it is created. When a new model is later released, your existing voices are not prepared for it automatically and report not_computed for that model.

To make an existing voice usable with a newly released model, recompute it via the API. Recompute only processes models the voice is not already prepared for; models that are already ready, and models that previously failed, are left unchanged. A failed voice is terminal and recompute does not recover it, so fix the reference clip and create a new voice instead.

Manage voices with the API

If you need to create and manage voices programmatically, the voice API lets you create, list, retrieve, recompute, and delete voices. See the API reference for the endpoints, request and response formats, and code examples.

Limits

Voice management is subject to per-project and per-organization limits:

• Reference clip size up to 10 MB per upload.
• Number of voices up to 20 per organization, counted across all projects. Each reference clip counts as one voice; preparing a voice for more models does not count against this limit.

Exceeding a limit returns a limit_exceeded error. Delete voices you no longer need, or request a higher limit in the Soniox Console.