Voices - KugelAudio

List Voices

Get a list of available voices.

GET

Query Parameters

language

string

Filter by language code (e.g., en, de)

Response

{
  "voices": [
    {
      "id": 123,
      "voice_id": 123,
      "name": "Emma",
      "description": "Warm, friendly female voice",
      "category": "premade",
      "sex": "female",
      "age": "middle_aged",
      "supported_languages": ["en", "de"],
      "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?language=en&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Voice

Get details for a specific voice.

GET

Path Parameters

voice_id

integer

required

The voice ID

Response

{
  "id": 123,
  "voice_id": 123,
  "name": "Emma",
  "description": "Warm, friendly female voice with a slight British accent",
  "category": "premade",
  "sex": "female",
  "age": "middle_aged",
  "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/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Voice

Create a new voice with optional reference audio files.

POST

Request Body (multipart/form-data)

metadata

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
`category`	string	No	`"conversational"`	Voice category
`age`	string	No	`"middle_age"`	`young`, `middle_age`, or `old`
`quality`	string	No	`"mid"`	`low`, `mid`, or `high`
`supported_languages`	array	No	`["en"]`	ISO 639-1 language codes
`is_public`	boolean	No	`false`	Make voice public
`sample_text`	string	No	`""`	Text for sample generation

files

file[]

Reference audio files (WAV, MP3, FLAC). Can include multiple files.

Response

{
  "id": 456,
  "name": "My Custom Voice",
  "description": "Cloned from reference audio",
  "generative_voice_description": "",
  "supported_languages": ["en"],
  "category": "cloned",
  "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":"cloned"};type=application/json' \
  -F "files=@reference.wav"

Update Voice

Update voice metadata. Only provided fields are changed.

PATCH

Path Parameters

voice_id

integer

required

The voice ID

Request Body (JSON)

name

string

Voice name (1-200 chars)

description

string

Voice description

Example

curl -X PATCH "https://api.kugelaudio.com/v1/voices/456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Voice Name", "description": "New description"}'

Delete Voice

Delete a voice you own.

DELETE

Path Parameters

voice_id

integer

required

The voice ID

Example

curl -X DELETE "https://api.kugelaudio.com/v1/voices/456" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Voice References

Get reference audio files associated with a voice.

GET

Response

{
  "references": [
    {
      "id": 1,
      "voice_id": 456,
      "name": "reference.wav",
      "reference_text": "",
      "s3_path": "voices/456/references/1.wav",
      "audio_url": "https://cdn.kugelaudio.com/...",
      "is_generated": false
    }
  ]
}

Example

curl "https://api.kugelaudio.com/v1/voices/456/references" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Voice Reference

Upload a reference audio file to a voice.

POST

Request Body (multipart/form-data)

file

required

Reference audio file (WAV, MP3, FLAC)

reference_text

string

Optional transcript of the reference audio

Example

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

Delete Voice Reference

Remove a reference audio file from a voice.

DELETE

Example

curl -X DELETE "https://api.kugelaudio.com/v1/voices/456/references/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish Voice

Request publication of a voice. Sets the voice as public and marks it as pending verification.

POST

Example

curl -X POST "https://api.kugelaudio.com/v1/voices/456/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Generate Voice Sample

Trigger sample audio generation for a voice. Sample generation also runs automatically on voice creation and when references change.

POST

Example

curl -X POST "https://api.kugelaudio.com/v1/voices/456/generate-sample" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voice Object

Fields

Field	Type	Description
`id`	integer	Unique voice ID
`voice_id`	integer	Same as `id` (backward compat)
`name`	string	Voice name
`description`	string	Voice description
`generative_voice_description`	string	Generative description
`category`	string	Voice category (see below)
`sex`	string	`male`, `female`, or `neutral`
`age`	string	`young`, `middle_age`, or `old`
`quality`	string	`low`, `mid`, or `high`
`supported_languages`	array	ISO 639-1 language codes
`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	URL to avatar image
`sample_url`	string	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	Public URL to audio
`is_generated`	boolean	Whether the reference was auto-generated

Category	Description
`premade`	Built-in voices provided by KugelAudio
`cloned`	Voices created from audio samples
`designed`	Custom-designed voices
`conversational`	Voices optimized for conversation
`narrative`	Voices for narration
`narrative_story`	Voices for storytelling
`characters`	Character voices

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

Voice Not Found

{
  "detail": "Voice not found"
}

Access Denied

{
  "detail": "Not authorized to access this voice"
}

Validation Error

{
  "detail": "category must be one of ['premade', 'cloned', ...], got 'invalid'"
}

API Documentation

Endpoints

​List Voices

​Query Parameters

​Response

​Example

​Get Voice

​Path Parameters

​Response

​Example

​Create Voice

​Request Body (multipart/form-data)

​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

​Publish Voice

​Example

​Generate Voice Sample

​Example

​Voice Object

​Fields

​Voice Reference Fields

​Categories

​Supported Languages

​Error Responses

​Voice Not Found

​Access Denied

​Validation Error

List Voices

Query Parameters

Response

Example

Get Voice

Path Parameters

Response

Example

Create Voice

Request Body (multipart/form-data)

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

Publish Voice

Example

Generate Voice Sample

Example

Voice Object

Fields

Voice Reference Fields

Categories

Supported Languages

Error Responses

Voice Not Found

Access Denied

Validation Error