> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deepgram

> Python API reference for the deepgram speech-to-text plugin.

<Card title="Usage guide" icon="book" href="/plugins/stt/deepgram" horizontal>
  Setup, environment variables, and Python/JavaScript/Go usage examples.
</Card>

## DeepgramSTT

Streaming speech-to-text via Deepgram's Listen WebSocket API.

Real-time transcription with interim results, smart formatting, keyterm/keyword
boosting, diarization and redaction. Audio format is fixed at 48 kHz mono linear16,
so `sample_rate`/`encoding`/`channels` are accepted
for backward compatibility but have no effect.

### Constructor

```python theme={null}
DeepgramSTT(*, api_key: 'str | None' = None, model: 'DeepgramSTTModel | str' = 'nova-2', language: 'str' = 'en-US', interim_results: 'bool' = True, punctuate: 'bool' = True, smart_format: 'bool' = True, sample_rate: 'int' = 48000, endpointing: 'int' = 50, filler_words: 'bool' = True, keywords: 'list[str] | None' = None, keyterm: 'list[str] | None' = None, profanity_filter: 'bool' = False, numerals: 'bool' = False, tag: 'Union[str, List[str]] | None' = None, enable_diarization: 'bool' = False, redact: 'Union[str, List[str]] | None' = None, base_url: 'str' = 'wss://api.deepgram.com/v1/listen', **kwargs) -> 'None'
```

<ParamField path="api_key" type="str | None">
  Deepgram API key. Falls back to `DEEPGRAM_API_KEY`.
</ParamField>

<ParamField path="model" type="DeepgramSTTModel | str" default="nova-2">
  Recognition model: `nova-3` family (`nova-3`, `nova-3-general`, `nova-3-medical`), `nova-2` family (`nova-2`, `nova-2-phonecall`, `nova-2-meeting`, `nova-2-medical`, `nova-2-finance`, `nova-2-drivethru`, …) or `flux-general-en`/`flux-general-multi`. Default `"nova-2"`.
</ParamField>

<ParamField path="language" type="str" default="en-US">
  BCP-47 language tag (e.g. `"en-US"`). Default `"en-US"`.
</ParamField>

<ParamField path="interim_results" type="bool" default="True">
  Emit partial hypotheses while the caller speaks. Default True.
</ParamField>

<ParamField path="punctuate" type="bool" default="True">
  Add punctuation to the transcript. Default True.
</ParamField>

<ParamField path="smart_format" type="bool" default="True">
  Apply date/number/currency formatting. Default True.
</ParamField>

<ParamField path="sample_rate" type="int" default="48000">
  Input rate in Hz. Fixed at 48000; ignored.
</ParamField>

<ParamField path="endpointing" type="int" default="50">
  Silence in ms before a finalized transcript is emitted. Default 50.
</ParamField>

<ParamField path="filler_words" type="bool" default="True">
  Keep "uh"/"um" fillers in the transcript. Default True.
</ParamField>

<ParamField path="keywords" type="list[str] | None">
  Legacy term-boost list (nova-2). Use `keyterm` on nova-3.
</ParamField>

<ParamField path="keyterm" type="list[str] | None">
  Keyterm-prompting list to boost domain vocabulary (nova-3).
</ParamField>

<ParamField path="profanity_filter" type="bool" default="False">
  Mask profanity. Default False.
</ParamField>

<ParamField path="numerals" type="bool" default="False">
  Convert spoken numbers to digits. Default False.
</ParamField>

<ParamField path="tag" type="Union[str, List[str]] | None">
  Request tag(s) attached for Deepgram usage reporting.
</ParamField>

<ParamField path="enable_diarization" type="bool" default="False">
  Label speakers in the transcript. Default False.
</ParamField>

<ParamField path="redact" type="Union[str, List[str]] | None">
  Entity type(s) to redact (e.g. `"pci"`, `"numbers"`).
</ParamField>

<ParamField path="base_url" type="str" default="wss://api.deepgram.com/v1/listen">
  Deepgram Listen WebSocket endpoint.
</ParamField>

### aclose

```python theme={null}
def aclose(self) -> 'None'
```

Release any resources held by the provider.

### emit

```python theme={null}
def emit(self, event: 'T', *args: 'Any') -> 'None'
```

Emit an event, invoking all registered handlers with the given arguments.

Handlers are called in registration order. Coroutine handlers are
scheduled on the running event loop. If the emitter is closed, the call
is a no-op.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'
```

Remove a previously registered handler for an event.

If the handler is not registered for the event, the call is a no-op.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'
```

Register a handler for an event.

Can be used directly by passing a callback, or as a decorator when
`callback` is omitted.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

### on\_stt\_transcript

```python theme={null}
def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'
```

Register the coroutine invoked when a transcription event is produced.

<ParamField path="callback" type="Callable[[STTResponse], Awaitable[None]]" required>
  An async callable that receives each `STTResponse`.
</ParamField>

### process\_audio

```python theme={null}
def process_audio(self, audio_frames: 'bytes', language: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'
```

Process a chunk of audio for transcription.

Implementations should consume the audio frames and emit transcription
results through the registered transcript callback.

<ParamField path="audio_frames" type="bytes" required>
  Raw audio bytes to transcribe.
</ParamField>

<ParamField path="language" type="Optional[str]">
  Optional language code to guide recognition.
</ParamField>

### stream\_transcribe

```python theme={null}
def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'
```

Transcribe a continuous audio stream.

<ParamField path="audio_stream" type="AsyncIterator[bytes]" required>
  An async iterator yielding raw audio byte chunks.
</ParamField>

<ResponseField name="returns" type="AsyncIterator[STTResponse]">
  STTResponse: Transcription events produced as audio is consumed.
</ResponseField>

***

## DeepgramSTTModel

```python theme={null}
DeepgramSTTModel = typing.Literal['nova-3', 'nova-3-general', 'nova-3-medical', 'nova-2', 'nova-2-general', 'nova-2-phonecall', 'nova-2-meeting', 'nova-2-conversationalai', 'nova-2-medical', 'nova-2-finance', 'nova-2-dr …
```