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

# LiveKit

> The livekit-plugins-slng Python package connects LiveKit Agents to SLNG speech to text and text to speech, with failover, warm standby connections, and low-latency turn finalization.

`livekit-plugins-slng` adds speech to text (STT) and text to speech (TTS)
adapters for [LiveKit Agents](https://docs.livekit.io/agents/). Pass a model
identifier and the plugin builds the bridge endpoint itself, so every streaming
model on the platform works with the same code.

This page is the plugin reference. For a walkthrough that sets up your models in
the dashboard and applies the change, see the
[LiveKit integration guide](/guides/integrate/livekit).

<Note>
  The plugin is realtime WebSocket only, so HTTP-only models (such as batch STT)
  are not available through it. This page documents version **1.6.7 and later**;
  upgrading from 1.6.6 or earlier? Read [Migrating from earlier
  versions](#migrating-from-earlier-versions) first.
</Note>

## Prerequisites

* Python 3.10+ and `livekit-agents>=1.6.10`
* A [LiveKit Agents](https://docs.livekit.io/agents/) project
* An SLNG API key. See [Create your API key](/guides/get-started/quickstart#create-your-api-key).

## Install

```bash theme={null}
uv add livekit-plugins-slng
# or: pip install livekit-plugins-slng
```

## Quickstart

The plugin reads your key from `SLNG_API_KEY`, or pass it with `api_key`. Create
an STT and a TTS instance and hand them to your agent session:

```python theme={null}
from livekit.plugins import slng

stt = slng.STT(model="deepgram/nova:3", language="en")
tts = slng.TTS(
    model="deepgram/aura:2",
    voice="aura-2-thalia-en",  # provider voice ID, required
    language="en",
)
```

<Note>
  Language codes are sent verbatim. Use the exact value the model expects, for
  example BCP-47 `hi-IN` for Sarvam Bulbul, not `hi`.
</Note>

<Accordion title="Full voice agent example">
  ```python agent.py theme={null}
  from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
  from livekit.plugins import silero, slng


  class MyAgent(Agent):
      async def on_enter(self):
          await self.session.say("Hi, how can I help you today?")


  async def entrypoint(ctx: JobContext):
      await ctx.connect()

      stt = slng.STT(model="deepgram/nova:3", language="en", sample_rate=16000)
      tts = slng.TTS(
          model="deepgram/aura:2",
          voice="aura-2-thalia-en",
          language="en",
          sample_rate=24000,
      )

      session = AgentSession(stt=stt, tts=tts, vad=silero.VAD.load())
      await session.start(agent=MyAgent(), room=ctx.room)


  if __name__ == "__main__":
      cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
  ```
</Accordion>

## Model identifiers

Models follow `provider/model:variant`. A bare identifier is the external
passthrough route; prefix with `slng/` for an SLNG-hosted instance.

```python theme={null}
model="deepgram/nova:3"          # external passthrough
model="slng/deepgram/nova:3-en"  # SLNG-hosted, English
```

See the [model catalog](/models/catalog/all-models) for the full list.

## STT reference

`slng.STT` streams speech to text over WebSocket. Provide either `model` or
`connections`; there is no default. Only 16-bit PCM (`pcm_s16le`) input is
supported, and batch `recognize()` is not available, so use `stream()`.

```python theme={null}
stt = slng.STT(model="deepgram/nova:3", language="en")
```

| Parameter                                                           | Default                 | Description                                                                                      |
| ------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| `api_key`                                                           | `None`                  | SLNG API key. Falls back to `SLNG_API_KEY`.                                                      |
| `model`                                                             | `None`                  | Model identifier. Required unless `connections` is set.                                          |
| `connections`                                                       | `None`                  | Ordered failover candidates (see [Failover](#failover)).                                         |
| `provider_api_key`                                                  | `None`                  | Your own provider credential ([BYOK](#bring-your-own-key-byok), external routes only).           |
| `language`                                                          | `"en"`                  | Language code, sent verbatim.                                                                    |
| `sample_rate`                                                       | `16000`                 | Audio sample rate in Hz.                                                                         |
| `enable_partial_transcripts`                                        | `True`                  | Stream interim results.                                                                          |
| `enable_diarization`, `min_speakers`, `max_speakers`                | `False`, `None`, `None` | Speaker identification (model support required).                                                 |
| `vad_threshold`, `vad_min_silence_duration_ms`, `vad_speech_pad_ms` | `0.5`, `300`, `30`      | VAD tuning (model support required).                                                             |
| `final_timeout_s`                                                   | `None`                  | Watchdog for stalled finals. Disabled unless set.                                                |
| `base_url`                                                          | `"api.slng.ai"`         | Gateway host. Point at a regional host to pin execution (see [Region routing](#region-routing)). |
| `external_agent_id`, `external_session_id`                          | `None`                  | Tracking IDs on usage events.                                                                    |
| `fallback_recovery_cooldown_s`                                      | `60.0`                  | Seconds before retrying a failed candidate.                                                      |

Any extra keyword argument is forwarded to the bridge init payload; the bridge
applies the options the model's catalog declares and ignores the rest (for
example Deepgram's `endpointing` and `smart_format`).

## TTS reference

`slng.TTS` streams text to speech over WebSocket. `voice` is required and passed
verbatim as the provider's voice ID. Use `tts.stream()` for voice agents and
`tts.synthesize(text)` for one-shot previews. Change `voice`, `language`, and
`speed` at runtime with `tts.update_options(...)`.

```python theme={null}
tts = slng.TTS(model="deepgram/aura:2", voice="aura-2-thalia-en", language="en")
```

| Parameter                                  | Default         | Description                                                                                      |
| ------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------ |
| `api_key`                                  | `None`          | SLNG API key. Falls back to `SLNG_API_KEY`.                                                      |
| `model`                                    | `None`          | Model identifier. Required unless `connections` is set.                                          |
| `voice`                                    | required        | Provider voice ID, passed verbatim.                                                              |
| `connections`                              | `None`          | Ordered failover candidates (see [Failover](#failover)).                                         |
| `provider_api_key`                         | `None`          | Your own provider credential ([BYOK](#bring-your-own-key-byok), external routes only).           |
| `language`                                 | `"en"`          | Language code, sent verbatim.                                                                    |
| `sample_rate`                              | `24000`         | Audio sample rate in Hz.                                                                         |
| `speed`                                    | `1.0`           | Speech speed multiplier.                                                                         |
| `text_chunking`, `phrase_max_chars`        | `"auto"`, `60`  | How streamed text is batched (see [Text chunking](#text-chunking)).                              |
| `warm_standby_enabled`                     | `False`         | Pre-open the next connection (see [Warm standby](#warm-standby-connections)).                    |
| `first_audio_timeout_s`                    | `None`          | Fail over if no audio arrives in time. Disabled unless set.                                      |
| `base_url`                                 | `"api.slng.ai"` | Gateway host. Point at a regional host to pin execution (see [Region routing](#region-routing)). |
| `external_agent_id`, `external_session_id` | `None`          | Tracking IDs on usage events.                                                                    |
| `fallback_recovery_cooldown_s`             | `60.0`          | Seconds before retrying a failed candidate.                                                      |

Extra keyword arguments are forwarded per the model's contract (for example Rime
Arcana `speakingStyle` or Cartesia Sonic `emotion`). Pass
`pronunciation={"mode": "rewrite", "name": "my-dictionary"}` to apply a
[pronunciation dictionary](/api-reference/text-to-speech/slng/pronunciation-dictionaries/list-pronunciation-dictionaries-http).
Pick a voice that matches your model from the
[text to speech catalog](/models/catalog/text-to-speech).

### Text chunking

`text_chunking="auto"` (the default) batches words into phrases, flushing at
punctuation or `phrase_max_chars`. This avoids the choppy audio that word-by-word
streaming causes on some providers. Set `"word"` only if you need per-word
forwarding.

### Warm standby connections

By default each turn opens a fresh connection, adding setup time to its first
audio. With `warm_standby_enabled=True`, the plugin pre-opens the next connection
while the current turn plays, so time to first audio drops to roughly the
provider's generation time.

```python theme={null}
tts = slng.TTS(model="cartesia/sonic:3", voice="<voice-id>", warm_standby_enabled=True)
```

The standby is a single connection per instance and counts toward your
concurrency limit while it waits. If it expires during a long silence, the plugin
reconnects at regular latency with no error. Where a provider exposes an
inactivity option, pass it as a model option to keep the standby alive through
pauses.

## Failover

Pass `connections=[...]`, an ordered list of candidates (model identifiers,
bridge endpoint URLs, or `STTConnectionConfig` / `TTSConnectionConfig` objects).
When `connections` supplies the full list, `model` is not needed.

```python theme={null}
stt = slng.STT(connections=["deepgram/nova:3", "soniox/speech-ai:rt-v5"])
```

* Each candidate gets `APIConnectOptions.max_retry` attempts before the next is
  tried. Deterministic 4xx errors advance immediately; HTTP 413 is terminal.
* STT fails over at safe stream boundaries and replays buffered audio, so no
  speech is lost. TTS switches only before its first audio, and all TTS
  candidates must share a sample rate and channel count.
* After `fallback_recovery_cooldown_s` (60s default), the primary is retried on
  the next request. A single candidate reconnects and replays on a transient
  drop instead of ending the stream.

`STTConnectionConfig` and `TTSConnectionConfig` keep endpoint-specific headers,
init payloads, and voices together; simple candidates inherit the global
settings.

## Bring your own key (BYOK)

Pass `provider_api_key` to use your own provider credential. The plugin sends it
as the `X-Slng-Provider-Key` header on external (passthrough) routes only. See
[Bring your own key](/guides/models/bring-your-own-key).

```python theme={null}
tts = slng.TTS(model="cartesia/sonic:3", voice="<voice-id>", provider_api_key="<your-key>")
```

## Region routing

Route to a sovereign hub by pointing `base_url` at a regional gateway host, for
example `eu.api.slng.ai` or `us.api.slng.ai`. Data stays in-jurisdiction and every
hub runs the full stack. See the [regions map](/guides/regions/regions-map) for
the available hosts.

```python theme={null}
stt = slng.STT(model="deepgram/nova:3", base_url="eu.api.slng.ai")
```

## Plugin events

Subscribe to `slng_event` for typed events covering gateway session identifiers
(`gateway.session`) and failover activity (`fallback.attempt_failed`,
`fallback.switch_succeeded`, `fallback.primary_recovered`,
`fallback.exhausted`).

```python theme={null}
@tts.on("slng_event")
def on_slng_event(event: slng.PluginEvent) -> None:
    print(event.name, event.component, event.data)
```

`external_agent_id` and `external_session_id` (max 128 characters) attach your
own identifiers to usage events as the `X-SLNG-Agent-Id` and `X-SLNG-Session-Id`
headers, so you can correlate gateway usage with your analytics.

## Migrating from earlier versions

Version 1.6.7 is a breaking rewrite:

* All traffic goes through the bridge. `model_endpoint` and `model_endpoints` were
  removed; pass a `model` or `connections` instead.
* STT has no default model, and `recognize()` (HTTP batch) is gone; use
  `stream()` with `pcm_s16le` input.
* TTS `voice` is required and passed verbatim.
* Language codes are no longer normalized client-side.
* `api_token` is deprecated; use `api_key`.
* Provider-specific defaults were removed; configure candidates via
  `connections`.

## Next steps

* [LiveKit integration guide](/guides/integrate/livekit) for the migration
  walkthrough.