Skip to main content
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 apply to the next synthesis request after the dictionary mutation finishes. By default all active project dictionaries apply automatically (language-filtered); use .dictionaryIds(List<Integer>) on GenerateRequest / StreamConfig / MultiContextConfig to select dictionaries per request (List.of() = none; a list = exactly those, including inactive ones). Without explicit selection, the service applies active dictionaries to generation and streaming requests; the service applies active dictionaries for the API key’s project during text processing. For the full HTTP contract, field limits, master-key project_id rules, and error codes, see the Dictionaries API reference.

​
Create a Dictionary

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

// 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());
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.

​
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. 
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.
replaceAll is intentionally destructive for omitted words. Only call it with the complete desired contents of that dictionary.
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()
);

​
Generate With Dictionaries

Keep normalize enabled unless you have a specific reason to bypass text normalization. 
import com.kugelaudio.sdk.AudioResponse;
import com.kugelaudio.sdk.GenerateRequest;

AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Postgres runs our product analytics.")
        .modelId("kugel-3")
        .language("en")
        .normalize(true)
        .build()
);
Next: Types — data models, audio utilities, and a complete example.