> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voices

> Manage and list voices

## List Voices

Get a list of available voices.

<ParamField path="GET" method="/v1/voices" />

### Query Parameters

<ParamField query="language" type="string">
  Filter by language code (e.g., `en`, `de`)
</ParamField>

<ParamField query="category" type="string">
  Filter by category: `premade`, `cloned`, `generated`
</ParamField>

<ParamField query="include_public" type="boolean" default="true">
  Include public voices in results
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum number of voices to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Offset for pagination
</ParamField>

### Response

```json theme={null}
{
  "voices": [
    {
      "id": 123,
      "voice_id": 1071,
      "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"
    }
  ],
  "total": 83,
  "limit": 20,
  "offset": 0
}
```

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.kugelaudio.com/v1/voices?language=en&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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}")

  # Filter by language
  result = client.voices.list(language="en")

  # Paginate
  result = client.voices.list(limit=10, offset=20)
  ```

  ```typescript JavaScript theme={null}
  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}`);

  // Filter by language
  const englishVoices = await client.voices.list({ language: 'en' });

  // Paginate
  const page2 = await client.voices.list({ limit: 10, offset: 20 });
  ```
</CodeGroup>

***

## Get Voice

Get details for a specific voice.

<ParamField path="GET" method="/v1/voices/{voice_id}" />

### Path Parameters

<ParamField path="voice_id" type="integer" required>
  The voice ID
</ParamField>

### Response

```json theme={null}
{
  "id": 123,
  "voice_id": 1071,
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.kugelaudio.com/v1/voices/1071" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  voice = client.voices.get(voice_id=1071)
  print(f"Voice: {voice.name}")
  print(f"Languages: {', '.join(voice.supported_languages)}")
  ```

  ```typescript JavaScript theme={null}
  const voice = await client.voices.get(1071);
  console.log(`Voice: ${voice.name}`);
  console.log(`Languages: ${voice.supportedLanguages.join(', ')}`);
  ```
</CodeGroup>

***

## Create Voice

Create a new voice with optional reference audio files.

<ParamField path="POST" method="/v1/voices" />

### Request Body (multipart/form-data)

<ParamField body="metadata" type="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      |
</ParamField>

<ParamField body="files" type="file[]">
  Reference audio files (WAV, MP3, OGG, M4A, FLAC). Can include multiple files.
</ParamField>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  from kugelaudio import KugelAudio

  client = KugelAudio(api_key="YOUR_API_KEY")

  voice = client.voices.create(
      name="My Voice",
      sex="female",
      category="cloned",
      reference_files=["reference.wav"],
  )
  ```

  ```typescript JavaScript theme={null}
  const voice = await client.voices.create({
    name: 'My Voice',
    sex: 'female',
    category: 'cloned',
    referenceFiles: [audioFile],
  });
  ```
</CodeGroup>

***

## Update Voice

Update voice metadata. Only provided fields are changed.

<ParamField path="PATCH" method="/v1/voices/{voice_id}" />

### Path Parameters

<ParamField path="voice_id" type="integer" required>
  The voice ID
</ParamField>

### Request Body (JSON)

<ParamField body="name" type="string">
  Voice name (1-200 chars)
</ParamField>

<ParamField body="description" type="string">
  Voice description
</ParamField>

<ParamField body="category" type="string">
  Voice category
</ParamField>

<ParamField body="age" type="string">
  `young`, `middle_age`, or `old`
</ParamField>

<ParamField body="sex" type="string">
  `male`, `female`, or `neutral`
</ParamField>

<ParamField body="quality" type="string">
  `low`, `mid`, or `high`
</ParamField>

<ParamField body="supported_languages" type="array">
  ISO 639-1 language codes
</ParamField>

<ParamField body="is_public" type="boolean">
  Make voice public
</ParamField>

<ParamField body="sample_text" type="string">
  Text for sample generation
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  voice = client.voices.update(voice_id=1072, name="Updated Voice Name")
  ```

  ```typescript JavaScript theme={null}
  const voice = await client.voices.update(1072, { name: 'Updated Voice Name' });
  ```
</CodeGroup>

***

## Delete Voice

Delete a voice you own.

<ParamField path="DELETE" method="/v1/voices/{voice_id}" />

### Path Parameters

<ParamField path="voice_id" type="integer" required>
  The voice ID
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.kugelaudio.com/v1/voices/1072" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  client.voices.delete(voice_id=1072)
  ```

  ```typescript JavaScript theme={null}
  await client.voices.delete(1072);
  ```
</CodeGroup>

***

## List Voice References

Get reference audio files associated with a voice.

<ParamField path="GET" method="/v1/voices/{voice_id}/references" />

### Response

```json theme={null}
{
  "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
    }
  ]
}
```

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.kugelaudio.com/v1/voices/1072/references" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  refs = client.voices.list_references(voice_id=1072)
  ```

  ```typescript JavaScript theme={null}
  const refs = await client.voices.listReferences(1072);
  ```
</CodeGroup>

***

## Add Voice Reference

Upload a reference audio file to a voice.

<ParamField path="POST" method="/v1/voices/{voice_id}/references" />

### Request Body (multipart/form-data)

<ParamField body="file" type="file" required>
  Reference audio file (WAV, MP3, OGG, M4A, FLAC)
</ParamField>

<ParamField body="reference_text" type="string">
  Optional transcript of the reference audio
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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."
  ```

  ```python Python theme={null}
  ref = client.voices.add_reference(
      voice_id=1072,
      file_path="new_reference.wav",
      reference_text="Hello, this is sample reference text.",
  )
  ```

  ```typescript JavaScript theme={null}
  const ref = await client.voices.addReference(1072, audioFile, 'Hello, this is sample reference text.');
  ```
</CodeGroup>

***

## Delete Voice Reference

Remove a reference audio file from a voice.

<ParamField path="DELETE" method="/v1/voices/{voice_id}/references/{reference_id}" />

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.kugelaudio.com/v1/voices/1072/references/1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  client.voices.delete_reference(voice_id=1072, reference_id=1)
  ```

  ```typescript JavaScript theme={null}
  await client.voices.deleteReference(1072, 1);
  ```
</CodeGroup>

***

## Publish Voice

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

<ParamField path="POST" method="/v1/voices/{voice_id}/publish" />

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.kugelaudio.com/v1/voices/1072/publish" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  voice = client.voices.publish(voice_id=1072)
  ```

  ```typescript JavaScript theme={null}
  const voice = await client.voices.publish(1072);
  ```
</CodeGroup>

***

## Generate Voice Sample

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

<ParamField path="POST" method="/v1/voices/{voice_id}/generate-sample" />

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.kugelaudio.com/v1/voices/1072/generate-sample" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  voice = client.voices.generate_sample(voice_id=1072)
  print(f"Sample URL: {voice.sample_url}")
  ```

  ```typescript JavaScript theme={null}
  const voice = await client.voices.generateSample(1072);
  console.log(`Sample URL: ${voice.sampleUrl}`);
  ```
</CodeGroup>

***

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

### Categories

| 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

```json theme={null}
{
  "error": "Voice not found",
  "error_code": "NOT_FOUND",
  "code": 404
}
```

See [Error Codes](/api-reference/errors) for the full TTS and voice API error
lookup table.