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

> List, create, update, and manage voices and reference audio

## List Available Voices

```python theme={null}
# List all available voices (returns VoiceListResponse)
result = client.voices.list()

for voice in result.voices:
    print(f"{voice.id}: {voice.name}")
    print(f"  Category: {voice.category}")
    print(f"  Languages: {', '.join(voice.supported_languages)}")
print(f"Showing {len(result.voices)} of {result.total}")

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

# Paginate
page2 = client.voices.list(limit=10, offset=10)
print(f"Page 2: {len(page2.voices)} voices (total: {page2.total})")
```

`list()` also declares `include_public`, but the current Python implementation
only sends that query field when it is `True`; `include_public=False` therefore
behaves like the API default instead of excluding public voices. Use the raw
Voice API when you need that filter.

## Get a Specific Voice

```python theme={null}
voice = client.voices.get(voice_id=1071)
print(f"Voice: {voice.name}")
print(f"Category: {voice.category}")
```

## Create a Voice

Create a new voice with optional reference audio files:

```python theme={null}
voice = client.voices.create(
    name="My Custom Voice",
    sex="female",
    description="A warm, conversational voice",
    category="conversational",
    reference_files=["reference1.wav", "reference2.wav"],
)
print(f"Created voice: {voice.id}")
```

The `reference_files` parameter accepts file paths (`str` or `Path`) whose
extensions are WAV, MP3, OGG, M4A, or FLAC.

## Update a Voice

```python theme={null}
voice = client.voices.update(
    voice_id=1071,
    name="Updated Name",
    description="New description",
)
```

The SDK also declares an `is_public` update argument, but the current API does
not accept that field on `PATCH /v1/voices/{voice_id}`. Use `publish()` to make
a voice public. The API's `generative_voice_description` field is not exposed
by this SDK's create/update methods; use the [Voice API
reference](/api-reference/endpoints/voices) when you need it.

## Delete a Voice

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

## Manage Reference Audio

```python theme={null}
# Add a new reference (file is positional; accepts a str or Path)
ref = client.voices.add_reference(
    voice_id=1071,
    file="new_reference.wav",
    reference_text="Optional transcript of the audio.",
)

# Delete a reference
client.voices.delete_reference(voice_id=1071, reference_id=456)
```

## Publish a Voice

Request that your voice be made publicly available. An admin will verify it before it becomes visible to others.

```python theme={null}
voice = client.voices.publish(voice_id=1071)
print(f"Pending verification: {voice.pending_verification}")
```

## Next steps

* [Types & Errors](/sdks/python/types) — `Voice`, `VoiceDetail`, `VoiceReference`, and enums
* [Generate Speech](/sdks/python/generate) — use a voice via `voice_id`
* [Voice API reference](/api-reference/endpoints/voices) — list references or
  generate a sample with the REST response shapes