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

# Camb AI

> Text-to-speech service using Camb AI's MARS models for high-quality speech synthesis

## Overview

`CambTTSService` provides high-quality text-to-speech synthesis using Camb AI's MARS model family with streaming capabilities. The service offers multiple model options optimized for different use cases: `mars-flash` for fast inference and `mars-pro` for high-quality output.

<CardGroup cols={2}>
  <Card title="Camb AI TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.camb.tts.html">
    Pipecat's API methods for Camb AI TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-camb.py">
    Complete example with interruption handling
  </Card>

  <Card title="Camb AI Documentation" icon="book" href="https://docs.camb.ai/">
    Official Camb AI API documentation
  </Card>

  <Card title="Camb AI Platform" icon="microphone" href="https://studio.camb.ai/">
    Access the Camb AI studio platform
  </Card>
</CardGroup>

## Installation

To use Camb AI services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[camb]"
```

## Prerequisites

### Camb AI Account Setup

Before using Camb AI TTS services, you need:

1. **Camb AI Account**: Sign up at [Camb AI](https://studio.camb.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Selection**: Choose voice IDs from the platform

### Required Environment Variables

* `CAMB_API_KEY`: Your Camb AI API key for authentication

## Configuration

### CambTTSService

<ParamField path="api_key" type="str" required>
  Camb.ai API key for authentication.
</ParamField>

<ParamField path="voice_id" type="int" default="147320" deprecated>
  Voice ID to use for synthesis.

  *Deprecated in v0.0.105. Use `settings=CambTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="model" type="str" default="mars-flash" deprecated>
  TTS model to use. Options: `"mars-flash"` (fast, 22.05kHz), `"mars-pro"` (high
  quality, 48kHz), `"mars-instruct"` (instruction-following, 22.05kHz).

  *Deprecated in v0.0.105. Use `settings=CambTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="timeout" type="float" default="60.0">
  Request timeout in seconds. 60 seconds is the minimum recommended by Camb.ai.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. If `None`, uses the model-specific default
  (22050 for mars-flash, 48000 for mars-pro).
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable voice settings. See [InputParams](#inputparams) below.

  *Deprecated in v0.0.105. Use `settings=CambTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="settings" type="CambTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `CambTTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter           | Type              | Default     | Description                                  |
| ------------------- | ----------------- | ----------- | -------------------------------------------- |
| `model`             | `str`             | `None`      | Model identifier. *(Inherited.)*             |
| `voice`             | `int`             | `None`      | Voice identifier.                            |
| `language`          | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)*       |
| `user_instructions` | `str`             | `NOT_GIVEN` | Instructions to guide voice synthesis style. |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.camb import CambTTSService

tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    settings=CambTTSService.Settings(
        model="mars-flash",
        voice=12345,
    ),
)
```

### With Language Customization

```python theme={null}
from pipecat.transcriptions.language import Language

tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    settings=CambTTSService.Settings(
        model="mars-flash",
        language=Language.FR,
    ),
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

<Tip>
  Set the `audio_out_sample_rate` in `PipelineParams` to match the model's
  sample rate (22050 for `mars-flash`, 48000 for `mars-pro`) for optimal
  quality. See the [example
  implementation](https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-camb.py)
  for usage.
</Tip>

* **Model-specific sample rates**: Each model has a fixed output sample rate. Setting a mismatched `sample_rate` will produce a warning and may cause audio issues.
* **Text length limit**: Input text is limited to 3000 characters per request. Longer text is automatically truncated with a warning.
* **140+ languages**: Camb.ai supports a wide range of languages through BCP-47 codes.