> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AssemblyAI Speech-to-Text

> AssemblyAI STT services: streaming WebSocket API (AssemblyAISTTService) and segmented HTTP API (AssemblyAISyncSTTService) for voice agents.

## Overview

AssemblyAI provides two speech-to-text services:

* **`AssemblyAISTTService`**: Real-time streaming via WebSocket. Opens a persistent connection and transcribes audio as it arrives, with support for interim results, end-of-turn detection, and continuous transcription.

* **`AssemblyAISyncSTTService`**: Segmented transcription via HTTP. Uses VAD to detect speech segments and transcribes each complete segment (up to 120 seconds) in a single HTTP request. No persistent session to manage. Ideal for dictation, scribe workflows, and voice agents where speech is detected locally.

<CardGroup cols={2}>
  <Card title="AssemblyAI STT API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.assemblyai.stt.html">
    Pipecat's API methods for AssemblyAI STT integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-assemblyai-turn-detection.py">
    Example with AssemblyAI built-in turn detection
  </Card>

  <Card title="Universal 3.5 Pro Realtime" icon="bolt" href="https://www.assemblyai.com/docs/streaming/universal-3-pro">
    Universal 3.5 Pro Realtime documentation and features
  </Card>

  <Card title="Universal 3.5 Pro Realtime API Reference" icon="book" href="https://www.assemblyai.com/docs/api-reference/streaming-api/universal-3-pro/universal-3-pro">
    Complete Universal 3.5 Pro Realtime API reference
  </Card>

  <Card title="AssemblyAI Console" icon="microphone" href="https://www.assemblyai.com/dashboard/signup">
    Access API keys and transcription features
  </Card>
</CardGroup>

## Installation

To use AssemblyAI services, install the required dependency:

```bash theme={null}
uv add "pipecat-ai[assemblyai]"
```

## Prerequisites

### AssemblyAI Account Setup

Before using AssemblyAI STT services, you need:

1. **AssemblyAI Account**: Sign up at [AssemblyAI Console](https://www.assemblyai.com/dashboard/signup)
2. **API Key**: Generate an API key from your dashboard
3. **Configuration**: Configure transcription settings and features for your use case

### Required Environment Variables

* `ASSEMBLYAI_API_KEY`: Your AssemblyAI API key for authentication

## Configuration

### AssemblyAISTTService

<ParamField path="api_key" type="str" required>
  AssemblyAI API key for authentication.
</ParamField>

<ParamField path="language" type="Language" default="Language.EN" deprecated>
  Language code for transcription. *Deprecated in v0.0.105. Use
  `settings=AssemblyAISTTService.Settings(...)` instead.*
</ParamField>

<ParamField path="api_endpoint_base_url" type="str" default="wss://streaming.assemblyai.com/v3/ws">
  WebSocket endpoint URL. Override for custom or proxied deployments.
</ParamField>

<ParamField path="sample_rate" type="int | None" default="None">
  Audio sample rate in Hz. If None, uses the input sample rate from the start
  frame.
</ParamField>

<ParamField path="encoding" type="str" default="pcm_s16le">
  Audio encoding format.
</ParamField>

<ParamField path="connection_params" type="AssemblyAIConnectionParams" default="None" deprecated>
  Connection configuration parameters. *Deprecated in v0.0.105. Use
  `settings=AssemblyAISTTService.Settings(...)` instead. See
  [Settings](#settings) below.*
</ParamField>

<ParamField path="vad_force_turn_endpoint" type="bool" default="True">
  Controls turn detection mode. When `True` (Pipecat mode, default): Forces
  AssemblyAI to return finals ASAP so Pipecat's turn detection (e.g., Smart
  Turn) decides when the user is done. VAD stop sends ForceEndpoint as ceiling.
  No UserStarted/StoppedSpeakingFrame emitted from STT. When `False` (AssemblyAI
  turn detection mode): AssemblyAI's model controls turn endings using built-in
  turn detection. Uses AssemblyAI API defaults for all parameters unless
  explicitly set. Emits UserStarted/StoppedSpeakingFrame from STT.
</ParamField>

<ParamField path="should_interrupt" type="bool" default="True">
  Whether to interrupt the bot when the user starts speaking in AssemblyAI turn
  detection mode (`vad_force_turn_endpoint=False`). Only applies when using
  AssemblyAI's built-in turn detection. See [User Turn
  Strategies](/api-reference/server/utilities/turn-management/user-turn-strategies#externaluserturnstrategies)
  if you pass your own `user_turn_strategies`.
</ParamField>

<ParamField path="speaker_format" type="str | None" default="None">
  Optional format string for speaker labels when diarization is enabled. Use
  `{speaker}` for speaker label and `{text}` for transcript text. Example:
  `"<{speaker}>{text}</{speaker}>"` or `"{speaker}: {text}"`. If None, transcript
  text is not modified.
</ParamField>

<ParamField path="settings" type="AssemblyAISTTService.Settings" default="None">
  Runtime-configurable settings for the STT service. See [Settings](#settings)
  below.
</ParamField>

<ParamField path="ttfs_p99_latency" type="float" default="ASSEMBLYAI_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment.
</ParamField>

### AssemblyAISyncSTTService

<ParamField path="api_key" type="str" required>
  AssemblyAI API key for authentication.
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  aiohttp ClientSession for HTTP requests. Pre-warming only helps when the warm
  and transcribe requests share this session's connection pool, so keep one
  session for the service.
</ParamField>

<ParamField path="base_url" type="str" default="https://sync.assemblyai.com">
  Base URL for the Sync API. Override for a data-residency endpoint (e.g.
  `https://sync.us.assemblyai.com` or `https://sync.eu.assemblyai.com`).
</ParamField>

<ParamField path="sample_rate" type="int | None" default="None">
  Audio sample rate in Hz. If None, uses the pipeline's rate.
</ParamField>

<ParamField path="enable_prewarming" type="bool" default="True">
  Whether to open the connection when the user starts speaking so the
  transcription request avoids the connection handshake.
</ParamField>

<ParamField path="max_context_turns" type="int" default="5">
  Number of prior conversation turns — user transcripts and agent replies
  together, in one chronological buffer — automatically carried as
  `conversation_context` on each request, so the model transcribes each turn
  with the surrounding dialogue. Set to 0 to disable automatic context. Ignored
  when `conversation_context` is set explicitly in `settings`.
</ParamField>

<ParamField path="max_context_chars" type="int" default="1500">
  Character budget for the automatic context buffer; the oldest turns are
  dropped first once either cap is exceeded.
</ParamField>

<ParamField path="settings" type="AssemblyAISyncSTTService.Settings" default="None">
  Runtime-configurable settings for the Sync STT service. See [Sync
  Settings](#sync-settings) below.
</ParamField>

<ParamField path="ttfs_p99_latency" type="float" default="ASSEMBLYAI_SYNC_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Broadcast at
  pipeline start for downstream turn timing; set it to your measured value.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AssemblyAISTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter                          | Type                                                 | Default               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------- | ---------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`                            | `str`                                                | `"universal-3-5-pro"` | STT model identifier. Set to `"universal-3-5-pro"` or `"universal-3-6-pro"` (Universal-3 Pro models). `universal-3-6-pro` is `universal-3-5-pro` upgraded with the same feature set. *(Inherited from base STT settings.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `language`                         | `Language \| str`                                    | `Language.EN`         | Language for speech recognition. *(Inherited from base STT settings.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `formatted_finals`                 | `bool`                                               | `True`                | Whether to enable transcript formatting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `word_finalization_max_wait_time`  | `int`                                                | `None`                | Maximum time to wait for word finalization in milliseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `end_of_turn_confidence_threshold` | `float`                                              | `None`                | Confidence threshold for end-of-turn detection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `min_turn_silence`                 | `int`                                                | `None`                | Silence duration (ms) before a speculative end-of-turn check. If terminal punctuation is found, the turn ends; otherwise a partial is emitted and the turn continues. Clamped to 50–10000 ms. Server default is mode-dependent (set by the `mode` preset).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `max_turn_silence`                 | `int`                                                | `None`                | Maximum silence (ms) before the turn is forced to end, regardless of punctuation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `keyterms_prompt`                  | `List[str]`                                          | `None`                | A list of words and phrases to improve recognition accuracy for. Maximum 100 terms. May be combined with `prompt` on U3 Pro models.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `prompt`                           | `str`                                                | `None`                | A contextual prompt describing what the audio is about — its domain, scenario, or conversation details — so the model better recognizes likely vocabulary. Carries context about your audio, not transcription instructions; formatting or behavioral commands are not supported. Maximum \~1500 characters. Only applicable to U3 Pro models; may be combined with `keyterms_prompt` on those models.                                                                                                                                                                                                                                                                                                                                     |
| `language_code`                    | `str`                                                | `None`                | Customer-declared audio language as an ISO code (e.g. `"en"`, `"es"`, `"fr"`). On U3 Pro models, a tier-1 code (`"en"`/`"es"`/`"fr"`/`"de"`/`"it"`/`"pt"`) steers transcription toward that language; other supported codes are `"tr"`, `"nl"`, `"sv"`, `"no"`, `"da"`, `"fi"`, `"hi"`, `"vi"`, `"ar"`, `"he"`, `"ja"`, `"zh"`. This is one of the names AssemblyAI accepts for its declared-language parameter, alongside `language_codes`, which covers the same languages as `Language` enums and is bound in preference to this one when both are set. Prefer `language_codes`. Distinct from `language_detection`, which controls whether the detected language is reported.                                                          |
| `language_codes`                   | `List[Language]`                                     | `None`                | Customer-declared audio languages. A single language (e.g. `[Language.ES]`) pins transcription to that language; several (e.g. `[Language.EN, Language.ES]`) steer toward that subset while keeping code-switching among them. Order is significant — the steering prompt follows the declared order. Regional variants resolve to their base code, so at most 10 distinct languages. Steering is prompt-based, so it applies to U3 Pro models only and is not sent for other models — including `universal-streaming-multilingual`, which transcribes multilingual audio without steering. Unlike most settings, a change applies to a live session without reconnecting; pass an empty list to clear steering back to the model default. |
| `speaker_labels`                   | `bool`                                               | `None`                | Whether to enable streaming speaker diarization. When enabled, each turn includes a `speaker_label` and each final word includes a `speaker` field for word-level attribution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `vad_threshold`                    | `float`                                              | `None`                | Confidence threshold (0.0–1.0) for classifying audio frames as silence. Frames with VAD confidence below this value are considered silent; increase for noisy environments to reduce false speech detection. Server default is mode-dependent (set by the `mode` preset).                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `domain`                           | `str`                                                | `None`                | Enable a domain-specific model for specialized terminology. Set to `"medical-v1"` for Medical Mode (improved accuracy on medications, procedures, conditions, and dosages). Supported languages: `en`, `es`, `de`, `fr`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `continuous_partials`              | `bool`                                               | `True`                | Whether to emit additional partial transcripts during long turns at a steady \~3 second cadence. When enabled, partials covering the full turn transcript are emitted about every 3 seconds while speech continues; when disabled, only one early partial is emitted near turn start. The first partial (at 750 ms) is unaffected.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `interruption_delay`               | `int`                                                | `None`                | How soon the first partial is emitted, in milliseconds (0–1000). Useful for tuning barge-in responsiveness or emitting earlier partials for LLM inference; larger values are more confident on interruptions, smaller values give faster time to first partial. The server adds a fixed 256 ms, so `0` yields an effective 256 ms and `500` yields 756 ms. Server default is mode-dependent (set by the `mode` preset).                                                                                                                                                                                                                                                                                                                    |
| `agent_context`                    | `str`                                                | `None`                | Your voice agent's spoken text (TTS reply), used as context for the next user turn — improves accuracy on short or ambiguous replies and spelled-out entities like emails or IDs. Set at connection to seed the agent's greeting and/or update after each reply; each update replaces the previous value. Maximum \~1500 characters.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `previous_context_n_turns`         | `int`                                                | `None`                | Advanced. Maximum number of prior conversation entries (user transcripts and any `agent_context` values) carried forward as context. Range 0–100; set to `0` to disable automatic carryover. Most integrations should leave this unset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `voice_focus`                      | `Literal["near-field", "far-field"]`                 | `None`                | Enable Voice Focus to isolate the primary voice and suppress background noise before transcription. Set to `"near-field"` for close-talking mics (headsets, phones) or `"far-field"` for distant mics (conference rooms). Off when unset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `voice_focus_threshold`            | `float`                                              | `None`                | Controls how aggressively Voice Focus suppresses background audio, from `0.0` (least) to `1.0` (most). Requires `voice_focus` to be set, otherwise a validation error is returned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `mode`                             | `Literal["min_latency", "balanced", "max_accuracy"]` | `None`                | Latency and accuracy preset controlling turn-detection and partial-emission defaults. `max_accuracy` favors quality, `min_latency` favors speed, and `balanced` trades off between them. When omitted, the server applies its own preset, which sets the defaults for mode-dependent fields such as `interruption_delay`, `min_turn_silence`, `vad_threshold`, `previous_context_n_turns`, and `continuous_partials`.                                                                                                                                                                                                                                                                                                                      |

### Sync Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AssemblyAISyncSTTService.Settings(...)`. The Sync service has a simpler settings surface than the streaming service — it supports prompting, key terms, and conversation context, but not turn detection or real-time features like voice focus.

| Parameter              | Type                       | Default               | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                | `str`                      | `"universal-3-5-pro"` | STT model identifier. Set to `"universal-3-5-pro"` or `"universal-3-6-pro"` (Universal-3 Pro models). `universal-3-6-pro` is `universal-3-5-pro` upgraded with the same feature set. *(Inherited from base STT settings.)*                                                                                                                                                                                     |
| `language`             | `Language \| str`          | `Language.EN`         | Language for speech recognition. *(Inherited from base STT settings.)*                                                                                                                                                                                                                                                                                                                                         |
| `prompt`               | `str \| None`              | `None`                | Custom transcription instruction prepended to the model's system prompt. When set, `language` is ignored — state the language in the prompt instead.                                                                                                                                                                                                                                                           |
| `keyterms_prompt`      | `List[str]`                | `None`                | Key terms or phrases to bias the decoder toward.                                                                                                                                                                                                                                                                                                                                                               |
| `conversation_context` | `str \| List[str] \| None` | `None`                | Prior turns from the same conversation, oldest first, giving the model the surrounding dialogue for better continuity and proper-noun consistency across a multi-turn conversation. A single string is treated as one turn. Setting this explicitly turns off the service's automatic context buffer and sends exactly this value; leave it unset to let the service manage context (see `max_context_turns`). |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
    ),
)
```

### With Custom Settings

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        keyterms_prompt=["Pipecat", "AssemblyAI"],
    ),
    vad_force_turn_endpoint=True,
)
```

### With AssemblyAI Built-in Turn Detection

AssemblyAI's Universal-3 Pro models (`universal-3-5-pro` and `universal-3-6-pro`) support built-in turn detection for more natural conversation flow. When `vad_force_turn_endpoint=False`, the service automatically requests `ExternalUserTurnStrategies`, so you don't need to configure turn strategies manually:

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    vad_force_turn_endpoint=False,  # Use AssemblyAI's built-in turn detection
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        # Optional: Tune turn detection timing
        min_turn_silence=100,  # Silence duration (ms) before a speculative end-of-turn check.
        max_turn_silence=1000,  # Maximum silence (ms) before forcing end-of-turn
    ),
)
```

### With Speaker Diarization

Enable speaker identification for multi-party conversations:

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        speaker_labels=True,  # Enable speaker diarization
    ),
    speaker_format="{speaker}: {text}",  # Format transcripts with speaker labels
)
```

### With Context Carryover

Context carryover improves transcription by giving the model memory of recent conversation turns. **It's enabled by default** for Universal-3 Pro models — the service automatically feeds each of the agent's completed replies to AssemblyAI as carryover context, so no configuration is required. The example below only tunes how many prior turns are retained:

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        previous_context_n_turns=4,  # Keep last 4 turns (if None, server default is 3. Set to 0 to disable.)
    ),
)
```

Context carryover helps with short answers, spelled-out entities (emails, IDs), and similar-sounding words. Set `previous_context_n_turns=0` to disable automatic carryover.

### With Voice Focus

Voice focus isolates the primary speaker and suppresses background noise:

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService

stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        voice_focus="near-field",  # Or "far-field" for distant capture
        voice_focus_threshold=0.7,  # 0.0-1.0, higher suppresses more
    ),
)
```

Use `"near-field"` for close-talking mics (headsets, handsets) or `"far-field"` for distant capture (conference rooms, laptop mics).

### With Language Steering

Steer transcription toward specific languages using `language_codes`:

```python theme={null}
from pipecat.services.assemblyai.stt import AssemblyAISTTService
from pipecat.transcriptions.language import Language

# Single language (pins transcription to that language)
stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        language_codes=[Language.ES],
    ),
)

# Multiple languages (steers toward subset, keeps code-switching)
stt = AssemblyAISTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAISTTService.Settings(
        model="universal-3-5-pro",
        language_codes=[Language.EN, Language.ES],  # Order is significant
    ),
)
```

Language steering is prompt-based and applies to U3 Pro models only. Regional variants (e.g. `Language.ES_MX`) resolve to their base code (`"es"`). At most 10 distinct languages can be declared. Unlike most settings, `language_codes` can be updated mid-session without reconnecting using `STTUpdateSettingsFrame`.

### AssemblyAISyncSTTService Usage

The Sync service transcribes VAD-detected speech segments via HTTP requests rather than a persistent WebSocket connection.

#### Basic Setup

```python theme={null}
import aiohttp
from pipecat.services.assemblyai.stt import AssemblyAISyncSTTService
from pipecat.transcriptions.language import Language

async with aiohttp.ClientSession() as session:
    stt = AssemblyAISyncSTTService(
        api_key=os.getenv("ASSEMBLYAI_API_KEY"),
        aiohttp_session=session,
        settings=AssemblyAISyncSTTService.Settings(
            language=Language.EN,
        ),
    )
```

#### With Custom Settings

```python theme={null}
import aiohttp
from pipecat.services.assemblyai.stt import AssemblyAISyncSTTService

async with aiohttp.ClientSession() as session:
    stt = AssemblyAISyncSTTService(
        api_key=os.getenv("ASSEMBLYAI_API_KEY"),
        aiohttp_session=session,
        settings=AssemblyAISyncSTTService.Settings(
            prompt="Transcribe this customer support call.",
            keyterms_prompt=["Pipecat", "AssemblyAI"],
        ),
    )
```

#### With Custom Context Management

```python theme={null}
import aiohttp
from pipecat.services.assemblyai.stt import AssemblyAISyncSTTService

async with aiohttp.ClientSession() as session:
    stt = AssemblyAISyncSTTService(
        api_key=os.getenv("ASSEMBLYAI_API_KEY"),
        aiohttp_session=session,
        max_context_turns=10,  # Keep more conversation history
        max_context_chars=2000,  # Allow more characters
    )
```

Or provide explicit context:

```python theme={null}
stt = AssemblyAISyncSTTService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    aiohttp_session=session,
    settings=AssemblyAISyncSTTService.Settings(
        conversation_context=["Booking a flight to Lisbon."],
    ),
)
```

#### Data Residency

```python theme={null}
async with aiohttp.ClientSession() as session:
    stt = AssemblyAISyncSTTService(
        api_key=os.getenv("ASSEMBLYAI_API_KEY"),
        aiohttp_session=session,
        base_url="https://sync.eu.assemblyai.com",  # EU endpoint
    )
```

## Methods

### update\_agent\_context()

```python theme={null}
async def update_agent_context(text: str)
```

Send the agent's latest spoken reply to AssemblyAI as carryover context. Improves transcription of the user's next turn — short answers, spelled-out entities, disambiguation.

**Parameters:**

* `text` (str): The agent's spoken reply text. Clipped to \~1500 characters.

**Example:**

```python theme={null}
# After the agent finishes speaking
await stt.update_agent_context("What is your order ID?")
```

> It is automatically invoked each time an assistant turn is completed.

### warm()

```python theme={null}
async def warm()
```

Pre-warm the connection to the Sync API (AssemblyAISyncSTTService only). Establishes the connection (DNS, TCP, TLS) ahead of a transcription request so the next segment starts uploading audio immediately. The warmed connection is reused only by requests that share this service's aiohttp session and base URL.

Best-effort: failures are logged and swallowed, since a failed warm-up only forfeits the latency saving.

**Example:**

```python theme={null}
# Manually warm the connection
await stt.warm()
```

> When `enable_prewarming=True` (the default), the connection is warmed automatically when the user starts speaking.

## Notes

* **Model**: Use `universal-3-5-pro` or `universal-3-6-pro`, AssemblyAI's flagship Universal-3 Pro streaming models. `universal-3-6-pro` is `universal-3-5-pro` upgraded with the same feature set. Both support built-in turn detection, prompting, continuous partials, context carryover, and voice focus. `universal-3-5-pro` is the default.
* **Turn detection modes**:
  * **Pipecat mode** (`vad_force_turn_endpoint=True`, default): Forces AssemblyAI to return finals ASAP so Pipecat's turn detection (e.g., Smart Turn) decides when the user is done. The service sends a `ForceEndpoint` message when VAD detects the user has stopped speaking.
  * **AssemblyAI mode** (`vad_force_turn_endpoint=False`, U3 Pro models only): AssemblyAI's model controls turn endings using built-in turn detection. The service proposes each turn boundary and automatically requests `ExternalUserTurnStrategies`, so you don't need to configure turn strategies manually. See [User Turn Strategies](/api-reference/server/utilities/turn-management/user-turn-strategies) for the interruption controls.
* **Context carryover** (U3 Pro models only): Seed the agent's most recent reply, improving transcription of the user's next turn — short answers, spelled-out entities, disambiguation. `update_agent_context()` is automatically invoked each time an assistant turn is completed. Control the window size with `previous_context_n_turns` (0–100, default 3); set to 0 to disable carryover entirely.
* **Voice focus** (U3 Pro models only): Set `voice_focus` to `"near-field"` or `"far-field"` to isolate the primary voice and suppress background noise. Tune suppression strength with `voice_focus_threshold` (0.0–1.0, higher values suppress more).
* **Speaker diarization**: Enable `speaker_labels=True` in Settings to automatically identify different speakers. Final transcripts will include a speaker field (e.g., "Speaker A", "Speaker B"). Use the `speaker_format` parameter to format transcripts with speaker labels.
* **Prompting** (U3 Pro models only): The `prompt` parameter allows you to guide transcription for specific names, terms, or domain vocabulary. May be combined with `keyterms_prompt` on U3 Pro models. AssemblyAI recommends testing without a prompt first.
* **Dynamic settings updates**: Most settings can be updated at runtime using `STTUpdateSettingsFrame`. `agent_context` and `language_codes` are hot-updatable without reconnecting; other settings require a reconnect.

### AssemblyAISyncSTTService

* **Segment limit**: Audio segments must be at most 120 seconds. The API rejects longer segments. This suits dictation, scribe workflows, and voice-agent turns where the client detects speech locally.
* **No persistent connection**: The Sync API is stateless. Each speech segment is transcribed in a single HTTP POST request with no upload step, no polling, and no session to manage.
* **Automatic conversation context**: Recent conversation turns — user transcripts and agent replies together — are automatically carried as `conversation_context` on each request. Control the buffer size with `max_context_turns` (default 5, set to 0 to disable) and `max_context_chars` (default 1500). Setting `conversation_context` explicitly in Settings turns off the automatic buffer and sends exactly that value.
* **Pre-warming**: When `enable_prewarming=True` (the default), the connection is opened when the user starts speaking so the transcription request skips the DNS, TCP, and TLS handshake. Call `warm()` directly to warm the connection at any other time.
* **aiohttp session**: Pre-warming only helps when the warm and transcribe requests share the same aiohttp session's connection pool, so keep one session for the service.
* **Data residency**: Override `base_url` for data-residency endpoints (e.g. `https://sync.us.assemblyai.com` or `https://sync.eu.assemblyai.com`).

<Tip>
  The `connection_params=` / `InputParams` / `params=` pattern is deprecated as
  of v0.0.105. Use `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Event Handlers

AssemblyAI STT supports the standard [service connection events](/api-reference/server/events/service-events), plus turn-level events for conversation tracking:

| Event             | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `on_connected`    | Connected to AssemblyAI WebSocket                             |
| `on_disconnected` | Disconnected from AssemblyAI WebSocket                        |
| `on_end_of_turn`  | End of turn detected (fires after final transcript is pushed) |

```python theme={null}
@stt.event_handler("on_connected")
async def on_connected(service):
    print("Connected to AssemblyAI")

@stt.event_handler("on_end_of_turn")
async def on_end_of_turn(service, transcript):
    print(f"Turn ended: {transcript}")
```

The `on_end_of_turn` event receives `(service, transcript)` where `transcript` is the final transcript text. This event fires after the final transcript is pushed, providing a reliable hook for end-of-turn logic that doesn't race with `TranscriptionFrame`. Works in both Pipecat and AssemblyAI turn detection modes.
