---
title: "Create a pronunciation dictionary"
method: POST
path: "/pronunciation_dicts"
tags: ["Pronunciation Dictionaries"]
---

# Create a pronunciation dictionary

`POST /pronunciation_dicts`

Create a new pronunciation dictionary for the authenticated organization. Each dictionary contains a list of items that control how specific words are spoken. Items can be alias type (text replacement) or phoneme type (IPA pronunciation notation).

As an alternative to providing items directly as JSON, you can upload a dictionary file (PLS/XML or plain text format, max 1MB) using multipart/form-data. PLS files use the standard W3C Pronunciation Lexicon Specification XML format. Text files use a line-based format: `word=alias` for aliases, `word:/phoneme/` for IPA phonemes.

Limits:
- Maximum 50 dictionaries per organization
- Maximum 100 items per dictionary
- Text: max 200 characters
- Alias/phoneme value: max 500 characters
- File upload: max 1MB (1,048,576 bytes)

## Request body

- CreatePronunciationDictRequest — Request body for creating a pronunciation dictionary.
  - `items` PronunciationDictItem[], required — List of pronunciation items (alias or phoneme type). At least one item is required.
    - union — A single pronunciation dictionary item. Use type 'alias' to replace matched text with a spoken alias, or type 'phoneme' to specify exact pronunciation using IPA notation.
      - PronunciationDictAliasItem — An alias pronunciation item. When the `text` value is found in input, it is replaced with the `alias` before speech synthesis.
        - `alias` string, required — The replacement text that will be spoken instead.
        - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
        - `type` 'alias', required — The item type.
      - PronunciationDictPhonemeItem — A phoneme pronunciation item. When the `text` value is found in input, it is pronounced using the specified IPA phoneme notation.
        - `alphabet` 'ipa', required — The phonetic alphabet used for the phoneme notation.
        - `phoneme` string, required — The phoneme notation representing the desired pronunciation.
        - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
        - `type` 'phoneme', required — The item type.
  - `name` string, required — Human-readable name. Must be unique within the organization.

## Response `201`

Pronunciation dictionary created successfully.

- PronunciationDictResponse — Response containing a single pronunciation dictionary.
  - `data` PronunciationDictData — A pronunciation dictionary record.
    - `created_at` string, date-time — ISO 8601 timestamp with millisecond precision.
    - `id` string, uuid — Unique identifier for the pronunciation dictionary.
    - `items` PronunciationDictItem[] — List of pronunciation items (alias or phoneme type).
      - union — A single pronunciation dictionary item. Use type 'alias' to replace matched text with a spoken alias, or type 'phoneme' to specify exact pronunciation using IPA notation.
        - PronunciationDictAliasItem — An alias pronunciation item. When the `text` value is found in input, it is replaced with the `alias` before speech synthesis.
          - `alias` string, required — The replacement text that will be spoken instead.
          - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
          - `type` 'alias', required — The item type.
        - PronunciationDictPhonemeItem — A phoneme pronunciation item. When the `text` value is found in input, it is pronounced using the specified IPA phoneme notation.
          - `alphabet` 'ipa', required — The phonetic alphabet used for the phoneme notation.
          - `phoneme` string, required — The phoneme notation representing the desired pronunciation.
          - `text` string, required — The text to match in the input. Case-insensitive matching is used during synthesis.
          - `type` 'phoneme', required — The item type.
    - `name` string — Human-readable name for the dictionary. Must be unique within the organization.
    - `record_type` 'pronunciation_dict' — Identifies the resource type.
    - `updated_at` string, date-time — ISO 8601 timestamp with millisecond precision.
    - `version` integer — Auto-incrementing version number. Increases by 1 on each update. Used for optimistic concurrency control and cache invalidation.

## Other responses

- `401` — Unauthorized. Invalid or missing API key.
- `422` — Validation error or organization limit exceeded.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)