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

# Dictionaries

> Per-project pronunciation and replacement lists for consistent brand and domain vocabulary

Custom dictionaries are per-project pronunciation and replacement lists.
Each entry maps a written word to the text or IPA the TTS pipeline should
pronounce instead. Use them for brand names, product names, acronyms, and
domain vocabulary that should sound consistent across requests.

Changes are available to synthesis after the dictionary mutation finishes.
Generation must send the dictionary's `project_id`; omission loads no project
dictionary. The current Java generation and streaming builders do not expose
that field, so use the [raw generation API](/api-reference/tts/generate) or raw
WebSocket protocol for dictionary-backed synthesis.

For the full HTTP contract, field limits, master-key `project_id` rules,
and error codes, see the [Dictionaries API reference](/api-reference/endpoints/dictionaries).

## Create a Dictionary

```java theme={null}
import com.kugelaudio.sdk.Dictionary;
import com.kugelaudio.sdk.KugelAudio;

KugelAudio client = KugelAudio.fromEnv();

Dictionary dictionary = client.dictionaries().create(
    "Brand names",
    "Product and company names",
    "en"
);

System.out.println(dictionary.getId());
```

## Manage Dictionaries

```java theme={null}
// List every dictionary in the project
List<Dictionary> dictionaries = client.dictionaries().list();

// Fetch one
Dictionary dict = client.dictionaries().get(dictionary.getId());

// Update name / description / language / isActive (null leaves a field unchanged)
client.dictionaries().update(
    dictionary.getId(),
    null,                      // name
    "Updated description",     // description
    null,                      // language
    false                      // isActive
);

// Delete a dictionary (cascades to its entries)
client.dictionaries().delete(dictionary.getId());
```

<Note>
  Every `dictionaries()` and `entries()` method has a master-key overload that
  takes a trailing `Long projectId`. Use it only when acting on a specific
  project with a master key; with a normal API key, call the shorter overload.
</Note>

## Add and Manage Entries

Use `replacement` for normal spelling-based fixes. Use `ipa` when you need
an exact phonetic pronunciation; IPA takes precedence over `replacement`.

```java theme={null}
import com.kugelaudio.sdk.DictionaryEntry;
import com.kugelaudio.sdk.DictionaryEntryInput;
import com.kugelaudio.sdk.DictionaryEntryListResponse;

DictionaryEntry createdEntry = client.dictionaries().entries().add(
    dictionary.getId(),
    new DictionaryEntryInput("Postgres", "post-gres")
);

DictionaryEntryListResponse page = client.dictionaries().entries().list(
    dictionary.getId(),
    "post",
    50,
    null,
    null
);

for (DictionaryEntry entry : page.getEntries()) {
    System.out.println(entry.getWord() + " → " + entry.getReplacement());
}

client.dictionaries().entries().update(
    dictionary.getId(),
    page.getEntries().get(0).getId(),
    null,
    "postgres",
    null,
    null
);

client.dictionaries().entries().delete(
    dictionary.getId(),
    createdEntry.getId()
);
```

## Atomic Bulk Sync

`replaceAll` upserts every entry in one transaction and deletes entries
currently in the dictionary whose `word` is not in the payload. Use it to
sync from a CMS, PIM, or internal glossary.

<Warning>
  `replaceAll` is intentionally destructive for omitted words. Only call it
  with the complete desired contents of that dictionary.
</Warning>

```java theme={null}
import com.kugelaudio.sdk.BulkReplaceResult;
import java.util.List;

BulkReplaceResult result = client.dictionaries().entries().replaceAll(
    dictionary.getId(),
    List.of(
        new DictionaryEntryInput("Postgres", "post-gres"),
        new DictionaryEntryInput("Kubernetes", "koo-ber-net-eez")
    )
);

System.out.printf(
    "upserted=%d deleted=%d%n",
    result.getUpserted(),
    result.getDeleted()
);
```

## Generation Limitation

`.dictionaryIds(...)` alone is not enough: the API requires `project_id` for
both the default active dictionaries and an explicit selection. Because the
Java generation builders cannot send `project_id`, use the [raw generation
API](/api-reference/tts/generate) for dictionary-backed synthesis.

***

Next: [Types](/sdks/java/types) — data models, audio utilities, and a complete example.