Voices API - KugelAudio

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.

Query Parameters

integer

default:"20"

Maximum number of voices to return (1-100)

integer

default:"0"

Offset for pagination

string

Language 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 the matching public catalog voices; your own matching voices come with every page and are not part of total. Omit it (or send it empty) to list every voice.

The listing returns every voice visible to you; unknown query parameters are ignored.

Response

{
  "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"
    }
  ],
  "total": 83,
  "limit": 20,
  "offset": 0
}

Example

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"

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")

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

Get Voice

Get details for a specific voice.

Path Parameters

string

required

The voice handle or legacy numeric ID

Response

{
  "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"
}

Example

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.

Request 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.

JSON

required

JSON 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`
`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)

file[]

Reference audio files (WAV, MP3, OGG, M4A, FLAC). Can include multiple files; each file is limited to 50 MiB.

During voice creation, empty files, unsupported extensions, and files larger than 50 MiB are skipped while the voice is still created. Use the dedicated reference-upload endpoint when you need a rejected file to fail the request.

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": ""
}

Example

curl -X POST "https://api.kugelaudio.com/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'metadata={"name":"My Voice","sex":"female","category":"conversational"};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",
    category="conversational",
    reference_files=["reference.wav"],
)

const voice = await client.voices.create({
  name: 'My Voice',
  sex: 'female',
  category: 'conversational',
  referenceFiles: [audioFile],
});

Update Voice

Update voice metadata. Only provided fields are changed.

Path Parameters

string

required

The voice handle or legacy numeric ID

Request Body (JSON)

string

Voice name (1-200 chars)

string

Voice description (maximum 2000 characters)

string

Generative voice description (maximum 2000 characters)

string

narrative_story, conversational, characters_animation, social_media, entertainment_tv, advertisement, or informative_educational

string

young, middle_age, or old

string

male, female, or neutral

string

low, mid, or high

array

Language tags: BCP-47 (de-DE, en-GB) or a bare language code (de)

string

Text for sample generation (maximum 2000 characters)

Example

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

Archive a voice you own. The endpoint returns 204 No Content.

Path Parameters

string

required

The voice handle or legacy numeric ID

Example

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.

Response

[
  {
    "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
  }
]

Example

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.

Request Body (multipart/form-data)

file

required

Non-empty reference audio file (WAV, MP3, OGG, M4A, FLAC), maximum 50 MiB. An empty or unsupported file returns 400; an oversized file returns 413.

string

default:""

Optional transcript of the reference audio.

Example

curl -X POST "https://api.kugelaudio.com/v1/voices/1072/references" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@new_reference.wav" \
  -F "reference_text=Hello, this is sample reference text."

ref = client.voices.add_reference(
    voice_id=1072,
    file="new_reference.wav",
    reference_text="Hello, this is sample reference text.",
)

const ref = await client.voices.addReference(1072, audioFile, 'Hello, this is sample reference text.');

Delete Voice Reference

Remove a reference audio file from a voice.

Example

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).

Request Body (multipart/form-data)

file

required

The 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.".

Example

curl -X PUT "https://api.kugelaudio.com/v1/voices/1072/avatar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@avatar.png"

Response

{
  "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.

Example

curl -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.

Example

curl -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

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.

​List Voices

​Query Parameters

​Response

​Example

​Get Voice

​Path Parameters

​Response

​Example

​Create Voice

​Request Body

​Response

​Example

​Update Voice

​Path Parameters

​Request Body (JSON)

​Example

​Delete Voice

​Path Parameters

​Example

​List Voice References

​Response

​Example

​Add Voice Reference

​Request Body (multipart/form-data)

​Example

​Delete Voice Reference

​Example

​Upload Avatar

​Request Body (multipart/form-data)

​Example

​Response

​Publish Voice

​Example

​Generate Voice Sample

​Example

​Response

​Voice Object

​Fields

​Voice Reference Fields

​Categories

​Supported Languages

​Error Responses

List Voices

Query Parameters

Response

Example

Get Voice

Path Parameters

Response

Example

Create Voice

Request Body

Response

Example

Update Voice

Path Parameters

Request Body (JSON)

Example

Delete Voice

Path Parameters

Example

List Voice References

Response

Example

Add Voice Reference

Request Body (multipart/form-data)

Example

Delete Voice Reference

Example

Upload Avatar

Request Body (multipart/form-data)

Example

Response

Publish Voice

Example

Generate Voice Sample

Example

Response

Voice Object

Fields

Voice Reference Fields

Categories

Supported Languages

Error Responses