Skip to content
KugelAudioDocs

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.

GET/v1/voices

Query Parameters

limit
integer
querydefault: 20

Maximum number of voices to return (1-100)

offset
integer
querydefault: 0

Offset for pagination

language
string
query

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 only the matching voices. Omit it (or send it empty) to list every voice.

include_public
boolean
querydefault: true

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

Response

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

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"

# Only your own voices
curl -X GET "https://api.kugelaudio.com/v1/voices?include_public=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Voice

Get details for a specific voice.

GET/v1/voices/{voice_id}

Path Parameters

voice_id
string
path
required

The voice handle or legacy numeric ID

Response

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

Example

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

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.

POST/v1/voices

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.

metadata
JSON
body
required

JSON object with voice metadata (sent as a JSON part):

FieldTypeRequiredDefaultDescription
namestringYes-Voice name (1-200 chars)
sexstringYes-male, female, or neutral
speaker_consentbooleanYes-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
descriptionstringNo""Voice description (maximum 2000 characters)
generative_voice_descriptionstringNo""Generative voice description (maximum 2000 characters)
categorystringNo"conversational"narrative_story, conversational, characters_animation, social_media, entertainment_tv, advertisement, or informative_educational
agestringNo"middle_age"young, middle_age, or old
qualitystringNo"mid"low, mid, or high
supported_languagesarrayNo["en"]Language tags: BCP-47 (de-DE, en-GB) or a bare language code (de)
is_publicbooleanNofalseMake voice public
sample_textstringNo""Text for sample generation (maximum 2000 characters)
files
file[]
body

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

Response

JSON
{
  "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:

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

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","speaker_consent":true};type=application/json' \
  -F "files=@reference.wav"

Update Voice

Update voice metadata. Only provided fields are changed.

PATCH/v1/voices/{voice_id}

Path Parameters

voice_id
string
path
required

The voice handle or legacy numeric ID

Request Body (JSON)

name
string
body

Voice name (1-200 chars)

description
string
body

Voice description (maximum 2000 characters)

generative_voice_description
string
body

Generative voice description (maximum 2000 characters)

category
string
body

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

age
string
body

young, middle_age, or old

sex
string
body

male, female, or neutral

quality
string
body

low, mid, or high

supported_languages
array
body

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

sample_text
string
body

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

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.

DELETE/v1/voices/{voice_id}

Path Parameters

voice_id
string
path
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"

List Voice References

Get reference audio files associated with a voice.

GET/v1/voices/{voice_id}/references

Response

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

POST/v1/voices/{voice_id}/references

Request Body (multipart/form-data)

file
file
body
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.

speaker_consent
boolean
body
required

Must 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_text
string
bodydefault:

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 "speaker_consent=true" \
  -F "reference_text=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.

DELETE/v1/voices/{voice_id}/references/{ref_id}

Example

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

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

PUT/v1/voices/{voice_id}/avatar

Request Body (multipart/form-data)

file
file
body
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

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

JSON
{
  "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"
}
POST/v1/voices/{voice_id}/publish

Example

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

Generate Voice Sample

Trigger sample audio generation for a voice that has at least one reference.

POST/v1/voices/{voice_id}/generate-sample

Example

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

Response

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

FieldTypeDescription
idintegerUnique voice ID
voice_idintegerSame as id (backward compat)
handlestring | nullPublic voice handle, when assigned
public_idstring | nullPublic identifier, when assigned
namestringVoice name
descriptionstring | nullVoice description; catalog records may return null
generative_voice_descriptionstringGenerative description
categorystringVoice category (see below)
sexstring | nullmale, female, or neutral; catalog records may return null
agestring | nullyoung, middle_age, or old; catalog records may return null
qualitystringlow, mid, or high
supported_languagesarrayBCP-47 language tags (de-DE, en-GB)
is_publicbooleanWhether the voice is public
verifiedbooleanWhether the voice is admin-verified
pending_verificationbooleanWhether verification is pending
avatar_urlstring | nullURL to avatar image
sample_urlstring | nullURL to sample audio
sample_textstringText used for sample generation

Voice Reference Fields

FieldTypeDescription
idintegerReference ID
voice_idintegerParent voice ID
namestringFile name
reference_textstringTranscript of the audio
s3_pathstringStorage path
audio_urlstring | nullSigned URL to audio, when available
is_generatedbooleanWhether 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:

CodeLanguage
enEnglish
deGerman
frFrench
esSpanish
itItalian
ptPortuguese
nlDutch
plPolish
jaJapanese
zhChinese
koKorean

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.

JSON
{
  "error": "Voice not found",
  "error_code": "NOT_FOUND",
  "code": 404
}

See Error Codes for the full TTS and voice API error lookup table.