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

> SDK reference for voices: list, get, create, update, delete and publish voices, manage their reference audio and generate voice samples from your own code.

Choosing a voice and the catalog are covered in [Voices](/features/voices); cloning
and speaker consent in [Voice cloning](/features/voice-cloning). Pass numeric voice
IDs. To use a voice handle, resolve it with
[`GET /v1/voices/{handle}`](/api-reference/endpoints/voices) and use the returned `id`.

## List available voices

<CodeGroup>

```python Python
# List 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}")

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

# Only voices that speak German
german = client.voices.list(language="de")
print(f"{german.total} German voices")
```

```typescript TypeScript
// List voices (returns VoiceListResponse)
const result = await client.voices.list();

for (const voice of result.voices) {
  console.log(`${voice.id}: ${voice.name}`);
  console.log(`  Category: ${voice.category}`);
  console.log(`  Languages: ${voice.supportedLanguages.join(', ')}`);
}
console.log(`Showing ${result.voices.length} of ${result.total}`);

// Paginate
const page2 = await client.voices.list({ limit: 10, offset: 10 });
console.log(`Page 2: ${page2.voices.length} voices (total: ${page2.total})`);

// Only voices that speak German
const german = await client.voices.list({ language: 'de' });
console.log(`${german.total} German voices`);
```

```java Java
import com.kugelaudio.sdk.Voice;
import com.kugelaudio.sdk.VoiceListResponse;

// List all available voices (returns VoiceListResponse)
VoiceListResponse result = client.voices().list();

for (Voice voice : result.getVoices()) {
    System.out.println(voice.getId() + ": " + voice.getName());
    System.out.println("  Sex: " + voice.getSex());
    System.out.println("  Quality: " + voice.getQuality());
}
System.out.printf("Showing %d of %d%n", result.getVoices().size(), result.getTotal());

// Paginate: list(language, includePublic, limit, offset)
VoiceListResponse page = client.voices().list(null, null, 10, 0);

// Only voices that speak German
VoiceListResponse german = client.voices().list("de", null, 100, 0);
System.out.printf("%d German voices%n", german.getTotal());
```

```rust Rust
use kugelaudio::VoiceListOptions;

// List voices (returns VoiceListResponse)
let result = client.voices().list(&VoiceListOptions::default()).await?;

for voice in &result.voices {
    println!("{}: {}", voice.id, voice.name);
    println!("  Category: {:?}", voice.category);
    println!("  Languages: {}", voice.supported_languages.join(", "));
}
println!("Showing {} of {}", result.voices.len(), result.total);

// Paginate
let page2 = client
    .voices()
    .list(&VoiceListOptions::default().limit(10).offset(10))
    .await?;
println!("Page 2: {} voices (total: {})", page2.voices.len(), page2.total);

// Only voices that speak German
let german = client.voices().list(&VoiceListOptions::default().language("de")).await?;
println!("{} German voices", german.total);
```

```cpp C++
// List voices (returns VoiceListResponse)
kugelaudio::VoiceListResponse result = client.voices().list();

for (const auto& voice : result.voices) {
  std::cout << voice.id << ": " << voice.name << '\n';
  std::cout << "  Category: " << voice.category.value_or("") << '\n';
  std::cout << "  Languages:";
  for (const auto& language : voice.supported_languages) std::cout << ' ' << language;
  std::cout << '\n';
}
std::cout << "Showing " << result.voices.size() << " of " << result.total << '\n';

// Paginate
kugelaudio::VoiceListOptions page_options;
page_options.limit = 10;
page_options.offset = 10;
kugelaudio::VoiceListResponse page2 = client.voices().list(page_options);

// Only voices that speak German
kugelaudio::VoiceListOptions german_options;
german_options.language = "de";
kugelaudio::VoiceListResponse german = client.voices().list(german_options);
std::cout << german.total << " German voices\n";
```

```dart Dart
// List voices (returns VoiceListResponse)
final result = await client.voices.list();

for (final voice in result.voices) {
  print('${voice.id}: ${voice.name}');
  print('  Category: ${voice.category?.value}');
  print('  Languages: ${voice.supportedLanguages.join(', ')}');
}
print('Showing ${result.voices.length} of ${result.total}');

// Paginate
final page2 = await client.voices.list(limit: 10, offset: 10);
print('Page 2: ${page2.voices.length} voices (total: ${page2.total})');

// Only voices that speak German
final german = await client.voices.list(language: 'de');
print('${german.total} German voices');
```

</CodeGroup>

The listing returns every voice available to you, page by page (limit and offset).
The language filter matches the voices' BCP-47 language tags, case-insensitively:
`de` matches every German accent (`de-DE`, `de-AT`, `de-CH`), `de-AT` only Austrian
German. The total and the pages count the filtered set. The include-public argument
(`include_public`, `includePublic`) defaults to true; set it to false to list only your
own voices, without the public catalog. The JavaScript and Java SDKs send false already;
the Python, Rust, C++ and Dart SDKs send it from their next release, and earlier versions
of them leave it out, so false lists the public catalog too. Each listed voice carries
`is_public` (shared in the public catalog) and `verified`.

## Get a specific voice

<CodeGroup>

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

```typescript TypeScript
const voice = await client.voices.get(1071);
console.log(`Voice: ${voice.name}`);
console.log(`Category: ${voice.category}`);
```

```java Java
import com.kugelaudio.sdk.VoiceDetail;

VoiceDetail voice = client.voices().get(1071);
System.out.println("Voice: " + voice.getName());
System.out.println("Quality: " + voice.getQuality());
```

```rust Rust
let voice = client.voices().get(1071).await?;
println!("Voice: {}", voice.name);
println!("Category: {:?}", voice.category);
```

```cpp C++
kugelaudio::VoiceDetail voice = client.voices().get(1071);
std::cout << "Voice: " << voice.name << '\n';
std::cout << "Category: " << voice.category.value_or("") << '\n';
```

```dart Dart
final voice = await client.voices.get(1071);
print('Voice: ${voice.name}');
print('Category: ${voice.category?.value}');
```

</CodeGroup>

`get()` returns the same fields as the listing (the catalog shape), including
`is_public` and `verified`. The pending-verification and sample-text fields are only
populated by `create()`, `update()` and `publish()`; in Java, `getReferences()` is empty
on `get()`, so use `listReferences(...)` for references.

## Create a voice

Create a new voice with optional reference audio files:

<CodeGroup>

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

```typescript TypeScript
// Browser: use File objects from an <input type="file">
const fileInput = document.getElementById('audio-upload') as HTMLInputElement;
const files = Array.from(fileInput.files!);

const voice = await client.voices.create({
  name: 'My Custom Voice',
  sex: 'female',
  speakerConsent: true,
  description: 'A warm, conversational voice',
  category: 'conversational',
  referenceFiles: files,
});
console.log(`Created voice: ${voice.id}`);
```

```java Java
import java.nio.file.Path;
import java.util.List;

VoiceDetail myVoice = client.voices().create(
    "My Custom Voice",
    "female",
    "en", // required by this SDK signature; see the Java tab below
    List.of(Path.of("reference1.wav"), Path.of("reference2.wav")),
    true // speakerConsent, required
);
int myVoiceId = myVoice.getId();
System.out.println("Created voice: " + myVoiceId);
```

```rust Rust
use kugelaudio::{ReferenceFile, VoiceCreate};

// VoiceCreate::new(name, sex, speaker_consent)
let voice = client
    .voices()
    .create(
        &VoiceCreate::new("My Custom Voice", "female", true)
            .description("A warm, conversational voice")
            .category("conversational")
            .reference_file(ReferenceFile::from_path("reference1.wav")?)
            .reference_file(ReferenceFile::from_path("reference2.wav")?),
    )
    .await?;
println!("Created voice: {}", voice.id);
```

```cpp C++
kugelaudio::VoiceCreateRequest request;
request.name = "My Custom Voice";
request.sex = "female";
request.speaker_consent = true;
request.description = "A warm, conversational voice";
request.category = kugelaudio::voice_category::kConversational;
request.reference_files = {"reference1.wav", "reference2.wav"};

kugelaudio::VoiceDetail voice = client.voices().create(request);
std::cout << "Created voice: " << voice.id << '\n';
```

```dart Dart
import 'package:kugelaudio/io.dart';

final voice = await client.voices.create(
  name: 'My Custom Voice',
  sex: 'female',
  speakerConsent: true,
  description: 'A warm, conversational voice',
  category: 'conversational',
  referenceFiles: [
    await loadAudioFile('reference1.wav'),
    await loadAudioFile('reference2.wav'),
  ],
);
print('Created voice: ${voice.id}');
```

</CodeGroup>

Speaker consent is required on `create()` and on adding a reference. Pass `true`
to confirm the [speaker consent](/features/voice-cloning#speaker-consent); any
other value is rejected by the API with `SPEAKER_CONSENT_REQUIRED`.

<Tabs>
<Tab title="Python">

`speaker_consent` is a required keyword argument on `create()` and
`add_reference()`. The `reference_files` parameter accepts file paths (`str` or
`Path`) whose extensions are WAV, MP3, OGG, M4A, or FLAC.

</Tab>
<Tab title="TypeScript">

`speakerConsent` is required on `create()` and `addReference()`. In Node.js, wrap the
file in a `File` so the multipart upload retains its filename extension:

```typescript
import { readFileSync } from 'fs';
import { File } from 'node:buffer';

const buf = readFileSync('reference.wav');
const file = new File([new Uint8Array(buf)], 'reference.wav', { type: 'audio/wav' });

const voice = await client.voices.create({
  name: 'My Custom Voice',
  sex: 'female',
  speakerConsent: true,
  referenceFiles: [file],
});
```

</Tab>
<Tab title="Java">

The last argument of `create(...)` and `addReference(...)` is `speakerConsent`.

The current Java SDK serializes its `language` argument under the legacy
`language` key, while the API accepts `supported_languages`. Voice creation
still succeeds, but that argument does not set the returned voice's language
list; use the REST endpoint when you need to set `supported_languages`.

Update, delete, reference, and publish calls need a voice you own, so the Java
examples below use `myVoiceId` from this step.

</Tab>
<Tab title="Rust">

`VoiceCreate::new(name, sex, speaker_consent)` takes the consent as its third
argument, and `add_reference()` takes it as an argument too. Recordings are
`ReferenceFile`s: `ReferenceFile::from_path(path)?` reads a file, and
`ReferenceFile::new(filename, bytes)` wraps bytes you already have. The other
fields are builder methods: `.description`, `.category`, `.age`, `.quality`,
`.supported_languages`, `.is_public`, `.sample_text`, `.reference_file`.

</Tab>
<Tab title="C++">

`VoiceCreateRequest::speaker_consent` defaults to `false`; set it to `true`.
`reference_files` are paths to WAV files, and `add_reference()` takes the consent as
an argument. `supported_languages` defaults to `{"en"}`.

</Tab>
<Tab title="Dart">

`speakerConsent` is required on `create()` and `addReference()`. Recordings are
`Audio` objects: `loadAudioFile(path)` from `package:kugelaudio/io.dart` reads a
file, and `Audio(bytes, filename: 'reference.wav')` wraps bytes you already have,
for example a Flutter asset or a picked file.

</Tab>
</Tabs>

## Update a voice

<CodeGroup>

```python Python
voice = client.voices.update(
    voice_id=1071,
    name="Updated Name",
    description="New description",
)
```

```typescript TypeScript
const voice = await client.voices.update(1071, {
  name: 'Updated Name',
  description: 'New description',
});
```

```java Java
import java.util.Map;

// The map carries API field names
VoiceDetail updated = client.voices().update(myVoiceId, Map.of(
    "name", "Updated Name"
));
```

```rust Rust
use kugelaudio::VoiceUpdate;

let voice = client
    .voices()
    .update(1071, &VoiceUpdate::new().name("Updated Name").description("New description"))
    .await?;
```

```cpp C++
kugelaudio::VoiceUpdate update;
update.name = "Updated Name";
update.description = "New description";
kugelaudio::VoiceDetail voice = client.voices().update(1071, update);
```

```dart Dart
final voice = await client.voices.update(
  1071,
  name: 'Updated Name',
  description: 'New description',
);
```

</CodeGroup>

The current update endpoint (`PATCH /v1/voices/{voice_id}`) does not accept the
public flag, even though the Python, TypeScript, Rust, C++ and Dart SDKs send one
when you set it. To make a voice public, call `publish()`
below. The API's `generative_voice_description` field is not exposed by the SDKs'
create and update methods; use the [Voice API reference](/api-reference/endpoints/voices)
when you need it.

## Delete a voice

<CodeGroup>

```python Python
client.voices.delete(voice_id=1071)
```

```typescript TypeScript
await client.voices.delete(1071);
```

```java Java
client.voices().delete(myVoiceId);
```

```rust Rust
client.voices().delete(1071).await?;
```

```cpp C++
client.voices().remove(1071);
```

```dart Dart
await client.voices.delete(1071);
```

</CodeGroup>

## Manage reference audio

<CodeGroup>

```python Python
# List references
for ref in client.voices.list_references(voice_id=1071):
    print(f"{ref.id}: {ref.reference_text}")

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

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

```typescript TypeScript
// List references
const refs = await client.voices.listReferences(1071);
for (const r of refs) {
  console.log(`${r.id}: ${r.referenceText}`);
}

// Add a new reference; audioFile is a File or Blob, built as in "Create a voice"
const ref = await client.voices.addReference(1071, audioFile, {
  speakerConsent: true,
  referenceText: 'Optional transcript.',
});

// Delete a reference
await client.voices.deleteReference(1071, 456);
```

```java Java
import com.kugelaudio.sdk.VoiceReference;

// List references
List<VoiceReference> refs = client.voices().listReferences(myVoiceId);
for (VoiceReference ref : refs) {
    System.out.println(ref.getId() + ": " + ref.getReferenceText());
}

// Add a new reference
VoiceReference ref = client.voices().addReference(
    myVoiceId,
    Path.of("new_reference.wav"),
    "Optional transcript of the audio.",
    true // speakerConsent, required
);

// Delete a reference
client.voices().deleteReference(myVoiceId, ref.getId());
```

```rust Rust
use kugelaudio::ReferenceFile;

// List references
for reference in client.voices().list_references(1071).await? {
    println!("{}: {:?}", reference.id, reference.reference_text);
}

// Add a new reference: file, speaker_consent, optional transcript
let reference = client
    .voices()
    .add_reference(
        1071,
        &ReferenceFile::from_path("new_reference.wav")?,
        true,
        Some("Optional transcript of the audio."),
    )
    .await?;

// Delete a reference
client.voices().delete_reference(1071, 456).await?;
```

```cpp C++
// List references
for (const auto& reference : client.voices().list_references(1071)) {
  std::cout << reference.id << ": " << reference.reference_text << '\n';
}

// Add a new reference: file, speaker_consent, optional transcript
kugelaudio::VoiceReference reference = client.voices().add_reference(
    1071, "new_reference.wav", /*speaker_consent=*/true, "Optional transcript of the audio.");

// Delete a reference
client.voices().remove_reference(1071, 456);
```

```dart Dart
import 'package:kugelaudio/io.dart';

// List references
for (final reference in await client.voices.listReferences(1071)) {
  print('${reference.id}: ${reference.referenceText}');
}

// Add a new reference
final reference = await client.voices.addReference(
  1071,
  await loadAudioFile('new_reference.wav'),
  speakerConsent: true,
  referenceText: 'Optional transcript of the audio.',
);

// Delete a reference
await client.voices.deleteReference(1071, 456);
```

</CodeGroup>

The current Java `VoiceReference` model maps `id` and `reference_text` correctly,
but its legacy `filename` property is not populated by the current API response. See
[Voice types](/sdks/types#voice-types) for the other legacy voice model fields.

## Generate a sample

Generate a preview sample from the voice's sample text (or a default). The voice
needs at least one uploaded reference.

<CodeGroup>

```python Python
# Returns a GeneratedSample: sample_s3_path and a signed, time-limited sample_url
# (None when the server could not sign one)
sample = client.voices.generate_sample(voice_id=1071)
print(f"Sample: {sample.sample_url}")
```

```typescript TypeScript
// Returns a VoiceDetail whose sampleUrl points at the new sample
const sample = await client.voices.generateSample(1071);
console.log(`Sample: ${sample.sampleUrl}`);
```

```java Java
// Only getSampleUrl() is populated; the response carries no other voice fields
VoiceDetail sample = client.voices().generateSample(myVoiceId);
System.out.println("Sample: " + sample.getSampleUrl());
```

```rust Rust
// Returns a GeneratedSample: sample_s3_path and a signed, time-limited sample_url
// (None when the server could not sign one)
let sample = client.voices().generate_sample(1071).await?;
println!("Sample: {:?}", sample.sample_url);
```

```cpp C++
// Returns a GeneratedSample: sample_s3_path and a signed, time-limited sample_url
// (std::nullopt when the server could not sign one)
kugelaudio::GeneratedSample sample = client.voices().generate_sample(1071);
std::cout << "Sample: " << sample.sample_url.value_or("") << '\n';
```

```dart Dart
// Returns a GeneratedSample: sampleS3Path and a signed, time-limited sampleUrl
// (null when the server could not sign one)
final sample = await client.voices.generateSample(1071);
print('Sample: ${sample.sampleUrl}');
```

</CodeGroup>

## Publish a voice

Request that your voice be made publicly available. This sets
`pending_verification: true` on the voice; an admin review decides whether it
becomes visible to others. The call does not change the public flag itself.

<CodeGroup>

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

```typescript TypeScript
const voice = await client.voices.publish(1071);
console.log(`Pending verification: ${voice.pendingVerification}`);
```

```java Java
// The Java VoiceDetail does not expose pending_verification;
// check the state with the REST endpoint.
client.voices().publish(myVoiceId);
```

```rust Rust
let voice = client.voices().publish(1071).await?;
println!("Pending verification: {}", voice.pending_verification);
```

```cpp C++
kugelaudio::VoiceDetail voice = client.voices().publish(1071);
std::cout << "Pending verification: " << voice.pending_verification << '\n';
```

```dart Dart
final voice = await client.voices.publish(1071);
print('Pending verification: ${voice.pendingVerification}');
```

</CodeGroup>

## Next steps

- [Types and errors](/sdks/types#voice-types): `Voice`, `VoiceDetail`, `VoiceReference`, and the create/update options
- [Generate speech](/sdks/generate): use a voice by its ID
- [Voice API reference](/api-reference/endpoints/voices): the REST response shapes, samples, and avatars
