# Custom voices

> Your org's own voices, each made from one short recording: create, list, rename, replace the recording, delete.

## Getting them enabled

A custom voice is a voice of your org's own, made from one short recording of a speaker. Only your org can speak it.

Custom voices are switched on per org, on request: write to [hello@vaakini.com](mailto:hello@vaakini.com?subject=Custom%20voices). Until then, creating one is refused with `custom_voices_not_enabled` (HTTP 403); listing works, and says `enabled: false`.

Once enabled, make and manage voices on the dashboard’s [Voices](https://app.vaakini.com/app/voices) page, or with the API below. An org can hold 10. They are free to create and keep, and are spoken at the same [price](https://docs.vaakini.com/pricing.md) as every other voice.

> Clone only a voice you have the right to use: your own, or one whose speaker has agreed to it.

## The recording

One speaker, clean speech, with the exact words that are spoken.

|  | What it takes |
| --- | --- |
| Format | WAV, FLAC or Ogg |
| Length | 0.5 to 30 seconds; 3 to 10 seconds of clean speech works best. A longer one is refused, never trimmed. |
| Transcript | The exact words spoken in the recording, up to 2,000 characters |
| Language | The recording's language, one of the twelve. The voice then speaks all twelve. |

## Create a voice

`POST /v1/custom-voices`, as a multipart form.

```shell
curl https://api.vaakini.com/v1/custom-voices \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -F name="Priya (support)" \
  -F gender=female \
  -F language=hi \
  -F transcript="नमस्ते, मैं प्रिया बोल रही हूँ।" \
  -F audio=@priya.wav
```

- `name` (`string`, Required): Your name for the voice, 1 to 100 characters.
- `audio` (`file`, Required): The recording.
- `transcript` (`string`, Required): The exact words spoken in it.
- `language` (`string`, Required): The recording’s language: `as` , `bn` , `en` , `gu` , `hi` , `kn` , `ml` , `mr` , `or` , `pa` , `ta` or `te`.
- `gender` (`string`, Optional): `female` or `male`: your label for the voice, shown in `GET /v1/voices`. It doesn’t change how the voice sounds.
- `models` (`JSON string`, Optional): How the voice is cloned, e.g. `{"vaakini-tts-1": {"mode": "icl"}}`. The modes are `icl_spk` (the default, recommended), `icl` and `spk`.

The answer is the voice, with status 201:

```json
{
  "id": "cv_t76u7a3um3xayk4b",
  "name": "Priya (support)",
  "gender": "female",
  "language": "hi",
  "models": [{"model": "vaakini-tts-1", "mode": "icl_spk"}],
  "revision": 1,
  "created_at": "2026-11-16T09:30:12Z"
}
```

## Speak it

Its `id` is what `voice` takes, in every client.

**cURL**

```shell
curl https://api.vaakini.com/v1/audio/speech \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "vaakini-tts-1", "voice": "cv_t76u7a3um3xayk4b", "language": "hi", "input": "आपका स्वागत है।"}' \
  --output welcome.mp3
```

**Python**

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

audio = client.speech.create(input="आपका स्वागत है।", voice="cv_t76u7a3um3xayk4b", language="hi")
with open("welcome.mp3", "wb") as f:
    f.write(audio)
```

In the LiveKit plugin it is `vaakini.TTS(voice="cv_…")`, in the Pipecat service `Settings(voice="cv_…")`. The voice is also in your org’s `GET /v1/voices`, with `category` `cloned`.

> **Give a new voice a few seconds**
>
> A voice created a moment ago can be refused as an unknown voice for a few seconds. Wait about five seconds after creating one before the first request that speaks it.

## List, rename, delete

```shell
curl https://api.vaakini.com/v1/custom-voices \
  -H "Authorization: Bearer $VAAKINI_API_KEY"
```

```json
{
  "enabled": true,
  "limit": 10,
  "voices": [
    {
      "id": "cv_t76u7a3um3xayk4b",
      "name": "Priya (support)",
      "gender": "female",
      "language": "hi",
      "models": [{"model": "vaakini-tts-1", "mode": "icl_spk"}],
      "revision": 1,
      "created_at": "2026-11-16T09:30:12Z"
    }
  ]
}
```

`enabled` says whether custom voices are switched on for your org, and `limit` how many it can hold. `GET /v1/custom-voices/{id}` answers one voice.

`PATCH` changes the name, the gender or both, and nothing else; a `gender` of null clears it.

```shell
curl -X PATCH https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Priya", "gender": null}'
```

`DELETE` removes the voice at once, with its recording and transcript: requests that name it are refused from then on. It answers 204.

```shell
curl -X DELETE https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b \
  -H "Authorization: Bearer $VAAKINI_API_KEY"
```

## Replace the recording

A better recording under the same id, so nothing that names the voice has to change.

```shell
curl -X PUT https://api.vaakini.com/v1/custom-voices/cv_t76u7a3um3xayk4b/recording \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -F language=hi \
  -F transcript="नमस्ते, मैं प्रिया बोल रही हूँ।" \
  -F audio=@priya2.wav
```

`PUT /v1/custom-voices/{id}/recording` takes `audio`, `transcript`, `language` and optionally `models`, as create does: the four change together. The voice’s `revision` goes up by one; its name and gender stay. Requests from then on speak the new recording, within a few seconds, and a reply already being spoken finishes in the old one. If the new recording can’t be used, the voice keeps its old one.

The Python SDK does all of this too:

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

voice = client.custom_voices.create(
    name="Priya (support)",
    audio="priya.wav",  # a path, bytes or an open binary file
    transcript="नमस्ते, मैं प्रिया बोल रही हूँ।",
    language="hi",
    gender="female",
)
print(voice.id, voice.revision)

print(client.custom_voices.list().voices)
print(client.custom_voices.get(voice.id).name)

voice = client.custom_voices.update(voice.id, name="Priya")
voice = client.custom_voices.replace_recording(
    voice.id,
    audio="priya2.wav",
    transcript="नमस्ते, मैं प्रिया बोल रही हूँ।",
    language="hi",
)
print(voice.name, voice.revision)

client.custom_voices.delete(voice.id)
```

## Errors

| code | Status | Meaning |
| --- | --- | --- |
| custom_voices_not_enabled | 403 | Custom voices aren't enabled for your org. |
| custom_voice_limit | 409 | Your org holds as many custom voices as it can. |
| bad_request | 422 | A field is missing or wrong, or the recording can't be used; the message says which. |
| not_found | 404 | No such custom voice in your org. |
| unavailable | 503 | The voice couldn't be made just now. Nothing was kept: try again. |

They come in the [shape](https://docs.vaakini.com/errors.md#shape) every error has.
