Cartesia TTS

In deepeval, you can use Cartesia to convert text into speech when running voice simulations. Synthesis is what speaks the simulated user's messages to your agent, so its clarity is what your agent's own speech recognition has to work with.

Cartesia is reached over plain HTTP rather than through a vendor SDK, so pip install deepeval is all you need — there is no extra package to install or version to pin.

Setting Up Your API Key

DeepEval autoloads .env.local then .env at import time (process env -> .env.local -> .env).

Recommended (local dev):

# .env.local
CARTESIA_API_KEY=<your-cartesia-api-key>

Alternative (Shell/CI):

export CARTESIA_API_KEY=<your-cartesia-api-key>

Alternative (notebook):

If you're working in a notebook environment (Jupyter or Colab), set your CARTESIA_API_KEY in a cell:

%env CARTESIA_API_KEY=<your-cartesia-api-key>

Command Line

To speak with Cartesia in every voice simulation, run:

deepeval set-tts cartesia --model=sonic-3.6

--model is optional and defaults to Cartesia's own default model.

The command above sets Cartesia as the default text-to-speech provider, unless overridden in Python code. To use a different one, run deepeval set-tts for that provider, or drop back to the OpenAI default:

deepeval unset-tts

In Code

Pass a CartesiaTTSModel to VoiceConfig to synthesize with Sonic instead of the default OpenAI model. Cartesia has no default voice, so voice is the one thing you have to supply:

from deepeval.models import CartesiaTTSModel
from deepeval.voice import VoiceConfig

tts_model = CartesiaTTSModel(
    model="sonic-3.6",
    voice="<your-cartesia-voice-id>",
)
voice_config = VoiceConfig(
    tts_model=tts_model,
    ...,
)

There are ZERO mandatory and TEN optional parameters when creating a CartesiaTTSModel:

[Optional] model: A string specifying the name of the speech model to use. Defaulted to sonic-3.6.
[Optional] api_key: A string specifying your Cartesia API key. Defaults to CARTESIA_API_KEY if not passed; raises an error at runtime if neither is set.
[Optional] base_url: A string specifying a custom endpoint to reach the Cartesia API through. Defaulted to https://api.cartesia.ai.
[Optional] voice: A string voice ID from your Cartesia account. Defaulted to None, which raises at synthesis time unless a Persona supplies one.
[Optional] sample_rate: An integer sample rate to synthesize at — one of 8000, 16000, 22050, 24000, 44100, or 48000. Anything else raises immediately. Defaulted to 24000.
[Optional] language: A string ISO-639-1 code for the language spoken. Defaulted to None.
[Optional] api_version: A string dating the Cartesia API to call, sent on every request. Defaulted to 2026-08-14, pinned so a server-side release can't change the response shape underneath a run.
[Optional] cost_per_1m_chars: A float setting the per-character price used for cost accounting. Defaulted to None.
[Optional] generation_kwargs: A dictionary of additional parameters forwarded to Cartesia's /tts/bytes request body.
[Optional] timeout: A float number of seconds to wait on a request before giving up. Defaulted to 120.0.

First set your API key and select Cartesia as the speech provider:

# .env.local
CARTESIA_API_KEY=<your-cartesia-api-key>
USE_CARTESIA_TTS=1
DEEPEVAL_TTS_MODEL=sonic-3.6

deepeval set-tts cartesia --model sonic-3.6 writes those same variables for you. DEEPEVAL_TTS_MODEL is optional: leave it out and synthesis runs on sonic-3.6 anyway, since that is Cartesia's default here.

You can also pass the model name in code, which wins over DEEPEVAL_TTS_MODEL:

from deepeval.voice import VoiceConfig

voice_config = VoiceConfig(
    tts_model="sonic-3.6",
    ...,
)

With USE_CARTESIA_TTS set, a bare model name is shorthand for CartesiaTTSModel(model=...), which has no voice of its own, so every golden's Persona has to carry a voice. Pass the model object itself to set one default voice for the whole run.

Available Cartesia Models

sonic-3.6 (default)

Setting Up Your API Key

Command Line

In Code

Available Cartesia Models

On this page