Prerequisites
- A SambaCloud account and API key
- A Cartesia 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:- SambaNova to Cartesia. The chat completion is requested with
stream=True. Each text delta is pushed into a Cartesia websocket context. - 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.
no_more_inputs() tells Cartesia the utterance is complete.
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
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:.env
3
Create the script
Save the following as
speak.py:speak.py
4
Run it
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.
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.Full example: terminal voice chat
The Cartesia integration example 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
2
Create a virtual environment and install dependencies
3
Add your API keys
.env and set SAMBANOVA_API_KEY and CARTESIA_API_KEY. The other settings are optional:4
Start a conversation
exit to quit.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.
Troubleshooting
You need to install cartesia[websockets]
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.PortAudio is not installed, or OSError: PortAudio library not found
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.Could not open an audio output device
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.
Authentication error or HTTP 401
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.Error message from Cartesia
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.Long silence before the first word
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.
