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

# Text-to-Speech Guide

> Complete guide to using VoxNexus Text-to-Speech API

## Overview

The Text-to-Speech (TTS) API converts text into natural-sounding speech audio. VoxNexus supports both REST API and WebSocket API for TTS operations.

## REST API

The REST API endpoint `/v1/tts` supports synchronous and streaming audio generation.

### Basic Usage

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.voxnexus.ai/v1/tts \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello, this is a test message",
      "model_id": "vn-tts-basic",
      "voice_id": "vn-xiaoxiao",
      "format": "wav",
      "sample_rate": 16000
    }'
  ```
</RequestExample>

### Request Parameters

<ParamField path="text" type="string" required>
  The text content to convert to speech.
</ParamField>

<ParamField path="model_id" type="string" required>
  Model identifier. Specifies which model to use for TTS. Use the `/v1/models` endpoint to browse available models.
</ParamField>

<ParamField path="voice_id" type="string" required>
  Unique identifier of the voice to use. Use the `/v1/voices` endpoint to browse available voices.
</ParamField>

<ParamField path="language" type="string">
  Language or locale code. Supports both ISO 639-1 language codes (e.g., `en`, `zh`) and BCP 47 locale codes (e.g., `en-US`, `zh-CN`). When a language code is provided, the system will automatically resolve it to the most common locale (e.g., `en` → `en-US`). Default: `en-US`.
</ParamField>

<ParamField path="format" type="string">
  Audio format. Supported values: `wav`, `pcm`. Default: `wav`.
</ParamField>

<ParamField path="sample_rate" type="integer">
  Sample rate in Hz. Supported values: `16000`, `24000`, `48000`. Default: `16000`.
</ParamField>

<ParamField path="bit_rate" type="integer" deprecated>
  Bit rate in kbps. **Not supported yet** - reserved for future compressed format support. Default: `128`.
</ParamField>

<ParamField path="speed" type="number">
  Speech rate multiplier. Range: `0.5` - `2.0`. Default: `1.0`.
</ParamField>

<ParamField path="pitch" type="integer">
  Pitch offset in semitones. Range: `-12` - `12`. Default: `0`.
</ParamField>

<ParamField path="volume" type="number">
  Volume multiplier. Range: `0.0` - `1.0`. Default: `1.0`.
</ParamField>

<ParamField path="voice_config" type="object">
  Voice-specific configuration object. Properties depend on the selected voice. Check voice details using `/v1/voices/{voice_id}` endpoint.
</ParamField>

### Response

The API returns audio data in the requested format. Response headers include metadata:

* `X-Request-ID`: Unique request identifier
* `X-Voice-ID`: Voice ID used for synthesis
* `X-Language`: Language code
* `X-Audio-Format`: Audio format
* `X-Sample-Rate`: Sample rate
* `Transfer-Encoding`: Transfer encoding (defaults to chunked streaming)

<ResponseExample>
  ```bash theme={null}
  HTTP/1.1 200 OK
  X-Request-ID: req_1234567890
  X-Voice-ID: vn-xiaoxiao
  X-Language: zh-CN
  X-Audio-Format: wav
  X-Sample-Rate: 16000
  Transfer-Encoding: chunked
  Content-Type: audio/wav

  [Audio binary data]
  ```
</ResponseExample>

### Streaming Response

By default, the API uses chunked transfer encoding for streaming audio data. This allows you to start playing audio while it's still being generated, reducing latency.

## WebSocket API

The WebSocket API provides real-time bidirectional communication for TTS operations, ideal for interactive applications.

### Connection

Connect to `wss://api.voxnexus.ai/v1/tts/realtime` with authentication:

```javascript theme={null}
// Connect with token as query parameter (recommended)
const ws = new WebSocket('wss://api.voxnexus.ai/v1/tts/realtime?token=YOUR_API_KEY');
```

### Message Flow

1. **Initialize**: Send an `init` message to configure voice parameters
2. **Send Text**: Send `text` messages with content to synthesize
3. **Receive Audio**: Receive `audio` messages with Base64-encoded audio data
4. **Handle Errors**: Monitor for `error` messages

### Initialization Message

```json theme={null}
{
  "type": "init",
  "model_id": "vn-tts-basic",
  "voice_id": "vn-xiaoxiao",
  "language": "zh-CN",
  "format": "wav",
  "sample_rate": 16000,
  "speed": 1.0,
  "pitch": 0,
  "volume": 1.0,
  "voice_config": {
    "style": "cheerful",
    "role": "Girl",
    "degree": 0.5
  }
}
```

### Text Message

```json theme={null}
{
  "type": "text",
  "text": "Hello, this is a test",
  "is_final": false
}
```

### Audio Response

```json theme={null}
{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "is_final": false
}
```

### Complete Example

```javascript theme={null}
// Connect with token as query parameter
const ws = new WebSocket('wss://api.voxnexus.ai/v1/tts/realtime?token=YOUR_API_KEY');

ws.onopen = () => {
  // Initialize
  ws.send(JSON.stringify({
    type: 'init',
    model_id: 'vn-tts-basic',
    voice_id: 'vn-xiaoxiao',
    format: 'wav',
    sample_rate: 16000
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch (message.type) {
    case 'ready':
      console.log('Ready:', message.request_id);
      // Send text to synthesize
      ws.send(JSON.stringify({
        type: 'text',
        text: 'Hello, this is a test',
        is_final: true
      }));
      break;
      
    case 'audio':
      // Decode and play audio
      const audioData = atob(message.data);
      // Handle audio playback
      break;
      
    case 'error':
      console.error('Error:', message.error);
      break;
  }
};
```

## Best Practices

### Model and Voice Selection

* Use the `/v1/models` endpoint to browse available TTS models
* Use the `/v1/voices` endpoint to browse available voices, optionally filtered by `model_id`
* Filter voices by language, gender, category, or style
* Test voices using sample audio URLs before production use

### Performance Optimization

* Use streaming for long texts to reduce perceived latency
* Choose appropriate sample rates (16kHz is sufficient for most use cases)
* Use PCM format for real-time WebSocket streaming, WAV for REST API

### Error Handling

Always implement proper error handling:

```javascript theme={null}
try {
  const response = await fetch('https://api.voxnexus.ai/v1/tts', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Hello',
      model_id: 'vn-tts-basic',
      voice_id: 'vn-xiaoxiao'
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Request failed');
  }
  
  // Handle audio data
} catch (error) {
  console.error('TTS Error:', error);
}
```

## Rate Limits and Quotas

* Implement exponential backoff for `429` responses
* Consider using WebSocket API for high-frequency use cases

## Common Use Cases

### Interactive Voice Response (IVR)

Use WebSocket API for real-time synthesis in IVR systems:

```javascript theme={null}
// Synthesize prompts in real-time
ws.send(JSON.stringify({
  type: 'text',
  text: 'Please press 1 for sales',
  is_final: false
}));
```

### Content Narration

Use REST API for batch processing of long-form content:

```bash theme={null}
# Process entire articles or books (article.json must include model_id and voice_id)
curl -X POST https://api.voxnexus.ai/v1/tts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @article.json \
  --output narration.wav
```

### Accessibility Features

Generate audio versions of text content for accessibility:

```javascript theme={null}
async function generateAudioAccessibility(text) {
  const response = await fetch('https://api.voxnexus.ai/v1/tts', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: text,
      model_id: 'vn-tts-basic',
      voice_id: 'vn-xiaoxiao',
      format: 'wav',
      sample_rate: 24000 // Higher quality for better clarity
    })
  });
  
  return response.blob();
}
```