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

# Using Voices

> Browse, filter, and use voices for speech generation

KugelAudio provides a variety of premade voices and supports custom voice cloning. This guide covers how to work with voices in your application.

## List Available Voices

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # List all available voices
    voices = client.voices.list()

    for voice in voices:
        print(f"{voice.id}: {voice.name}")
        print(f"  Category: {voice.category}")
        print(f"  Languages: {', '.join(voice.supported_languages)}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    // List all available voices
    const voices = await client.voices.list();

    for (const voice of voices) {
      console.log(`${voice.id}: ${voice.name}`);
      console.log(`  Category: ${voice.category}`);
      console.log(`  Languages: ${voice.supportedLanguages.join(', ')}`);
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.kugelaudio.sdk.Voice;
    import java.util.List;

    List<Voice> voices = client.voices().list();
    for (Voice voice : voices) {
        System.out.printf("%d: %s%n", voice.getId(), voice.getName());
        System.out.printf("  Category: %s%n", voice.getCategory());
        System.out.printf("  Languages: %s%n",
            String.join(", ", voice.getSupportedLanguages()));
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.kugelaudio.com/v1/voices \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"
    ```
  </Tab>
</Tabs>

## Filter Voices

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Filter by language
    result = client.voices.list(language="de")
    german_voices = result.voices

    # Get only public voices
    result = client.voices.list(include_public=True)

    # Limit results
    result = client.voices.list(limit=10)

    # Paginate through all voices
    result = client.voices.list(limit=10, offset=20)
    print(f"Showing {len(result.voices)} of {result.total} voices")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    // Filter by language
    const { voices: germanVoices } = await client.voices.list({ language: 'de' });

    // Get only public voices
    const { voices: publicVoices } = await client.voices.list({ includePublic: true });

    // Limit results
    const { voices: first10 } = await client.voices.list({ limit: 10 });

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

  <Tab title="Java">
    ```java theme={null}
    // Filter by language
    VoiceListResponse result = client.voices().list("de", null, null, null);
    List<Voice> germanVoices = result.getVoices();

    // Paginate
    VoiceListResponse page = client.voices().list(null, null, 10, 20);
    System.out.printf("Showing %d of %d%n", page.getVoices().size(), page.getTotal());
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Filter by language
    curl "https://api.kugelaudio.com/v1/voices?language=de" \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

    # Get only public voices
    curl "https://api.kugelaudio.com/v1/voices?include_public=true" \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

    # Limit results
    curl "https://api.kugelaudio.com/v1/voices?limit=10" \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

    # Get only cloned voices
    curl "https://api.kugelaudio.com/v1/voices?category=cloned" \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"
    ```
  </Tab>
</Tabs>

## Get Voice Details

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    voice = client.voices.get(voice_id=1071)
    print(f"Voice: {voice.name}")
    print(f"Description: {voice.description}")
    print(f"Sample text: {voice.sample_text}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    const voice = await client.voices.get(1071);
    console.log(`Voice: ${voice.name}`);
    console.log(`Description: ${voice.description}`);
    console.log(`Sample text: ${voice.sampleText}`);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Voice voice = client.voices().get(1071);
    System.out.printf("Voice: %s%n", voice.getName());
    System.out.printf("Description: %s%n", voice.getDescription());
    System.out.printf("Sample text: %s%n", voice.getSampleText());
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.kugelaudio.com/v1/voices/1071 \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY"
    ```
  </Tab>
</Tabs>

## Use a Specific Voice

Pass the `voice_id` (Python), `voiceId` (JavaScript), or `voice_id` JSON field (cURL) when generating speech:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    audio = client.tts.generate(
        text="Hello with a specific voice!",
        model_id="kugel-3",
        voice_id=1071,
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    const audio = await client.tts.generate({
      text: 'Hello with a specific voice!',
      modelId: 'kugel-3',
      voiceId: 1071,
    });
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    AudioResponse audio = client.tts().generate(
        GenerateRequest.builder("Hello with a specific voice!")
            .modelId("kugel-3")
            .voiceId(1071)
            .language("en")
            .build()
    );
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.kugelaudio.com/v1/tts/generate \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "Hello with a specific voice!",
        "model_id": "kugel-3",
        "voice_id": 1071
      }' \
      --output output.pcm
    ```
  </Tab>
</Tabs>

Voices work with all generation methods - basic generation, streaming, and streaming sessions:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # With streaming
    for chunk in client.tts.stream(
        text="Streaming with a specific voice.",
        model_id="kugel-3",
        voice_id=1071,
    ):
        if hasattr(chunk, 'audio'):
            play_audio(chunk.audio)

    # With streaming sessions (for LLM integration)
    async with client.tts.streaming_session(
        voice_id=1071,
        cfg_scale=2.0,
    ) as session:
        async for chunk in session.send("Hello!"):
            play_audio(chunk.audio)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    // With streaming
    await client.tts.stream(
      { text: 'Streaming with a specific voice.', modelId: 'kugel-3', voiceId: 1071 },
      { onChunk: (chunk) => playAudio(chunk.audio) }
    );
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // With streaming
    client.tts().stream(
        GenerateRequest.builder("Streaming with a specific voice.")
            .modelId("kugel-3")
            .voiceId(1071)
            .language("en")
            .build(),
        new StreamCallbacks() {
            @Override
            public void onChunk(AudioChunk chunk) {
                playAudio(chunk.getAudio());
            }
        }
    );

    // With streaming sessions (for LLM integration)
    try (StreamingSession session = client.tts().streamingSession(
            StreamConfig.builder().voiceId(1071).cfgScale(2.0).build())) {
        session.send("Hello!", true);
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Stream with a specific voice and pipe to ffplay
    curl -X POST https://api.kugelaudio.com/v1/tts/generate \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "Streaming with a specific voice.",
        "model_id": "kugel-3",
        "voice_id": 1071
      }' \
      --no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -
    ```
  </Tab>
</Tabs>

## Voice Properties

Each voice includes the following information:

| Property              | Type   | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `id`                  | int    | Unique voice ID                         |
| `name`                | string | Human-readable name                     |
| `description`         | string | Voice description                       |
| `category`            | string | `premade`, `cloned`, or `generated`     |
| `sex`                 | string | `male`, `female`, or `neutral`          |
| `age`                 | string | `young`, `middle_aged`, or `old`        |
| `supported_languages` | list   | ISO 639-1 language codes                |
| `sample_text`         | string | Sample text for preview                 |
| `sample_url`          | string | Sample audio URL                        |
| `is_public`           | bool   | Whether the voice is publicly available |
| `verified`            | bool   | Whether the voice has been verified     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Voice Cloning" icon="clone" href="/features/voice-cloning">
    Create custom voices from audio samples
  </Card>

  <Card title="Generate Speech" icon="play" href="/features/generate">
    Generate audio with your chosen voice
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/streaming/overview">
    Stream audio in real-time
  </Card>
</CardGroup>