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

# Voice Library

> Explore VoxNexus voice library and find the perfect voice for your application

## Overview

VoxNexus offers a diverse library of high-quality voices covering multiple languages, accents, genders, and styles. Each voice is carefully crafted using advanced AI technology to deliver natural, expressive speech.

## Voice Categories

### By Language

Our voice library supports 50+ languages and locales:

* **English**: Multiple accents (US, UK, Australian, etc.)
* **Chinese**: Mandarin, Cantonese, and regional variants
* **Spanish**: European and Latin American variants
* **French**: European and Canadian French
* **German**: Standard German and regional accents
* **Japanese**: Standard Japanese
* **Korean**: Standard Korean
* **And many more...**

### By Gender

Choose voices that match your application's needs:

* **Male Voices**: Deep, authoritative, or friendly male voices
* **Female Voices**: Warm, professional, or energetic female voices
* **Neutral Voices**: Gender-neutral options for inclusive applications

### By Category

Voices are organized into categories:

* **Premade Voices**: Professional, pre-built voices ready for immediate use
* **Cloned Voices**: Custom voices created from audio samples
* **Generated Voices**: AI-generated voices with unique characteristics

### By Style

Match voice style to your content:

* **Professional**: Formal, business-appropriate voices
* **Casual**: Friendly, conversational voices
* **Cheerful**: Energetic, upbeat voices
* **Calm**: Soothing, relaxed voices
* **Authoritative**: Confident, commanding voices
* **Friendly**: Warm, approachable voices

## Discovering Voices

### Browse All Voices

Use the `/v1/voices` endpoint to browse available voices:

```bash theme={null}
curl -X GET "https://api.voxnexus.ai/v1/voices" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### Search Voices

Search for voices by keyword:

```bash theme={null}
curl -X GET "https://api.voxnexus.ai/v1/voices/search?q=xiaoxiao" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### Filter Voices

Filter voices by attributes:

```bash theme={null}
# Filter by language
curl -X GET "https://api.voxnexus.ai/v1/voices?language=zh" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by locale
curl -X GET "https://api.voxnexus.ai/v1/voices?locale=zh-CN" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by gender
curl -X GET "https://api.voxnexus.ai/v1/voices?gender=female" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by category
curl -X GET "https://api.voxnexus.ai/v1/voices?category=premade" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by style
curl -X GET "https://api.voxnexus.ai/v1/voices?style=cheerful" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by model
curl -X GET "https://api.voxnexus.ai/v1/voices?model_id=vn-tts-ultra" \
  -H "X-Api-Key: YOUR_API_KEY"

# Combine filters
curl -X GET "https://api.voxnexus.ai/v1/voices?locale=zh-CN&gender=female&style=cheerful" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### Get Voice Details

Retrieve detailed information about a specific voice:

```bash theme={null}
curl -X GET "https://api.voxnexus.ai/v1/voices/vn-xiaoxiao" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Voice Response Format

When you query the voice API, you'll receive responses in this format:

```json theme={null}
{
  "voices": [
    {
      "voice_id": "vn-xiaoxiao",
      "name": "Xiaoxiao",
      "display_name": "Xiaoxiao",
      "gender": "female",
      "category": "premade",
      "description": "A warm and friendly female voice, suitable for general scenarios",
      "primary_locale": "zh-CN",
      "is_multilingual": true,
      "supported_locales": [
        {
          "locale": "zh-CN",
          "language": "zh",
          "locale_name": "Chinese (Simplified, China)",
          "accent": "mandarin",
          "preview_url": "https://api.voxnexus.ai/samples/vn-xiaoxiao/zh-CN.mp3",
          "is_primary": true
        }
      ],
      "labels": {
        "personalities": ["warm", "friendly"],
        "scenarios": ["assistant", "news"]
      },
      "preview_url": "https://api.voxnexus.ai/samples/vn-xiaoxiao.mp3",
      "config_schema": {
        "style": {
          "type": "string",
          "enum": ["cheerful", "sad", "angry"]
        },
        "role": {
          "type": "string",
          "enum": ["Girl", "Boy"]
        },
        "degree": {
          "type": "number",
          "min": 0,
          "max": 1
        }
      },
      "models": ["vn-tts-basic", "vn-tts-ultra"]
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 150,
    "total_pages": 8
  }
}
```

## Voice Configuration

Many voices support additional configuration options through the `voice_config` parameter:

### Style Configuration

Some voices support different speaking styles:

```json theme={null}
{
  "text": "Hello, world!",
  "voice_id": "vn-xiaoxiao",
  "voice_config": {
    "style": "cheerful"
  }
}
```

### Role Configuration

Some voices can adopt different roles:

```json theme={null}
{
  "text": "Hello, world!",
  "voice_id": "vn-xiaoxiao",
  "voice_config": {
    "role": "Girl",
    "degree": 0.5
  }
}
```

### Checking Voice Configuration Options

Each voice's `config_schema` field describes the available configuration options. Check the voice details to see what's supported:

```javascript theme={null}
const response = await fetch('https://api.voxnexus.ai/v1/voices/vn-xiaoxiao', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

const voice = await response.json();
console.log('Available config options:', voice.config_schema);
```

## Popular Voices

### Chinese Voices

<CardGroup cols={2}>
  <Card title="Xiaoxiao" icon="user">
    A cheerful and energetic female voice, perfect for friendly applications.
  </Card>

  <Card title="Yunxi" icon="user">
    A calm and professional male voice, ideal for business content.
  </Card>
</CardGroup>

### English Voices

<CardGroup cols={2}>
  <Card title="Jenny" icon="user">
    A professional female voice with clear pronunciation.
  </Card>

  <Card title="Guy" icon="user">
    A friendly male voice suitable for various applications.
  </Card>
</CardGroup>

## Voice Selection Best Practices

### Match Voice to Content

Choose voices that match your content type:

* **Educational Content**: Clear, articulate voices
* **Entertainment**: Expressive, character voices
* **Business**: Professional, authoritative voices
* **Accessibility**: Clear, easy-to-understand voices

### Consider Your Audience

Select voices appropriate for your target audience:

* **Age**: Match voice age to audience age
* **Language**: Use native speakers' preferred accents
* **Culture**: Consider cultural preferences
* **Accessibility**: Ensure voices are clear and understandable

### Test Before Production

Always test voices with sample content:

1. Generate sample audio with your content
2. Listen to the output quality
3. Test with your target audience
4. Adjust voice parameters as needed

### Use Voice Samples

Listen to voice samples before integration:

```javascript theme={null}
async function previewVoice(voiceId) {
  const response = await fetch(`https://api.voxnexus.ai/v1/voices/${voiceId}`, {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const voice = await response.json();
  if (voice.preview_url) {
    const audio = new Audio(voice.preview_url);
    audio.play();
  }
}
```

## Voice Customization

### Speed Control

Adjust speech rate to match your needs:

```json theme={null}
{
  "text": "Hello, world!",
  "voice_id": "vn-xiaoxiao",
  "speed": 1.2
}
```

### Pitch Adjustment

Modify pitch for different effects:

```json theme={null}
{
  "text": "Hello, world!",
  "voice_id": "vn-xiaoxiao",
  "pitch": 2
}
```

### Volume Control

Adjust volume levels:

```json theme={null}
{
  "text": "Hello, world!",
  "voice_id": "vn-xiaoxiao",
  "volume": 0.8
}
```

## Multi-Voice Applications

### Character Voices

Use different voices for different characters:

```javascript theme={null}
const characters = {
  narrator: 'vn-yunxi',
  hero: 'vn-xiaoxiao',
  villain: 'vn-deep-voice'
};

async function narrateStory(story) {
  for (const segment of story.segments) {
    const audio = await synthesize({
      text: segment.text,
      voice_id: characters[segment.character]
    });
    await playAudio(audio);
  }
}
```

### Language Switching

Switch voices based on user language preference:

```javascript theme={null}
const voiceMap = {
  'en-US': 'vn-jenny',
  'zh-CN': 'vn-xiaoxiao',
  'es-ES': 'vn-maria'
};

function getVoiceForLanguage(language) {
  return voiceMap[language] || voiceMap['en-US'];
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Learn how to use voices in your API calls
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started with your first voice synthesis
  </Card>
</CardGroup>