Voices and cloning

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.

List voices

GET /voices returns the voices your account can use.

curl https://api.callers.ai/voices \
  -H "Authorization: $CALLERS_API_KEY"

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

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

string

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

string

The voice’s ID at the provider.

string

Display name.

string

MALE or FEMALE.

boolean

Whether the voice can speak several languages.

string[]

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

object

Provider settings such as stability, similarity_boost, and speed.

string

Speech provider.

string

Owning account.

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.

string

required

Display name, at least 5 characters.

string

required

The voice’s ID at the provider.

string

required

ELEVENLABS, CARTESIA, or GOOGLE_CLOUD.

string

required

MALE or FEMALE.

string

Provider model to use with this voice.

boolean

default:"false"

Whether the voice is multilingual.

string[]

Locales the voice supports.

object

Voice settings.

Show properties

number

default:"0.5"

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

number

default:"0.75"

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

number

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

boolean

default:"false"

Also create the voice in each of your subaccounts.

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 }
  }'

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

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.

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

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"

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();

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.

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.

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.

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.

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:

{ "name": "Renewals", "voiceId": "6650d0e1a1b2c3d4e5f60aa1" }

See Manage agents.

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.

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"

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,
});

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.

Voices and sounds

Browse, test, and tune voices in the dashboard.

Manage agents

Assign voices to agents through the API.

Get started

Guides

Webhooks

Endpoints

Voices and cloning

List voices

Add a voice by provider ID

Clone a voice from audio

Audio requirements by provider

Clone file retention

Update or delete a voice

Assign a voice to an agent

Background sounds

Troubleshooting

Voices and sounds

Manage agents

​List voices

​Add a voice by provider ID

​Clone a voice from audio

​Audio requirements by provider

​Clone file retention

​Update or delete a voice

​Assign a voice to an agent

​Background sounds

​Troubleshooting

​Related

Voices and sounds

Manage agents

List voices

Add a voice by provider ID

Clone a voice from audio

Audio requirements by provider

Clone file retention

Update or delete a voice

Assign a voice to an agent

Background sounds

Troubleshooting

Related