# Voice cloning
URL: /tts/concepts/voice-cloning

Create custom Soniox Text-to-Speech voices from a short reference clip and use them by ID across all supported languages.

## Overview

Voice cloning lets you create a **custom voice** from a short reference clip and
then use it anywhere a [built-in voice](/tts/concepts/voices) name is accepted.
Like the built-in voices, a cloned voice works across all
[60+ supported languages](/tts/concepts/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.

<Callout type="info">
  A cloned voice is scoped to the **project** it was created in. Create, manage,
  and use the voice within that project.
</Callout>

***

## Create a voice

The easiest way to create and manage voices is in the
[Soniox Console](https://console.soniox.com):

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](#manage-voices-with-the-api).

### Reference clip requirements

* **Use a clip of up to 2 minutes.** Longer clips are accepted at upload but
  fail during processing with
  [`voice_audio_too_long`](/api-reference/errors#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`](/api-reference/errors#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 35 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](https://console.soniox.com), 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:

```json
{
  "model": "tts-rt-v2",
  "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`](/api-reference/errors#voice-not-found),
[`voice_not_ready`](/api-reference/errors#voice-not-ready),
[`voice_not_prepared`](/api-reference/errors#voice-not-prepared), or
[`voice_failed`](/api-reference/errors#voice-failed). See the
[Errors reference](/api-reference/errors) 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](/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 **35 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`](/api-reference/errors#limit-exceeded) error. Delete voices you
no longer need, or request a higher limit in the
[Soniox Console](https://console.soniox.com).