Dictionaries

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. See Dictionaries at Synthesis. For the full HTTP contract, field limits, 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
);

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

Delete a Dictionary

Deleting a dictionary also deletes its entries:

client.dictionaries().delete(dictionary.getId());

Dictionaries at Synthesis

Set .projectId(long) on GenerateRequest, StreamConfig or MultiContextConfig. With the project set, its active dictionaries for the request language apply. Add .dictionaryIds(...) for an exact selection, or List.of() to disable dictionaries for the request. A non-empty .dictionaryIds(...) without .projectId(...) is rejected.

AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Willkommen bei Kugel Audio.")
        .voiceId(1071)
        .language("de")
        .projectId(dictionary.getProjectId())
        .build()
);

Next steps

Types: data models, audio utilities, and a complete example
Dictionaries API reference: use a dictionary in synthesis with project_id

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Create a Dictionary

Manage Dictionaries

Add and Manage Entries

Atomic Bulk Sync

Delete a Dictionary

Dictionaries at Synthesis

Next steps

​Create a Dictionary

​Manage Dictionaries

​Add and Manage Entries

​Atomic Bulk Sync

​Delete a Dictionary

​Dictionaries at Synthesis

​Next steps

Create a Dictionary

Manage Dictionaries

Add and Manage Entries

Atomic Bulk Sync

Delete a Dictionary

Dictionaries at Synthesis

Next steps