> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voices and cloning

> List voices, add provider voices by ID, clone voices from audio samples, tune voice settings, and manage background sounds with the Callers API.

Every Voice agent speaks with a voice from your account's voice library. With the API you can list the voices available to you, add a voice you already have at ElevenLabs, Cartesia, or Google Cloud, clone a new voice from audio samples, and manage the background sounds played during calls.

For the dashboard version of these features, see [Voices and sounds](https://docs.callers.ai/documentation/voice/voices-and-sounds.md).

## List voices

`GET /voices` returns the voices your account can use.

```bash cURL theme={"dark"}
curl https://api.callers.ai/voices \
  -H "Authorization: $CALLERS_API_KEY"
```

```javascript Node.js theme={"dark"}
const res = await fetch("https://api.callers.ai/voices", {
  headers: { Authorization: process.env.CALLERS_API_KEY },
});
const { data: voices } = await res.json();
```

```python Python theme={"dark"}
voices = requests.get(
    "https://api.callers.ai/voices",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
).json()["data"]
```

**id** `string`

Callers voice ID. Use this as `voiceId` / `callParams.voice` when creating or updating agents.

**voiceId** `string`

The voice's ID at the provider.

**name** `string`

Display name.

**gender** `string`

`MALE` or `FEMALE`.

**isMultilingual** `boolean`

Whether the voice can speak several languages.

**supportedLocales** `string[]`

Locales the voice supports, such as `en-US` or `es-MX`.

**settings** `object`

Provider settings such as `stability`, `similarity_boost`, and `speed`.

**ttsClient** `string`

Speech provider.

**organizationId** `string`

Owning account.

> [!WARNING]
>
> Use the Callers `id`, not the provider `voiceId`, when you assign a voice to an agent.

## Add a voice by provider ID

If a voice already exists in your ElevenLabs, Cartesia, or Google Cloud account, add it with `POST /voices`.

**name** `string` *required*

Display name, at least 5 characters.

**voiceId** `string` *required*

The voice's ID at the provider.

**voiceProviderType** `string` *required*

`ELEVENLABS`, `CARTESIA`, or `GOOGLE_CLOUD`.

**gender** `string` *required*

`MALE` or `FEMALE`.

**ttsModel** `string`

Provider model to use with this voice.

**isMultilingual** `boolean` (default: false)

Whether the voice is multilingual.

**supportedLocales** `string[]`

Locales the voice supports.

**settings** `object`

Voice settings.

**properties**

**stability** `number` (default: 0.5)

0–1. Higher is more consistent, lower is more expressive.

**similarity\_boost** `number` (default: 0.75)

0–1. How closely to match the original voice.

**speed** `number`

−1 (slowest) to 1 (fastest). 0 is normal speed.

**subAccounts** `boolean` (default: false)

Also create the voice in each of your subaccounts.

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/voices \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support - Maya",
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceProviderType": "ELEVENLABS",
    "gender": "FEMALE",
    "supportedLocales": ["en-US"],
    "settings": { "stability": 0.6, "similarity_boost": 0.75, "speed": 0 }
  }'
```

```javascript Node.js theme={"dark"}
const res = await fetch("https://api.callers.ai/voices", {
  method: "POST",
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support - Maya",
    voiceId: "21m00Tcm4TlvDq8ikWAM",
    voiceProviderType: "ELEVENLABS",
    gender: "FEMALE",
    supportedLocales: ["en-US"],
    settings: { stability: 0.6, similarity_boost: 0.75, speed: 0 },
  }),
});
const { data: created } = await res.json(); // array of voices
```

```python Python theme={"dark"}
created = requests.post(
    "https://api.callers.ai/voices",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "Support - Maya",
        "voiceId": "21m00Tcm4TlvDq8ikWAM",
        "voiceProviderType": "ELEVENLABS",
        "gender": "FEMALE",
        "supportedLocales": ["en-US"],
        "settings": {"stability": 0.6, "similarity_boost": 0.75, "speed": 0},
    },
).json()["data"]
```

The response is an array: the voice created in your account, plus one per subaccount when `subAccounts` is `true`.

## Clone a voice from audio

`POST /voices/voice-clone` creates a new voice from recordings. Send it as `multipart/form-data` with one `files` part per recording.

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Display name, at least 5 characters. |
| `files` | Yes | Audio samples. See the provider rules below. |
| `providerType` | No | `ELEVENLABS` (default), `CARTESIA`, or `GOOGLE_CLOUD`. |
| `ttsModel` | No | Provider model. Requires `providerType`. |
| `description` | No | Description of the voice. |
| `supportedLocales` | No | Locales, default `["en-US"]`. |
| `supportsAllLanguages` | No | Mark the voice as usable in every language. Default `false`. |
| `stability`, `similarityBoost` | No | 0–1. |
| `speed` | No | −1 to 1. |
| `subAccounts` | No | Also create the voice in your subaccounts. Default `false`. |

### Audio requirements by provider

These match the limits shown in the dashboard; see [File requirements by provider](https://docs.callers.ai/documentation/voice/voices-and-sounds.md#file-requirements-by-provider).

| Provider | Files | Formats | Max size per file |
| - | - | - | - |
| ElevenLabs | 1–10 | MP3, WAV | 11 MB |
| Cartesia | Exactly 1 | FLAC, MP3, MPEG, MPGA, OGA, OGG, WAV, WEBM | 16 MB |
| Google Cloud | Exactly 2: a reference recording and a consent recording, with `reference` and `consent` in the file names | WAV, PCM, MP3, M4A | 10 MB |

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/voices/voice-clone \
  -H "Authorization: $CALLERS_API_KEY" \
  -F "name=Founder voice" \
  -F "providerType=ELEVENLABS" \
  -F "supportedLocales=en-US" \
  -F "files=@sample-1.mp3" \
  -F "files=@sample-2.mp3"
```

```javascript Node.js theme={"dark"}
import fs from "node:fs";

const form = new FormData();
form.append("name", "Founder voice");
form.append("providerType", "ELEVENLABS");
form.append("supportedLocales", "en-US");
for (const path of ["sample-1.mp3", "sample-2.mp3"]) {
  form.append("files", new Blob([fs.readFileSync(path)], { type: "audio/mpeg" }), path);
}

const res = await fetch("https://api.callers.ai/voices/voice-clone", {
  method: "POST",
  headers: { Authorization: process.env.CALLERS_API_KEY }, // fetch sets the multipart boundary
  body: form,
});
const { data: voices } = await res.json();
```

```python Python theme={"dark"}
files = [
    ("files", ("sample-1.mp3", open("sample-1.mp3", "rb"), "audio/mpeg")),
    ("files", ("sample-2.mp3", open("sample-2.mp3", "rb"), "audio/mpeg")),
]
voices = requests.post(
    "https://api.callers.ai/voices/voice-clone",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    data={"name": "Founder voice", "providerType": "ELEVENLABS", "supportedLocales": "en-US"},
    files=files,
).json()["data"]
```

The response is an array of the created voices. Use the first item's `id` in your agent.

> [!WARNING]
>
> Only clone voices you have the rights and the speaker's consent to use. Google Cloud requires a recorded consent statement as one of the two files.

> [!TIP]
>
> For the best clone, use clean recordings: one speaker, no music or background noise, natural pace, and a few minutes of total audio where the provider allows multiple files.

If voice cloning isn't available for your account, the request is rejected. Contact [support@callers.ai](mailto:support@callers.ai).

### Clone file retention

The audio files you upload for cloning are kept for a retention period. Set it in days with `PUT /voices/clone-files/retention` and the body `{ "retentionDays": 30 }` (a positive whole number).

## Update or delete a voice

* `PUT /voices/{id}` updates `name`, `ttsModel`, `isMultilingual`, `supportedLocales`, `gender`, or `settings`. Send only the fields you want to change.
* `DELETE /voices/{id}` removes the voice from your library. Reassign any agents that use it first.

```bash theme={"dark"}
curl -X PUT "https://api.callers.ai/voices/$VOICE_ID" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"stability": 0.7, "similarity_boost": 0.8, "speed": 0.1}}'
```

## Assign a voice to an agent

Pass the Callers voice `id` when creating or replacing an agent, either as `voiceId` or as `callParams.voice`:

```json theme={"dark"}
{ "name": "Renewals", "voiceId": "6650d0e1a1b2c3d4e5f60aa1" }
```

See [Manage agents](https://docs.callers.ai/api-reference/guides/manage-agents.md).

## Background sounds

Background sounds play under the agent's voice (for example, office ambience) on calls made over SIP.

| Method and path | What it does |
| - | - |
| `GET /background-noise` | List built-in presets (`source: SYSTEM`) and your uploads. |
| `POST /background-noise` | Upload an MP3 (`multipart/form-data` with `name`, 1–100 characters, and `file`, up to 10 MB). |
| `PUT /background-noise/{id}` | Rename: `{ "name": "Busy office" }`. |
| `DELETE /background-noise/{id}` | Delete an upload. |

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/background-noise \
  -H "Authorization: $CALLERS_API_KEY" \
  -F "name=Busy office" \
  -F "file=@office.mp3;type=audio/mpeg"
```

```javascript Node.js theme={"dark"}
import fs from "node:fs";

const form = new FormData();
form.append("name", "Busy office");
form.append("file", new Blob([fs.readFileSync("office.mp3")], { type: "audio/mpeg" }), "office.mp3");

const res = await fetch("https://api.callers.ai/background-noise", {
  method: "POST",
  headers: { Authorization: process.env.CALLERS_API_KEY },
  body: form,
});
```

```python Python theme={"dark"}
res = requests.post(
    "https://api.callers.ai/background-noise",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    data={"name": "Busy office"},
    files={"file": ("office.mp3", open("office.mp3", "rb"), "audio/mpeg")},
)
```

To use a sound, set the agent's `backgroundNoiseId` and, optionally, `callParams.backgroundNoiseVolumePercent`.

## Troubleshooting

> **400 when cloning**
>
> Check the file count, formats, and sizes for the provider (table above), and that `name` has at least 5 characters. `ttsModel` requires `providerType`.

> **The agent uses the wrong voice**
>
> You probably passed the provider `voiceId`. Use the Callers `id` from `GET /voices`.

> **Background sound isn't audible**
>
> Background sounds play on SIP calls only. Check the agent's volume setting.

## Related

> **[Voices and sounds](https://docs.callers.ai/documentation/voice/voices-and-sounds.md)**
>
> Browse, test, and tune voices in the dashboard.

> **[Manage agents](https://docs.callers.ai/api-reference/guides/manage-agents.md)**
>
> Assign voices to agents through the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.