Deepgram STT

In deepeval, you can use Deepgram 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
DEEPGRAM_API_KEY=<your-deepgram-api-key>

Alternative (Shell/CI):

export DEEPGRAM_API_KEY=<your-deepgram-api-key>

Alternative (notebook):

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

%env DEEPGRAM_API_KEY=<your-deepgram-api-key>

Command Line

To transcribe with Deepgram in every voice simulation, run:

deepeval set-stt deepgram --model=nova-3

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

The command above sets Deepgram 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 DeepgramSTTModel to VoiceConfig to transcribe with Deepgram instead of the default OpenAI model:

from deepeval.models import DeepgramSTTModel
from deepeval.voice import VoiceConfig

stt_model = DeepgramSTTModel(
    model="nova-3",
    language="en",
)
voice_config = VoiceConfig(
    stt_model=stt_model,
    ...,
)

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

[Optional] model: A string specifying the name of the transcription model to use. Defaulted to nova-3.
[Optional] api_key: A string specifying your Deepgram API key. Defaults to DEEPGRAM_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 Deepgram API through. Defaulted to https://api.deepgram.com.
[Optional] language: A string BCP-47 code (e.g. "en") pinning the spoken language. Pass "auto" to have Deepgram detect it per request instead. Defaulted to None, which Deepgram reads as English.
[Optional] smart_format: A boolean asking Deepgram to punctuate, capitalize and format numbers in the transcript. Defaulted to True.
[Optional] cost_per_minute: A float overriding the per-minute price used for cost accounting. Defaults to the built-in price for the model.
[Optional] transcription_kwargs: A dictionary of additional query parameters forwarded to Deepgram's /v1/listen 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 Deepgram as the transcription provider:

# .env.local
DEEPGRAM_API_KEY=<your-deepgram-api-key>
USE_DEEPGRAM_STT=1
DEEPEVAL_STT_MODEL=nova-3

deepeval set-stt deepgram --model nova-3 writes those same variables for you. DEEPEVAL_STT_MODEL is optional: leave it out and transcription runs on nova-3 anyway, since that is Deepgram'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="nova-3",
    ...,
)

With USE_DEEPGRAM_STT set, a bare model name is shorthand for DeepgramSTTModel(model=...). Pass the model object itself to pin a language or turn off smart formatting.

Available Deepgram Models

nova-3 (default)
nova-3-general

Any model Deepgram's /v1/listen endpoint accepts will work.

Setting Up Your API Key

Command Line

In Code

Available Deepgram Models

On this page