Cartesia STT

In deepeval, you can use Cartesia to transcribe speech into text when running voice simulations. Transcription is what turns your agent's spoken replies into the Turn.content your multi-turn metrics judge, so its accuracy directly bounds how faithfully those metrics see the conversation.

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 transcribe with Cartesia in every voice simulation, run:

deepeval set-stt cartesia --model=ink-whisper

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

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

deepeval unset-stt

In Code

Pass a CartesiaSTTModel to VoiceConfig to transcribe with Ink instead of the default OpenAI model:

from deepeval.models import CartesiaSTTModel
from deepeval.voice import VoiceConfig

stt_model = CartesiaSTTModel(
    model="ink-whisper",
    language="en",
)
voice_config = VoiceConfig(
    stt_model=stt_model,
    ...,
)

There are ZERO mandatory and EIGHT optional parameters when creating a CartesiaSTTModel:

[Optional] model: A string specifying the name of the transcription model to use. Defaulted to ink-whisper.
[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] language: A string ISO-639-1 code (e.g. "en") pinning the spoken language. Defaulted to None, which Cartesia reads as English.
[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_minute: A float setting the per-minute price used for cost accounting. Defaulted to None.
[Optional] transcription_kwargs: A dictionary of additional multipart fields forwarded to Cartesia's /stt endpoint.
[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 transcription provider:

# .env.local
CARTESIA_API_KEY=<your-cartesia-api-key>
USE_CARTESIA_STT=1
DEEPEVAL_STT_MODEL=ink-whisper

deepeval set-stt cartesia --model ink-whisper writes those same variables for you. DEEPEVAL_STT_MODEL is optional: leave it out and transcription runs on ink-whisper anyway, since that is Cartesia's default here.

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

from deepeval.voice import VoiceConfig

voice_config = VoiceConfig(
    stt_model="ink-whisper",
    ...,
)

With USE_CARTESIA_STT set, a bare model name is shorthand for CartesiaSTTModel(model=...). Pass the model object itself to pin a language.

Available Cartesia Models

ink-whisper (default)

Cartesia's batch endpoint only serves the ink-whisper family. ink-2 is realtime-only and will not transcribe here.

Setting Up Your API Key

Command Line

In Code

Available Cartesia Models

On this page