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

# Integration Guide

> Step-by-step guide to integrating Cartesia voice AI

## Prerequisites

Before you begin, ensure you have:

* A Cartesia API key ([Sign up here](https://cartesia.ai))
* Node.js 18+ or Python 3.8+
* Basic understanding of async/await patterns

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @cartesia/cartesia-js
  ```

  ```bash python theme={null}
  pip install cartesia
  ```
</CodeGroup>

## Basic Setup

<Steps>
  <Step title="Initialize the Client">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      import Cartesia from '@cartesia/cartesia-js';

      const cartesia = new Cartesia({
        apiKey: process.env.CARTESIA_API_KEY,
      });
      ```

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

      client = cartesia.Cartesia(
          api_key=os.environ.get("CARTESIA_API_KEY")
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Choose a Voice">
    ```javascript theme={null}
    // List available voices
    const voices = await cartesia.voices.list();

    // Use a voice ID
    const voiceId = "a0e99841-438c-4a64-b679-ae501e7d6091";
    ```
  </Step>

  <Step title="Generate Speech">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      const response = await cartesia.tts.bytes({
        model_id: "sonic",
        transcript: "Hello, I'm CARTER!",
        voice: {
          mode: "id",
          id: voiceId
        },
        output_format: {
          container: "mp3",
          encoding: "mp3",
          sample_rate: 44100
        }
      });

      // Save or play the audio
      const audioBlob = new Blob([response.audio], { type: 'audio/mp3' });
      ```

      ```python Python theme={null}
      output = client.tts.bytes(
          model_id="sonic",
          transcript="Hello, I'm CARTER!",
          voice_id=voice_id,
          output_format={
              "container": "mp3",
              "encoding": "mp3",
              "sample_rate": 44100
          }
      )

      # Save audio
      with open("output.mp3", "wb") as f:
          f.write(output["audio"])
      ```
    </CodeGroup>
  </Step>
</Steps>

## Streaming Integration

For real-time applications like CARTER:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Server-Sent Events (SSE) streaming
  const response = await cartesia.tts.sse({
    model_id: "sonic",
    transcript: "Streaming response in real-time",
    voice: {
      mode: "id",
      id: voiceId
    },
    output_format: {
      container: "raw",
      encoding: "pcm_s16le",
      sample_rate: 16000
    }
  });

  // Process chunks as they arrive
  for await (const chunk of response) {
    // Play audio chunk
    audioPlayer.play(chunk);
  }
  ```

  ```python Python theme={null}
  # Streaming with Python
  output_stream = client.tts.sse(
      model_id="sonic",
      transcript="Streaming response in real-time",
      voice_id=voice_id,
      output_format={
          "container": "raw",
          "encoding": "pcm_s16le",
          "sample_rate": 16000
      },
      stream=True
  )

  for chunk in output_stream:
      # Process each audio chunk
      audio_player.play(chunk)
  ```
</CodeGroup>

## WebSocket Integration

For lowest latency (like CARTER's voice interface):

```javascript theme={null}
// Connect to WebSocket
const ws = await cartesia.tts.websocket({
  model_id: "sonic",
  voice: {
    mode: "id",
    id: voiceId
  },
  output_format: {
    container: "raw",
    encoding: "pcm_s16le",
    sample_rate: 16000
  }
});

// Send text to convert
await ws.send({
  transcript: "Ultra-low latency response",
  context_id: "conversation-1"
});

// Listen for audio
ws.on('message', (audioChunk) => {
  playAudio(audioChunk);
});

// Close when done
await ws.close();
```

## Adding Emotions

Control voice emotions like CARTER:

```javascript theme={null}
const response = await cartesia.tts.sse({
  model_id: "sonic",
  transcript: "I'm so excited about this!",
  voice: {
    mode: "id",
    id: voiceId
  },
  _experimental_voice_controls: {
    emotion: ["positivity:highest", "excitement"],
    speed: "fast"
  }
});
```

### Available Emotions

* **positivity** (lowest, low, high, highest)
* **curiosity**
* **surprise**
* **anger**
* **sadness**

## Error Handling

Implement robust error handling:

```javascript theme={null}
try {
  const response = await cartesia.tts.bytes({
    model_id: "sonic",
    transcript: message,
    voice: { mode: "id", id: voiceId }
  });
  
  return response.audio;
} catch (error) {
  if (error.status === 429) {
    // Rate limit - implement backoff
    await delay(1000);
    return retry();
  } else if (error.status === 401) {
    // Invalid API key
    console.error('Invalid API key');
  } else {
    // Other errors
    console.error('TTS error:', error);
  }
}
```

## Rate Limiting

Handle rate limits gracefully:

```javascript theme={null}
async function generateWithRetry(text, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await cartesia.tts.bytes({
        model_id: "sonic",
        transcript: text,
        voice: { mode: "id", id: voiceId }
      });
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        // Exponential backoff
        await delay(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Context IDs Consistent">
    Use the same context\_id for related messages to maintain conversation flow and improve latency.
  </Accordion>

  <Accordion title="Optimize Audio Format">
    * Use PCM for lowest latency
    * Use MP3 for file storage
    * Match sample rate to your playback system
  </Accordion>

  <Accordion title="Handle Disconnections">
    Implement reconnection logic for WebSocket connections:

    ```javascript theme={null}
    ws.on('close', () => {
      setTimeout(() => reconnect(), 1000);
    });
    ```
  </Accordion>

  <Accordion title="Cache Voice IDs">
    Fetch and cache voice IDs at startup rather than on each request.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Voice API Reference" icon="book" href="/developers/voice-api">
    Detailed API documentation
  </Card>

  <Card title="Code Examples" icon="code" href="/developers/examples">
    Working code samples
  </Card>
</CardGroup>

<Note>
  For production use, always implement proper error handling, rate limiting, and monitoring.
</Note>