AssemblyAI STT

In deepeval, you can use AssemblyAI 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
ASSEMBLYAI_API_KEY=<your-assemblyai-api-key>

Alternative (Shell/CI):

export ASSEMBLYAI_API_KEY=<your-assemblyai-api-key>

Alternative (notebook):

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

%env ASSEMBLYAI_API_KEY=<your-assemblyai-api-key>

Command Line

To transcribe with AssemblyAI in every voice simulation, run:

deepeval set-stt assemblyai --model=universal-3-5-pro

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

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

from deepeval.models import AssemblyAISTTModel
from deepeval.voice import VoiceConfig

stt_model = AssemblyAISTTModel(
    model="universal-3-5-pro",
    language="en",
)
voice_config = VoiceConfig(
    stt_model=stt_model,
    ...,
)

There are ZERO mandatory and EIGHT optional parameters when creating an AssemblyAISTTModel:

[Optional] model: A string specifying the name of the transcription model to use. Defaulted to universal-3-5-pro.
[Optional] api_key: A string specifying your AssemblyAI API key. Defaults to ASSEMBLYAI_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 AssemblyAI API through. Defaulted to https://api.assemblyai.com.
[Optional] language: A string ISO-639-1 code (e.g. "en") pinning the spoken language. Pass "auto" to have AssemblyAI detect it instead. Defaulted to None.
[Optional] cost_per_hour: A float overriding the hourly price used for cost accounting. Defaults to the built-in price for whichever endpoint the clip took.
[Optional] transcription_kwargs: A dictionary of additional parameters forwarded to AssemblyAI's transcription request.
[Optional] timeout: A float number of seconds to wait on a request before giving up. Defaulted to 120.0.
[Optional] poll_interval_seconds: A float number of seconds between status checks on the upload-and-poll path. Defaulted to 1.0, and never consulted for clips short enough to take the synchronous endpoint.

First set your API key and select AssemblyAI as the transcription provider:

# .env.local
ASSEMBLYAI_API_KEY=<your-assemblyai-api-key>
USE_ASSEMBLYAI_STT=1
DEEPEVAL_STT_MODEL=universal-3-5-pro

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

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

Available AssemblyAI Models

universal-3-5-pro (default, replaces the deprecated slam-1)
universal-2

Setting Up Your API Key

Command Line

In Code

Available AssemblyAI Models

On this page