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. Dictionaries apply to a synthesis request only when it carries the dictionary’s projectId; see Generate With Dictionaries. Changes are available to synthesis after the dictionary mutation finishes. For the full HTTP contract, field limits, master-key project_id rules, and error codes, see the Dictionaries API reference.

Create a Dictionary

import { KugelAudio } from 'kugelaudio';

const client = new KugelAudio({ apiKey: process.env.KUGELAUDIO_API_KEY! });

const dictionary = await client.dictionaries.create({
  name: 'Brand names',
  description: 'Product and company names',
  language: 'en',
});

console.log(dictionary.id);

Manage Dictionaries

// List every dictionary in the project
const dictionaries = await client.dictionaries.list();

// Fetch one
const dict = await client.dictionaries.get(dictionary.id);

// Update name / description / language / isActive (only provided fields change)
await client.dictionaries.update(dictionary.id, {
  description: 'Updated description',
});

Every dictionaries.* and dictionaries.entries.* method accepts an optional final { projectId } argument. It is required only for master-key callers acting on a specific project; with a normal API key, omit it.

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.

const createdEntry = await client.dictionaries.entries.add(dictionary.id, {
  word: 'Postgres',
  replacement: 'post-gres',
});

const page = await client.dictionaries.entries.list(dictionary.id, {
  search: 'post',
  limit: 50,
});

for (const entry of page.entries) {
  console.log(`${entry.word} → ${entry.replacement}`);
}

await client.dictionaries.entries.update(
  dictionary.id,
  page.entries[0].id,
  { replacement: 'postgres' }
);

await client.dictionaries.entries.delete(dictionary.id, createdEntry.id);

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.

const result = await client.dictionaries.entries.replaceAll(dictionary.id, [
  { word: 'Postgres', replacement: 'post-gres' },
  { word: 'Kubernetes', replacement: 'koo-ber-net-eez' },
]);

console.log(`upserted=${result.upserted} deleted=${result.deleted}`);

Generate With Dictionaries

Pass the dictionary’s projectId on client.tts.generate() or client.tts.stream(). Without projectId, no dictionary applies and a non-empty dictionaryIds is rejected. With projectId, omit dictionaryIds to apply all active dictionaries of the project, or pass a list to select exact IDs. Keep normalize enabled unless you have a specific reason to bypass text normalization.

const audio = await client.tts.generate({
  text: 'Postgres runs our product analytics.',
  modelId: 'kugel-3',
  voiceId: 1071,
  language: 'en',
  normalize: true,
  projectId: dictionary.projectId,
  dictionaryIds: [dictionary.id],
});

Streaming and multi-context sessions take the same two fields in their config and send them with the session configuration; they apply to every turn or context on that connection:

const session = client.tts.streamingSession(
  { voiceId: 1071, language: 'en', projectId: dictionary.projectId },
  { onChunk: (chunk) => playAudio(chunk.audio) },
);

const multi = client.tts.createMultiContextSession({
  defaultVoiceId: 1071,
  language: 'en',
  projectId: dictionary.projectId,
  dictionaryIds: [dictionary.id],
});

Dictionary types

interface Dictionary {
  id: number;
  projectId: number;
  name: string;
  description?: string;
  language?: string;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

interface DictionaryEntry {
  id: number;
  dictionaryId: number;
  word: string;
  replacement: string;
  ipa?: string;
  caseSensitive: boolean;
  createdAt: string;
  updatedAt: string;
}

interface DictionaryEntryInput {     // payload for add() / replaceAll()
  word: string;
  replacement: string;
  ipa?: string;
  caseSensitive?: boolean;
}

interface DictionaryEntryListResponse {  // returned by entries.list()
  entries: DictionaryEntry[];
  total: number;
  limit: number;
  offset: number;
}

interface BulkReplaceResult {        // returned by entries.replaceAll()
  upserted: number;
  deleted: number;
  total: number;
}

interface CreateDictionaryOptions { name: string; description?: string; language?: string; }
interface UpdateDictionaryOptions { name?: string; description?: string; language?: string; isActive?: boolean; }
interface UpdateDictionaryEntryOptions { word?: string; replacement?: string; ipa?: string; caseSensitive?: boolean; }

Clean up

// Delete a dictionary (cascades to its entries)
await client.dictionaries.delete(dictionary.id);

Next steps

Types & Errors: the full TypeScript reference
Text Normalization: how normalization interacts with dictionaries

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

Generate With Dictionaries

Dictionary types

Clean up

Next steps

​Create a Dictionary

​Manage Dictionaries

​Add and Manage Entries

​Atomic Bulk Sync

​Generate With Dictionaries

​Dictionary types

​Clean up

​Next steps

Create a Dictionary

Manage Dictionaries

Add and Manage Entries

Atomic Bulk Sync

Generate With Dictionaries

Dictionary types

Clean up

Next steps