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

# Cartesia integration guide

[Cartesia](https://cartesia.ai) is a low-latency text-to-speech platform. Its websocket API accepts text a piece at a time and streams audio back as it goes, so speech can start before the full text exists.

That pairs well with SambaCloud. SambaNova streams a model's answer token by token, and each piece can go straight into Cartesia. You hear the start of the answer while the model is still writing the end of it.

This guide explains how the two connect, walks through a minimal script, and then runs a complete terminal voice chat from the [SambaNova integrations repository](https://github.com/sambanova/integrations/tree/main/cartesia_integration).

> [!NOTE]
>
> This example uses the SambaNova and Cartesia SDKs directly, with no voice framework. For full voice agents with speech-to-text, turn-taking, and telephony, see [Pipecat](https://docs.sambanova.ai/docs/en/integrations/pipecat.md) and [LiveKit](https://docs.sambanova.ai/docs/en/integrations/livekit.md), which both support Cartesia.

## Prerequisites

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=cartesia\&utm_medium=external\&utm_campaign=cloud_signup) account and [API key](https://cloud.sambanova.ai/apis?utm_source=cartesia\&utm_medium=external\&utm_campaign=cloud_signup)
* A [Cartesia](https://play.cartesia.ai/keys) account and API key
* Python 3.11 or later
* Speakers or headphones
* On Debian or Ubuntu, the PortAudio library: `sudo apt install libportaudio2`. macOS and Windows need nothing extra.

## How it works

Two streams run at the same time:

1. **SambaNova to Cartesia.** The chat completion is requested with `stream=True`. Each text delta is pushed into a Cartesia websocket *context*.
2. **Cartesia to your speakers.** The same context returns raw audio chunks as soon as Cartesia has enough text to speak. Each chunk is played as it arrives.

A Cartesia context represents one utterance. Everything you push into it is spoken as continuous speech, so the voice stays natural even though the text arrives in fragments. When the model finishes, `no_more_inputs()` tells Cartesia the utterance is complete.

```text theme={}
question ─► SambaCloud (stream=True) ── text deltas ──► Cartesia context ── audio chunks ──► speakers
```

> [!NOTE]
>
> The examples use `Meta-Llama-3.3-70B-Instruct`, which starts answering right away. If you use a reasoning model such as `gpt-oss-120b`, its reasoning arrives in a separate field of the stream. Only `delta.content` is sent to Cartesia, so the reasoning is never spoken, but it is still silence before the first word. Passing `reasoning_effort="low"` to `chat.completions.create` keeps that silence short. The full example does this automatically for `gpt-oss` models.

## Minimal example

The script below asks one question and speaks the answer as it streams.

**1. Install the packages**

```bash theme={}
pip install sambanova==1.13.0 "cartesia[websockets]==4.2.0" sounddevice==0.5.6 python-dotenv==1.1.0
```

> [!NOTE]
>
> The `[websockets]` extra is required. Without it, the Cartesia SDK raises an error when you open a websocket connection.

**2. Set your API keys**

Create a `.env` file in the same directory as the script:

```bash .env theme={}
SAMBANOVA_API_KEY="your-sambanova-api-key"
CARTESIA_API_KEY="your-cartesia-api-key"
```

**3. Create the script**

Save the following as `speak.py`:

```python speak.py theme={}
import asyncio
import os

import sounddevice as sd
from cartesia import AsyncCartesia
from dotenv import load_dotenv
from sambanova import AsyncSambaNova

load_dotenv()

QUESTION = 'In two sentences, why is the sky blue?'
SAMPLE_RATE = 44100


async def main() -> None:
    llm = AsyncSambaNova(api_key=os.environ['SAMBANOVA_API_KEY'])
    tts = AsyncCartesia(api_key=os.environ['CARTESIA_API_KEY'])
    speaker = sd.RawOutputStream(samplerate=SAMPLE_RATE, channels=1, dtype='int16')
    speaker.start()

    async with tts.tts.websocket_connect() as conn:
        # One context = one utterance. Text pushed into it is spoken as it arrives.
        ctx = conn.context(
            model_id='sonic-3.6',
            voice={'mode': 'id', 'id': '6ccbfb76-1fc6-48f7-b71d-91ac6298247b'},
            output_format={'container': 'raw', 'encoding': 'pcm_s16le', 'sample_rate': SAMPLE_RATE},
            language='en',
        )

        async def write() -> None:
            stream = await llm.chat.completions.create(
                model='Meta-Llama-3.3-70B-Instruct',
                messages=[{'role': 'user', 'content': QUESTION}],
                stream=True,
            )
            async for chunk in stream:
                text = chunk.choices[0].delta.content if chunk.choices else None
                if text:  # only the answer is spoken, never the model's reasoning
                    print(text, end='', flush=True)
                    await ctx.push(text)
            await ctx.no_more_inputs()

        async def speak() -> None:
            async for event in ctx.receive():
                if event.type == 'chunk' and event.audio:
                    await asyncio.to_thread(speaker.write, event.audio)
                elif event.type == 'error':
                    raise RuntimeError(event.message or event.title or 'unknown error')

        await asyncio.gather(write(), speak())

    speaker.stop()  # waits for the last audio to finish playing
    speaker.close()
    await tts.close()
    print()


asyncio.run(main())
```

**4. Run it**

```bash theme={}
python speak.py
```

The answer prints in your terminal, and you hear it spoken while it is still printing.

`write()` and `speak()` run concurrently through `asyncio.gather`. That concurrency is what lets audio start before the model has finished. `speaker.write` blocks until the sound card has room, so it runs in a thread to keep the event loop free for the SambaNova stream.

> [!NOTE]
>
> Both examples request English speech with `language='en'`. An answer in another language is still read out, but with an English accent. To speak another language, change `language` and choose a voice for that language from the [Cartesia voice library](https://play.cartesia.ai/voices).

## Full example: terminal voice chat

The [Cartesia integration example](https://github.com/sambanova/integrations/tree/main/cartesia_integration) builds on the minimal script with a multi-turn conversation, per-answer latency timings, Ctrl-C to stop an answer mid-sentence, and reconnection when the Cartesia socket drops.

**1. Clone the repository**

```bash theme={}
git clone https://github.com/sambanova/integrations.git
cd integrations/cartesia_integration
```

**2. Create a virtual environment and install dependencies**

```bash theme={}
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

**3. Add your API keys**

```bash theme={}
cp .env.example .env
```

Open `.env` and set `SAMBANOVA_API_KEY` and `CARTESIA_API_KEY`. The other settings are optional:

| Variable | Default | Description |
| :- | :- | :- |
| `SAMBANOVA_MODEL` | `Meta-Llama-3.3-70B-Instruct` | Any [SambaCloud model](https://docs.sambanova.ai/docs/en/models/sambacloud-models.md) |
| `CARTESIA_MODEL` | `sonic-3.6` | Cartesia text-to-speech model |
| `CARTESIA_VOICE_ID` | `6ccbfb76-1fc6-48f7-b71d-91ac6298247b` | Any voice from the [Cartesia voice library](https://play.cartesia.ai/voices) |

**4. Start a conversation**

```bash theme={}
python main.py
```

Type a question and press Enter. Press Ctrl-C to stop an answer, and type `exit` to quit.

```text theme={}
Connected to Cartesia in 1005 ms. Model: Meta-Llama-3.3-70B-Instruct.
Type a question and press Enter. Ctrl-C stops an answer, "exit" quits.

you > why is the sky blue?

  The sky is blue because of the way light behaves when it enters our atmosphere. When sunlight comes in, it's made up of all different colors, but our atmosphere scatters the shorter, blue wavelengths more than the others. This scattering effect is what gives the sky its blue color, and it's why it usually looks blue on a sunny day. It's pretty cool how it all works together like that.

  first token    846 ms   (SambaNova inference: 150 ms)
  first sound   1169 ms   (Cartesia)
  audio 22.6 s generated in 4.0 s  (5.6x realtime)
```

### Reading the timings

After each answer the example prints three measurements, all counted from the moment the question is sent:

* **First token**: when the first word of the answer reached your machine. The value in brackets is SambaNova's own inference time, which excludes the network. The difference between the two is the round trip, which depends on your connection.
* **First sound**: when the first audio arrived from Cartesia. This is how long you wait before hearing anything.
* **Realtime**: seconds of speech produced per second of waiting. Above 1x, audio arrives faster than it plays, so playback never stalls.

The Cartesia connection is opened once at startup and reused for every answer, so its handshake is not included in these numbers.

## Troubleshooting

> [accordion] You need to install cartesia\[websockets]
>
> The websocket client is an optional extra of the Cartesia SDK. Install it with `pip install "cartesia[websockets]==4.2.0"`, or install from the example's `requirements.txt`, which includes it.

> [accordion] PortAudio is not installed, or OSError: PortAudio library not found
>
> `sounddevice` needs the PortAudio library. On Debian or Ubuntu, run `sudo apt install libportaudio2`. On macOS and Windows it is bundled with the package.

> [accordion] Could not open an audio output device
>
> Check that speakers or headphones are connected and selected as the default output device. Remote sessions such as SSH and containers usually have no audio device.

> [accordion] Authentication error or HTTP 401
>
> Check `SAMBANOVA_API_KEY` and `CARTESIA_API_KEY` in your `.env` file. The full example prints `Could not connect to Cartesia: … HTTP 401` when the Cartesia key is rejected.

> [accordion] Error message from Cartesia
>
> Errors reported by Cartesia, such as an unknown voice ID or a model your plan cannot use, are shown with Cartesia's own message. Check `CARTESIA_VOICE_ID` and `CARTESIA_MODEL`.

> [accordion] Long silence before the first word
>
> Reasoning models think before they answer. If you set `SAMBANOVA_MODEL` to a reasoning model such as `gpt-oss-120b`, switch back to the default, `Meta-Llama-3.3-70B-Instruct`. The time to first token reported by SambaNova also varies with load, so a single slow answer is not unusual.

## Cartesia documentation

For more about voices, models, and the websocket API, see the [Cartesia documentation](https://docs.cartesia.ai).
