Create and manage custom pronunciation rules for consistent text-to-speech output. Define how specific words, acronyms, and phrases should be pronounced across all voice generations.

Quick Reference

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.pronunciationDictionaries

Capabilities

Create from File

Create pronunciation dictionary from PLS (Pronunciation Lexicon Specification) file.

/**
 * @param request - PLS file and dictionary metadata
 * @param requestOptions - Optional request configuration
 * @returns Created dictionary metadata
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.createFromFile(
  request: BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromFilePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddPronunciationDictionaryResponseModel>;

interface BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromFilePost {
  /** Name for the dictionary */
  name: string;
  /** PLS file containing pronunciation rules */
  file: File | Blob;
  /** Dictionary description */
  description?: string;
  /** Workspace ID (optional) */
  workspace_access?: string;
}

interface AddPronunciationDictionaryResponseModel {
  /** Dictionary ID */
  id: string;
  /** Dictionary name */
  name: string;
  /** Version ID */
  version_id: string;
}

Create from Rules

Create pronunciation dictionary from an array of rules.

/**
 * @param request - Pronunciation rules and metadata
 * @param requestOptions - Optional request configuration
 * @returns Created dictionary metadata
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.createFromRules(
  request: BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddPronunciationDictionaryResponseModel>;

interface BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPost {
  /** List of pronunciation rules. (REQUIRED) */
  rules: PronunciationRule[];
  /** The name of the pronunciation dictionary, used for identification only. (REQUIRED) */
  name: string;
  /** A description of the pronunciation dictionary, used for identification only. */
  description?: string;
  /** Should be one of 'admin', 'editor' or 'viewer'. If not provided, defaults to no access. */
  workspaceAccess?: "admin" | "editor" | "viewer";
}

/** Pronunciation rule (discriminated union based on type field) */
type PronunciationRule = PronunciationRuleAlias | PronunciationRulePhoneme;

interface PronunciationRuleAlias {
  /** Rule type discriminator (REQUIRED) */
  type: "alias";
  /** String to replace (REQUIRED) */
  stringToReplace: string;
  /** Replacement text (REQUIRED) */
  alias: string;
}

interface PronunciationRulePhoneme {
  /** Rule type discriminator (REQUIRED) */
  type: "phoneme";
  /** String to replace (REQUIRED) */
  stringToReplace: string;
  /** Phonetic pronunciation (REQUIRED) */
  phoneme: string;
  /** Phonetic alphabet (REQUIRED) */
  alphabet: "ipa" | "cmu" | "arpabet";
}

Get Dictionary

Retrieve metadata about a pronunciation dictionary.

/**
 * @param pronunciation_dictionary_id - Dictionary ID
 * @param requestOptions - Optional request configuration
 * @returns Dictionary metadata
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.get(
  pronunciation_dictionary_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetPronunciationDictionaryMetadataResponse>;

interface GetPronunciationDictionaryMetadataResponse {
  id: string;
  name: string;
  version_id: string;
  description?: string;
  created_by: string;
  creation_time_unix: number;
}

Update Dictionary

Update dictionary metadata without changing version.

/**
 * @param pronunciation_dictionary_id - Dictionary ID
 * @param request - Updated metadata
 * @param requestOptions - Optional request configuration
 * @returns Updated dictionary metadata
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.update(
  pronunciation_dictionary_id: string,
  request?: BodyUpdatePronunciationDictionaryV1PronunciationDictionariesPronunciationDictionaryIdPatch,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetPronunciationDictionaryMetadataResponse>;

interface BodyUpdatePronunciationDictionaryV1PronunciationDictionariesPronunciationDictionaryIdPatch {
  /** New name */
  name?: string;
  /** New description */
  description?: string;
}

Download Dictionary

Download PLS file with pronunciation rules.

/**
 * @param dictionary_id - Dictionary ID
 * @param version_id - Version ID
 * @param requestOptions - Optional request configuration
 * @returns ReadableStream of PLS file content
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.download(
  dictionary_id: string,
  version_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<ReadableStream<Uint8Array>>;

List Dictionaries

List all pronunciation dictionaries with pagination.

/**
 * @param request - Pagination and sorting options
 * @param requestOptions - Optional request configuration
 * @returns Paginated list of dictionaries
 * @throws UnprocessableEntityError if request fails
 */
client.pronunciationDictionaries.list(
  request?: PronunciationDictionariesListRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetPronunciationDictionariesMetadataResponseModel>;

interface PronunciationDictionariesListRequest {
  /** Pagination cursor */
  cursor?: string;
  /** Page size */
  pageSize?: number;
  /** Sort field */
  sort?: string;
  /** Sort direction */
  sortDirection?: "asc" | "desc";
}

interface GetPronunciationDictionariesMetadataResponseModel {
  pronunciation_dictionaries: GetPronunciationDictionaryMetadataResponse[];
  next_cursor?: string;
  has_more: boolean;
}

Rule Management

Manage individual pronunciation rules within dictionaries.

/**
 * Add rules to existing dictionary (creates new version)
 */
client.pronunciationDictionaries.rules.add(
  pronunciation_dictionary_id: string,
  request: AddRulesToDictionaryRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddPronunciationDictionaryResponseModel>;

/**
 * Remove rules from dictionary (creates new version)
 */
client.pronunciationDictionaries.rules.remove(
  pronunciation_dictionary_id: string,
  request: RemoveRulesFromDictionaryRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddPronunciationDictionaryResponseModel>;

interface AddRulesToDictionaryRequest {
  rules: PronunciationRule[];
}

interface RemoveRulesFromDictionaryRequest {
  rule_strings: string[];
}

Usage Examples

Create Dictionary from Rules

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Create dictionary with pronunciation rules
const dictionary = await client.pronunciationDictionaries.createFromRules({
  name: "Tech Terms",
  description: "Pronunciation rules for technical terms and acronyms",
  rules: [
    {
      type: "alias",
      stringToReplace: "API",
      alias: "A P I",
    },
    {
      type: "alias",
      stringToReplace: "SQL",
      alias: "sequel",
    },
    {
      type: "alias",
      stringToReplace: "GUI",
      alias: "gooey",
    },
    {
      type: "phoneme",
      stringToReplace: "nginx",
      phoneme: "ˈɛndʒɪnˈɛks",
      alphabet: "ipa",
    },
  ],
});

console.log("Dictionary ID:", dictionary.id);
console.log("Version ID:", dictionary.version_id);

Use Dictionary in TTS

// Apply pronunciation dictionary to text-to-speech
const audio = await client.textToSpeech.convert("voice-id", {
  text: "Our API uses SQL and the nginx server with a modern GUI.",
  pronunciation_dictionary_locators: [
    {
      pronunciation_dictionary_id: dictionary.id,
      version_id: dictionary.version_id,
    },
  ],
});

// "API" will be pronounced as "A P I"
// "SQL" will be pronounced as "sequel"
// "GUI" will be pronounced as "gooey"
// "nginx" will be pronounced as "ˈɛndʒɪnˈɛks"

Acronym Dictionary

// Create dictionary for company acronyms
const acronyms = await client.pronunciationDictionaries.createFromRules({
  name: "Company Acronyms",
  rules: [
    { type: "alias", stringToReplace: "CEO", alias: "C E O" },
    { type: "alias", stringToReplace: "CTO", alias: "C T O" },
    { type: "alias", stringToReplace: "HR", alias: "H R" },
    { type: "alias", stringToReplace: "IT", alias: "I T" },
    { type: "alias", stringToReplace: "Q&A", alias: "Q and A" },
    { type: "alias", stringToReplace: "R&D", alias: "R and D" },
  ],
});

Brand Names Dictionary

// Define how to pronounce brand names
const brands = await client.pronunciationDictionaries.createFromRules({
  name: "Brand Names",
  rules: [
    {
      type: "phoneme",
      stringToReplace: "Huawei",
      phoneme: "ˈwɑːweɪ",
      alphabet: "ipa",
    },
    {
      type: "alias",
      stringToReplace: "Xiaomi",
      alias: "shao me",
    },
    {
      type: "alias",
      stringToReplace: "GIF",
      alias: "jif", // or "gif" depending on preference
    },
  ],
});

Medical Terms Dictionary

// Medical terminology pronunciation
const medicalTerms = await client.pronunciationDictionaries.createFromRules({
  name: "Medical Terms",
  description: "Pronunciation for common medical terms",
  rules: [
    {
      type: "alias",
      stringToReplace: "mg",
      alias: "milligrams",
    },
    {
      type: "alias",
      stringToReplace: "ml",
      alias: "milliliters",
    },
    {
      type: "alias",
      stringToReplace: "IV",
      alias: "I V",
    },
    {
      type: "phoneme",
      stringToReplace: "acetaminophen",
      phoneme: "əˌsiːtəˈmɪnəfən",
      alphabet: "ipa",
    },
  ],
});

Add Rules to Existing Dictionary

// Add new rules to existing dictionary
const updated = await client.pronunciationDictionaries.rules.add(
  dictionary.id,
  {
    rules: [
      {
        type: "alias",
        stringToReplace: "URL",
        alias: "U R L",
      },
      {
        type: "alias",
        stringToReplace: "HTTP",
        alias: "H T T P",
      },
    ],
  }
);

console.log("New version ID:", updated.version_id);

Remove Rules

// Remove specific rules from dictionary
await client.pronunciationDictionaries.rules.remove(dictionary.id, {
  rule_strings: ["SQL", "GUI"],
});

List All Dictionaries

// Get all pronunciation dictionaries
const dictionaries = await client.pronunciationDictionaries.list({
  pageSize: 50,
  sortDirection: "desc",
});

for (const dict of dictionaries.pronunciation_dictionaries) {
  console.log(`${dict.name} (${dict.id})`);
  console.log(`  Created: ${new Date(dict.creation_time_unix * 1000).toLocaleString()}`);
}

Download Dictionary File

import { writeFile } from "fs/promises";

// Download PLS file
const plsFile = await client.pronunciationDictionaries.download(
  dictionary.id,
  dictionary.version_id
);

const chunks: Uint8Array[] = [];
for await (const chunk of plsFile) {
  chunks.push(chunk);
}
await writeFile("dictionary.pls", Buffer.concat(chunks));

Create from PLS File

import { readFile } from "fs/promises";

// Load existing PLS file
const plsContent = await readFile("custom_dictionary.pls");

// Create dictionary from file
const fromFile = await client.pronunciationDictionaries.createFromFile({
  name: "Imported Dictionary",
  file: new File([plsContent], "custom_dictionary.pls"),
  description: "Dictionary imported from PLS file",
});

Update Dictionary Metadata

// Update name and description
await client.pronunciationDictionaries.update(dictionary.id, {
  name: "Updated Tech Terms",
  description: "Updated pronunciation rules for technical terms",
});

Multiple Dictionaries

// Use multiple dictionaries at once
const audio = await client.textToSpeech.convert("voice-id", {
  text: "The CEO discussed our API with the IT team.",
  pronunciation_dictionary_locators: [
    {
      pronunciation_dictionary_id: acronyms.id,
      version_id: acronyms.version_id,
    },
    {
      pronunciation_dictionary_id: dictionary.id,
      version_id: dictionary.version_id,
    },
  ],
});

IPA Phonemes

// Use International Phonetic Alphabet
const ipaDict = await client.pronunciationDictionaries.createFromRules({
  name: "IPA Pronunciations",
  rules: [
    {
      type: "phoneme",
      stringToReplace: "schedule",
      phoneme: "ˈʃɛdjuːl", // British pronunciation
      alphabet: "ipa",
    },
    {
      type: "phoneme",
      stringToReplace: "tomato",
      phoneme: "təˈmɑːtəʊ", // British pronunciation
      alphabet: "ipa",
    },
  ],
});

CMU Phonemes

// Use CMU (Carnegie Mellon) phoneme alphabet
const cmuDict = await client.pronunciationDictionaries.createFromRules({
  name: "CMU Pronunciations",
  rules: [
    {
      type: "phoneme",
      stringToReplace: "hello",
      phoneme: "HH AH0 L OW1",
      alphabet: "cmu",
    },
    {
      type: "phoneme",
      stringToReplace: "world",
      phoneme: "W ER1 L D",
      alphabet: "cmu",
    },
  ],
});

Paginate Dictionaries

// Paginate through all dictionaries
async function getAllDictionaries() {
  const allDicts: GetPronunciationDictionaryMetadataResponse[] = [];
  let cursor: string | undefined;

  while (true) {
    const page = await client.pronunciationDictionaries.list({
      cursor,
      pageSize: 100,
    });

    allDicts.push(...page.pronunciation_dictionaries);

    if (!page.has_more) break;
    cursor = page.next_cursor;
  }

  return allDicts;
}

const all = await getAllDictionaries();
console.log(`Total dictionaries: ${all.length}`);

Version

Tile

Files