> ## 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.

# Pronunciation dictionaries

> Force a fixed spoken form for brand names, acronyms, and other terms your TTS model mispronounces.

A pronunciation dictionary is a reusable set of rewrite rules. Each rule swaps a word or phrase for replacement text before it reaches the TTS model, so "SLNG" is spoken as "slang" and "NAIC" as "en ay eye see" on every turn. You create the dictionary once, then reference it by name when you open a TTS session.

Rewrite matching is deterministic: case-insensitive, whole-word or whole-phrase, longest-match first, and non-recursive. The walkthrough below uses a WebSocket, but the same `pronunciation` selector applies to HTTP TTS requests. One dictionary is active per request or WebSocket turn.

## Prerequisites

* An SLNG API key.
* The hostname of a production cluster with dictionary support enabled.

<Note>
  Create and consume a dictionary on the **same cluster, organization, and environment**. A dictionary created on one cluster is not visible from another.
</Note>

<Steps>
  <Step title="Create your dictionary">
    Send the rewrite rules to `POST /v1/pronunciation/dictionaries`. A successful call returns **201 Created**.

    ```bash theme={null}
    export SLNG_API_KEY="your-api-key"
    export SLNG_BASE_URL="https://[region].api.slng.ai"

    curl --fail-with-body "$SLNG_BASE_URL/v1/pronunciation/dictionaries" \
      -H "Authorization: Bearer $SLNG_API_KEY" \
      -H "Content-Type: application/json" \
      --data '{
        "name": "brand-names",
        "modes": {
          "rewrite": {
            "rules": [
              {"match": "SLNG", "replace": "slang"}
            ]
          }
        }
      }'
    ```

    Each rule pairs a `match` term with the `replace` text sent to the model. A dictionary holds up to 256 rules. Pronunciation fails closed: if a request names a dictionary that cannot be resolved, the TTS request is rejected rather than synthesized without it.
  </Step>

  <Step title="Open a TTS WebSocket with the dictionary selected">
    Connect to a TTS endpoint on the same cluster and pass the dictionary name in the `init` config. This example uses Deepgram Aura 2:

    ```text theme={null}
    wss://[region].api.slng.ai/v1/bridges/unmute/tts/deepgram/aura:2
    ```

    Send the API key in the handshake header:

    ```text theme={null}
    Authorization: Bearer your-api-key
    ```

    Then send the `init` message with a `pronunciation` selector:

    ```json theme={null}
    {
      "type": "init",
      "config": {
        "encoding": "linear16",
        "sample_rate": 24000,
        "pronunciation": {"mode": "rewrite", "name": "brand-names"}
      }
    }
    ```
  </Step>

  <Step title="Send text and collect audio">
    After the server sends `ready`, send a text message:

    ```json theme={null}
    {"type": "text", "text": "Welcome to SLNG.", "flush": true}
    ```

    Collect binary audio frames until `audio_end`. The model speaks "SLNG" as "slang" instead of reading the letters on its own.
  </Step>

  <Step title="Reuse the selection across turns">
    The selection stays active for the session. Send later text messages without repeating `pronunciation`. To switch dictionaries, include a new selector on the first text message of a later turn.

    <Warning>
      Keep complete matching words or phrases within a single message, and set the dictionary before a turn begins rather than mid-turn. To speak without rewriting, open a new session with no `pronunciation` selector.
    </Warning>
  </Step>
</Steps>

## API reference

<Card title="Pronunciation dictionaries API" icon="book-open" href="/api-reference/text-to-speech/slng/pronunciation-dictionaries/create-pronunciation-dictionary-http">
  Create, list, read, and delete dictionaries, with the full rewrite contract and error codes.
</Card>