> ## 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, publish, and manage voices and their reference audio

## List Available Voices

```typescript theme={null}
// List all available 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}`);

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

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

## Get a Specific Voice

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

## Create a Voice

Create a new voice with optional reference audio files:

```typescript theme={null}
// 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',
  description: 'A warm, conversational voice',
  category: 'conversational',
  referenceFiles: files,
});
console.log(`Created voice: ${voice.id}`);
```

```typescript theme={null}
// Node.js — use File so the multipart upload retains its filename extension
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',
  referenceFiles: [file],
});
```

## Update a Voice

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

## Delete a Voice

```typescript theme={null}
await client.voices.delete(1071);
```

## Manage Reference Audio

```typescript theme={null}
// Add a new reference
const ref = await client.voices.addReference(1071, audioFile, 'Optional transcript.');

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

## Publish a Voice

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

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

***

The `Voice`, `VoiceDetail`, `VoiceReference`, and create/update option interfaces are documented in [Types & Errors](/sdks/javascript/types#voice).

Use the [Voice API reference](/api-reference/endpoints/voices) to list references
or generate a sample with the REST response shapes.