Voices API
REST reference for the Voices API: list and filter voices, get voice details, create, update and delete voices, and manage their reference audio.
Catalog and management endpoints require authentication. List/get return public catalog voices plus private voices visible to the caller's organization. Create, update, delete, reference, publish, and sample operations additionally require an API key associated with an organization and user, and operate only on voices that organization owns.
Every {voice_id} path field accepts a numeric voice ID or a public handle.
The {ref_id} path field is the integer reference ID returned by list or upload.
List Voices
Get a list of available voices.
/v1/voicesQuery Parameters
limit20Maximum number of voices to return (1-100)
offset0Offset for pagination
languageLanguage filter on the BCP-47 tags in supported_languages,
case-insensitive. A bare language code matches every accent of it: de
returns de-DE, de-AT and de-CH voices. A full tag matches only that
accent: de-AT returns Austrian German voices only. total and pagination
count only the matching voices. Omit it (or send it empty) to list every voice.
include_publictruefalse lists only your own voices, without the public catalog. A voice of
yours that is also in the public catalog is listed among them.
The listing returns every voice visible to you, your own voices first and then
the public catalog, newest first within each. limit and offset page that
one list, and total counts all of it, so a page with an offset at or past
total is empty. Unknown query parameters are ignored.
Each voice carries is_public (shared in the public catalog) and verified
(checked and admitted to the catalog by KugelAudio). A public catalog voice has both.
{
"voices": [
{
"id": 1071,
"voice_id": 1071,
"handle": "emma",
"public_id": null,
"name": "Emma",
"description": "Warm, friendly female voice",
"category": "premade",
"sex": "female",
"age": "middle_age",
"quality": "high",
"supported_languages": ["en-GB", "de-DE"],
"avatar_url": "https://cdn.kugelaudio.com/avatars/emma.png",
"sample_url": "https://cdn.kugelaudio.com/samples/emma.mp3",
"is_public": true,
"verified": true
}
],
"total": 83,
"limit": 20,
"offset": 0
}curl -X GET "https://api.kugelaudio.com/v1/voices?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
# Only German voices
curl -X GET "https://api.kugelaudio.com/v1/voices?language=de" \
-H "Authorization: Bearer YOUR_API_KEY"
# Only your own voices
curl -X GET "https://api.kugelaudio.com/v1/voices?include_public=false" \
-H "Authorization: Bearer YOUR_API_KEY"from kugelaudio import KugelAudio
client = KugelAudio(api_key="YOUR_API_KEY")
# List all voices
result = client.voices.list()
for voice in result.voices:
print(f"{voice.id}: {voice.name}")
print(f"Total: {result.total}")
# Paginate
result = client.voices.list(limit=10, offset=20)
# Only German voices
german = client.voices.list(language="de")
# Only your own voices (sent from the Python SDK release after 2026-11-14;
# earlier versions omit include_public=False and list the catalog too)
mine = client.voices.list(include_public=False)
for voice in mine.voices:
print(f"{voice.name}: public={voice.is_public} verified={voice.verified}")import { KugelAudio } from 'kugelaudio';
const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });
// List all voices
const result = await client.voices.list();
for (const voice of result.voices) {
console.log(`${voice.id}: ${voice.name}`);
}
console.log(`Total: ${result.total}`);
// Paginate
const page2 = await client.voices.list({ limit: 10, offset: 20 });
// Only German voices
const german = await client.voices.list({ language: 'de' });
// Only your own voices
const mine = await client.voices.list({ includePublic: false });
for (const voice of mine.voices) {
console.log(`${voice.name}: public=${voice.isPublic} verified=${voice.verified}`);
}Get Voice
Get details for a specific voice.
/v1/voices/{voice_id}Path Parameters
voice_idThe voice handle or legacy numeric ID
{
"id": 1071,
"voice_id": 1071,
"handle": "emma",
"public_id": null,
"name": "Emma",
"description": "Warm, friendly female voice with a slight British accent",
"category": "premade",
"sex": "female",
"age": "middle_age",
"quality": "high",
"supported_languages": ["en", "de", "fr"],
"avatar_url": "https://cdn.kugelaudio.com/avatars/emma.png",
"sample_url": "https://cdn.kugelaudio.com/samples/emma.mp3",
"is_public": true,
"verified": true
}curl -X GET "https://api.kugelaudio.com/v1/voices/1071" \
-H "Authorization: Bearer YOUR_API_KEY"voice = client.voices.get(voice_id=1071)
print(f"Voice: {voice.name}")
print(f"Languages: {', '.join(voice.supported_languages)}")const voice = await client.voices.get(1071);
console.log(`Voice: ${voice.name}`);
console.log(`Languages: ${voice.supportedLanguages.join(', ')}`);Create Voice
Create a new voice with optional reference audio files. The request must carry
speaker_consent: true, your speaker consent; without it the request is rejected
with 400 and error_code SPEAKER_CONSENT_REQUIRED, and nothing is stored.
/v1/voicesRequest Body
Send either application/json with the metadata fields directly in the body,
or multipart/form-data when attaching reference files. Multipart requests use
the parts below.
metadataJSON object with voice metadata (sent as a JSON part):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | - | Voice name (1-200 chars) |
sex | string | Yes | - | male, female, or neutral |
speaker_consent | boolean | Yes | - | Must be true: you confirm that you are the speaker of the recordings or that you have the speaker's permission to create a synthetic voice from them. Only the JSON boolean true is accepted |
description | string | No | "" | Voice description (maximum 2000 characters) |
generative_voice_description | string | No | "" | Generative voice description (maximum 2000 characters) |
category | string | No | "conversational" | narrative_story, conversational, characters_animation, social_media, entertainment_tv, advertisement, or informative_educational |
age | string | No | "middle_age" | young, middle_age, or old |
quality | string | No | "mid" | low, mid, or high |
supported_languages | array | No | ["en"] | Language tags: BCP-47 (de-DE, en-GB) or a bare language code (de) |
is_public | boolean | No | false | Make voice public |
sample_text | string | No | "" | Text for sample generation (maximum 2000 characters) |
filesReference audio files (WAV, MP3, OGG, M4A, FLAC). Can include multiple files; each file is limited to 50 MiB.
Response
{
"id": 456,
"voice_id": 456,
"handle": null,
"public_id": null,
"name": "My Custom Voice",
"description": "Cloned from reference audio",
"generative_voice_description": "",
"supported_languages": ["en"],
"category": "conversational",
"age": "middle_age",
"sex": "female",
"quality": "mid",
"is_public": false,
"verified": false,
"pending_verification": false,
"sample_url": null,
"avatar_url": null,
"sample_text": ""
}A request without speaker_consent: true returns 400:
{
"error": "speaker_consent must be true: confirm that you are the speaker of the recording or that you have the speaker's permission to create a synthetic voice from it.",
"error_code": "SPEAKER_CONSENT_REQUIRED",
"code": 400
}curl -X POST "https://api.kugelaudio.com/v1/voices" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F 'metadata={"name":"My Voice","sex":"female","category":"conversational","speaker_consent":true};type=application/json' \
-F "files=@reference.wav"from kugelaudio import KugelAudio
client = KugelAudio(api_key="YOUR_API_KEY")
voice = client.voices.create(
name="My Voice",
sex="female",
speaker_consent=True,
category="conversational",
reference_files=["reference.wav"],
)const voice = await client.voices.create({
name: 'My Voice',
sex: 'female',
speakerConsent: true,
category: 'conversational',
referenceFiles: [audioFile],
});Update Voice
Update voice metadata. Only provided fields are changed.
/v1/voices/{voice_id}Path Parameters
voice_idThe voice handle or legacy numeric ID
Request Body (JSON)
nameVoice name (1-200 chars)
descriptionVoice description (maximum 2000 characters)
generative_voice_descriptionGenerative voice description (maximum 2000 characters)
categorynarrative_story, conversational, characters_animation, social_media,
entertainment_tv, advertisement, or informative_educational
ageyoung, middle_age, or old
sexmale, female, or neutral
qualitylow, mid, or high
supported_languagesLanguage tags: BCP-47 (de-DE, en-GB) or a bare language code (de)
sample_textText for sample generation (maximum 2000 characters)
curl -X PATCH "https://api.kugelaudio.com/v1/voices/1072" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Voice Name", "description": "New description"}'voice = client.voices.update(voice_id=1072, name="Updated Voice Name")const voice = await client.voices.update(1072, { name: 'Updated Voice Name' });Delete Voice
Permanently delete a voice you own, together with its stored audio: the
reference audio, the generated sample, the avatar and the cached encodings. The
endpoint returns 204 No Content. Deletion cannot be undone.
A published (public) voice cannot be deleted and returns 409. If the stored
audio cannot be removed, the endpoint returns 500 and the voice is left
unchanged, so the request can be repeated.
/v1/voices/{voice_id}Path Parameters
voice_idThe voice handle or legacy numeric ID
curl -X DELETE "https://api.kugelaudio.com/v1/voices/1072" \
-H "Authorization: Bearer YOUR_API_KEY"client.voices.delete(voice_id=1072)await client.voices.delete(1072);List Voice References
Get reference audio files associated with a voice.
/v1/voices/{voice_id}/references[
{
"id": 1,
"voice_id": 1072,
"name": "reference.wav",
"reference_text": "",
"s3_path": "voices/1072/references/1.wav",
"audio_url": "https://cdn.kugelaudio.com/...",
"is_generated": false
}
]curl "https://api.kugelaudio.com/v1/voices/1072/references" \
-H "Authorization: Bearer YOUR_API_KEY"Add Voice Reference
Upload a reference audio file to a voice. The request must carry
speaker_consent=true, your speaker consent for this recording; without it the
upload is rejected with 400 and error_code SPEAKER_CONSENT_REQUIRED, and
no audio is stored.
/v1/voices/{voice_id}/referencesRequest Body (multipart/form-data)
fileNon-empty reference audio file (WAV, MP3, OGG, M4A, FLAC), maximum 50 MiB.
An empty or unsupported file returns 400; an oversized file returns 413.
speaker_consentMust be true: you confirm that you are the speaker of this recording or
that you have the speaker's permission to create a synthetic voice from it.
reference_textOptional transcript of the reference audio.
curl -X POST "https://api.kugelaudio.com/v1/voices/1072/references" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@new_reference.wav" \
-F "speaker_consent=true" \
-F "reference_text=Hello, this is sample reference text."ref = client.voices.add_reference(
voice_id=1072,
file="new_reference.wav",
speaker_consent=True,
reference_text="Hello, this is sample reference text.",
)const ref = await client.voices.addReference(1072, audioFile, {
speakerConsent: true,
referenceText: 'Hello, this is sample reference text.',
});Delete Voice Reference
Permanently delete a reference audio file from a voice, including the stored
audio. The endpoint returns 204 No Content.
/v1/voices/{voice_id}/references/{ref_id}curl -X DELETE "https://api.kugelaudio.com/v1/voices/1072/references/1" \
-H "Authorization: Bearer YOUR_API_KEY"client.voices.delete_reference(voice_id=1072, reference_id=1)await client.voices.deleteReference(1072, 1);Upload Avatar
Upload a PNG, JPEG, or WebP avatar image for a voice you can edit. The format is
detected from the file content. Avatars of public voices cannot be changed
(403).
/v1/voices/{voice_id}/avatarRequest Body (multipart/form-data)
fileThe image file. Maximum 10 MB (413 above that); an empty file returns 400,
and a file that is not PNG, JPEG, or WebP returns
400 "Unsupported avatar format. Use PNG, JPEG, or WebP.".
curl -X PUT "https://api.kugelaudio.com/v1/voices/1072/avatar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@avatar.png"{
"avatar_s3_path": "voices/1072/avatar.png"
}Publish Voice
Request publication of a voice. This sets pending_verification: true; an admin
review decides whether the voice becomes public. is_public is not changed by
this call.
A voice with no recorded speaker consent cannot be published: the call returns
409 with error_code SPEAKER_CONSENT_MISSING. This applies to voices created
before the consent was required. Add the voice's reference audio again with
speaker_consent=true, then publish.
Public voices need clean references: speech must sit at least 20 dB above the
background or room sound between words in the first 20 seconds of every
reference, because a voice reproduces the room of its reference in every
render. A voice with a reference below that returns 400 with error_code
VALIDATION_ERROR and a message naming the measured value. Record in a quieter
room or clean the recording, replace the reference, then publish again. The
same check applies when you add a reference to a voice that is already public;
such a reference must be WAV, FLAC, MP3 or OGG. Private voices are not checked.
{
"error": "Reference 'take-1.wav' has background or room sound between words: speech sits only 12.6 dB above it, and public voices need at least 20.0 dB. Record in a quieter room or clean the recording, then upload it again.",
"error_code": "VALIDATION_ERROR"
}/v1/voices/{voice_id}/publishcurl -X POST "https://api.kugelaudio.com/v1/voices/1072/publish" \
-H "Authorization: Bearer YOUR_API_KEY"voice = client.voices.publish(voice_id=1072)const voice = await client.voices.publish(1072);Generate Voice Sample
Trigger sample audio generation for a voice that has at least one reference.
/v1/voices/{voice_id}/generate-samplecurl -X POST "https://api.kugelaudio.com/v1/voices/1072/generate-sample" \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"sample_s3_path": "voices/1072/sample.wav",
"sample_url": "https://cdn.kugelaudio.com/..."
}sample_s3_path is always a string. sample_url is a signed string | null.
Voice Object
Fields
List and get responses contain the catalog fields through avatar_url and
sample_url. Create, update, and publish responses additionally contain the
generative, publication, verification, and sample-text fields below.
The list response wraps the voice objects in voices and also returns integer
total, limit, and offset fields.
| Field | Type | Description |
|---|---|---|
id | integer | Unique voice ID |
voice_id | integer | Same as id (backward compat) |
handle | string | null | Public voice handle, when assigned |
public_id | string | null | Public identifier, when assigned |
name | string | Voice name |
description | string | null | Voice description; catalog records may return null |
generative_voice_description | string | Generative description |
category | string | Voice category (see below) |
sex | string | null | male, female, or neutral; catalog records may return null |
age | string | null | young, middle_age, or old; catalog records may return null |
quality | string | low, mid, or high |
supported_languages | array | BCP-47 language tags (de-DE, en-GB) |
is_public | boolean | Whether the voice is public |
verified | boolean | Whether the voice is admin-verified |
pending_verification | boolean | Whether verification is pending |
avatar_url | string | null | URL to avatar image |
sample_url | string | null | URL to sample audio |
sample_text | string | Text used for sample generation |
Voice Reference Fields
| Field | Type | Description |
|---|---|---|
id | integer | Reference ID |
voice_id | integer | Parent voice ID |
name | string | File name |
reference_text | string | Transcript of the audio |
s3_path | string | Storage path |
audio_url | string | null | Signed URL to audio, when available |
is_generated | boolean | Whether the reference was auto-generated |
Categories
The accepted values when creating or updating a voice are
narrative_story, conversational, characters_animation, social_media,
entertainment_tv, advertisement, and informative_educational.
Supported Languages
Common language codes:
| Code | Language |
|---|---|
en | English |
de | German |
fr | French |
es | Spanish |
it | Italian |
pt | Portuguese |
nl | Dutch |
pl | Polish |
ja | Japanese |
zh | Chinese |
ko | Korean |
Error Responses
Notable management errors include 400 VALIDATION_ERROR for invalid metadata
or files, 403 UNAUTHORIZED when the key has no organization/user identity,
404 NOT_FOUND for an invisible voice or missing reference, 413 VALIDATION_ERROR for a reference upload over 50 MiB or an avatar over 10 MB, and 501 VALIDATION_ERROR when voice management is unavailable on the deployment.
{
"error": "Voice not found",
"error_code": "NOT_FOUND",
"code": 404
}See Error Codes for the full TTS and voice API error lookup table.