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

# Voice API Reference

> Complete reference for Cartesia Voice API

## Overview

CARTER uses Cartesia's **Sonic model** for ultra-realistic voice generation with emotional expression. This reference covers the key endpoints and parameters.

## Text-to-Speech Endpoints

### Generate Audio (Bytes)

Generate complete audio files:

```javascript theme={null}
POST /tts/bytes

{
  "model_id": "sonic",
  "transcript": "Your text here",
  "voice": {
    "mode": "id",
    "id": "voice-id"
  },
  "output_format": {
    "container": "mp3",
    "encoding": "mp3",
    "sample_rate": 44100
  }
}
```

### Stream Audio (SSE)

Server-Sent Events for streaming:

```javascript theme={null}
POST /tts/sse

{
  "model_id": "sonic",
  "transcript": "Streaming text",
  "voice": {
    "mode": "id",
    "id": "voice-id"
  },
  "output_format": {
    "container": "raw",
    "encoding": "pcm_s16le",
    "sample_rate": 16000
  },
  "stream": true
}
```

### WebSocket Connection

For lowest latency:

```javascript theme={null}
WSS wss://api.cartesia.ai/tts/websocket

// Send message
{
  "model_id": "sonic",
  "voice": {
    "mode": "id",
    "id": "voice-id"
  },
  "transcript": "Real-time text",
  "context_id": "conversation-1"
}
```

## Parameters

### Model ID

<ParamField path="model_id" type="string" required>
  The model to use for generation. Use `"sonic"` for latest features.

  Options: `"sonic"`, `"sonic-2"`, `"sonic-turbo"`
</ParamField>

### Transcript

<ParamField path="transcript" type="string" required>
  The text to convert to speech. Supports SSML tags for advanced control.
</ParamField>

### Voice

<ParamField path="voice" type="object" required>
  Voice configuration object

  ```javascript theme={null}
  {
    "mode": "id",  // or "embedding"
    "id": "voice-id"  // Cartesia voice ID
  }
  ```
</ParamField>

### Output Format

<ParamField path="output_format" type="object" required>
  Audio output configuration

  ```javascript theme={null}
  {
    "container": "mp3",  // mp3, raw, wav
    "encoding": "mp3",   // mp3, pcm_s16le, pcm_f32le
    "sample_rate": 44100 // 16000, 22050, 44100, 48000
  }
  ```
</ParamField>

### Experimental Voice Controls

<ParamField path="_experimental_voice_controls" type="object">
  Control emotions and speech characteristics

  ```javascript theme={null}
  {
    "emotion": ["positivity:highest", "excitement"],
    "speed": "fast",  // slow, normal, fast
    "volume": "high"  // low, normal, high
  }
  ```
</ParamField>

## Voice Emotions

Available emotional controls:

| Emotion    | Levels                     |
| ---------- | -------------------------- |
| Positivity | lowest, low, high, highest |
| Anger      | Use tag directly           |
| Sadness    | Use tag directly           |
| Surprise   | Use tag directly           |
| Curiosity  | Use tag directly           |

Example:

```javascript theme={null}
{
  "_experimental_voice_controls": {
    "emotion": ["positivity:highest", "curiosity"]
  }
}
```

## Response Format

### Bytes Response

```javascript theme={null}
{
  "audio": "<base64-encoded-audio>",
  "context_id": "conversation-1"
}
```

### Stream Response (SSE)

```
data: {"audio": "<base64-chunk>", "context_id": "conv-1"}

data: {"audio": "<base64-chunk>", "context_id": "conv-1"}

data: {"done": true}
```

### WebSocket Messages

```javascript theme={null}
// Audio chunk
{
  "type": "chunk",
  "data": "<base64-audio>",
  "context_id": "conv-1"
}

// Done
{
  "type": "done",
  "context_id": "conv-1"
}
```

## Voice Management

### List Voices

```javascript theme={null}
GET /voices

Response:
[
  {
    "id": "voice-id",
    "name": "Voice Name",
    "description": "Voice description",
    "language": "en"
  }
]
```

### Get Voice

```javascript theme={null}
GET /voices/{voice_id}

Response:
{
  "id": "voice-id",
  "name": "Voice Name",
  "description": "Description",
  "language": "en",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### Clone Voice

```javascript theme={null}
POST /voices/clone

{
  "name": "Custom Voice",
  "description": "My custom voice",
  "audio_files": ["base64-audio-1", "base64-audio-2"]
}
```

## Rate Limits

| Plan       | Requests/min | Concurrent Streams |
| ---------- | ------------ | ------------------ |
| Free       | 20           | 2                  |
| Pro        | 100          | 10                 |
| Enterprise | Custom       | Custom             |

## Error Codes

| Code | Description                      |
| ---- | -------------------------------- |
| 400  | Bad Request - Invalid parameters |
| 401  | Unauthorized - Invalid API key   |
| 429  | Rate Limit Exceeded              |
| 500  | Server Error                     |

Example error response:

```javascript theme={null}
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": 429
  }
}
```

## SDK Methods

<CodeGroup>
  ```javascript JavaScript theme={null}
  import Cartesia from '@cartesia/cartesia-js';

  const cartesia = new Cartesia({ apiKey: 'your-key' });

  // Generate audio bytes
  const audio = await cartesia.tts.bytes({
    model_id: "sonic",
    transcript: "Hello",
    voice: { mode: "id", id: voiceId }
  });

  // Stream audio
  const stream = await cartesia.tts.sse({
    model_id: "sonic",
    transcript: "Streaming",
    voice: { mode: "id", id: voiceId }
  });

  // WebSocket
  const ws = await cartesia.tts.websocket({
    model_id: "sonic",
    voice: { mode: "id", id: voiceId }
  });
  ```

  ```python Python theme={null}
  import cartesia

  client = cartesia.Cartesia(api_key="your-key")

  # Generate audio bytes
  output = client.tts.bytes(
      model_id="sonic",
      transcript="Hello",
      voice_id=voice_id
  )

  # Stream audio
  stream = client.tts.sse(
      model_id="sonic",
      transcript="Streaming",
      voice_id=voice_id,
      stream=True
  )

  # WebSocket
  ws = client.tts.websocket(
      model_id="sonic",
      voice_id=voice_id
  )
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Endpoint">
    * **Bytes**: For pre-generated audio files
    * **SSE**: For streaming in web applications
    * **WebSocket**: For lowest latency in real-time apps
  </Accordion>

  <Accordion title="Optimize Sample Rate">
    * 16000 Hz: Voice applications (lowest bandwidth)
    * 22050 Hz: Balanced quality/size
    * 44100 Hz: High quality music/effects
  </Accordion>

  <Accordion title="Use Context IDs">
    Maintain context\_id across related requests for better latency and coherence.
  </Accordion>

  <Accordion title="Handle Rate Limits">
    Implement exponential backoff and retry logic for 429 errors.
  </Accordion>
</AccordionGroup>

## Resources

* [Official Cartesia Docs](https://docs.cartesia.ai)
* [Cartesia Playground](https://play.cartesia.ai/text-to-speech)
* [API Status](https://status.cartesia.ai)

<Note>
  For the most up-to-date API reference, always check the [official Cartesia documentation](https://docs.cartesia.ai).
</Note>