> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a pronunciation dictionary > 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) ## OpenAPI ````yaml /openapi/source/external/text-to-speech/pronunciation-dicts.json post /pronunciation_dicts openapi: 3.1.0 info: version: 1.0.0 title: Telnyx API x-latency-category: interactive x-endpoint-cost: light description: >- Pronunciation Dictionaries allow you to control how specific words and phrases are spoken during text-to-speech synthesis. Create dictionaries containing alias items (text replacement) and phoneme items (IPA pronunciation notation) that are applied before speech generation. license: name: MIT url: https://github.com/openai/openai-openapi/blob/master/LICENSE contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Telnyx API v2 security: - bearerAuth: [] tags: - name: Pronunciation Dictionaries description: >- Manage pronunciation dictionaries for text-to-speech synthesis. Dictionaries contain alias items (text replacement) and phoneme items (IPA pronunciation notation) that control how specific words are spoken. paths: /pronunciation_dicts: post: tags: - Pronunciation Dictionaries summary: Create a pronunciation dictionary description: >- 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) operationId: CreatePronunciationDict requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePronunciationDictRequest' multipart/form-data: schema: type: object required: - name - file properties: name: type: string description: Human-readable name. Must be unique within the organization. minLength: 1 maxLength: 255 example: Brand Names file: type: string format: binary description: >- Dictionary file to upload. Supported formats: PLS/XML (.pls, .xml) and plain text (.txt). Max size: 1MB (1,048,576 bytes). responses: '201': description: Pronunciation dictionary created successfully. content: application/json: schema: $ref: '#/components/schemas/PronunciationDictResponse' '401': description: Unauthorized. Invalid or missing API key. '422': description: Validation error or organization limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: errors: - code: '90202' title: Validation failed detail: items must have at least one item source: pointer: /items limit_exceeded: summary: Organization limit exceeded value: errors: - code: '90203' title: Limit exceeded detail: >- Maximum number of pronunciation dictionaries (50) reached source: pointer: / duplicate_name: summary: Duplicate dictionary name value: errors: - code: '90202' title: Validation failed detail: >- organization_id, name a dictionary with this name already exists source: pointer: /organization_id, name x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const pronunciationDict = await client.pronunciationDicts.create({ items: [ { alias: 'tel-nicks', text: 'Telnyx', type: 'alias', }, ], name: 'Brand Names', }); console.log(pronunciationDict.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) pronunciation_dict = client.pronunciation_dicts.create( items=[{ "alias": "tel-nicks", "text": "Telnyx", "type": "alias", }], name="Brand Names", ) print(pronunciation_dict.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpronunciationDict, err := client.PronunciationDicts.New(context.TODO(), telnyx.PronunciationDictNewParams{\n\t\tItems: []telnyx.PronunciationDictNewParamsItemUnion{{\n\t\t\tOfAlias: &telnyx.PronunciationDictAliasItemParam{\n\t\t\t\tAlias: \"tel-nicks\",\n\t\t\t\tText: \"Telnyx\",\n\t\t\t\tType: telnyx.PronunciationDictAliasItemTypeAlias,\n\t\t\t},\n\t\t}},\n\t\tName: \"Brand Names\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", pronunciationDict.Data)\n}\n" - lang: Java source: >- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictAliasItem; import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateParams; import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); PronunciationDictCreateParams params = PronunciationDictCreateParams.builder() .addItem(PronunciationDictAliasItem.builder() .alias("tel-nicks") .text("Telnyx") .type(PronunciationDictAliasItem.Type.ALIAS) .build()) .name("Brand Names") .build(); PronunciationDictCreateResponse pronunciationDict = client.pronunciationDicts().create(params); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") pronunciation_dict = telnyx.pronunciation_dicts.create( items: [{alias: "tel-nicks", text: "Telnyx", type: :alias}], name: "Brand Names" ) puts(pronunciation_dict) - lang: PHP source: >- pronunciationDicts->create( items: [['alias' => 'tel-nicks', 'text' => 'Telnyx', 'type' => 'alias']], name: 'Brand Names', ); var_dump($pronunciationDict); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx pronunciation-dicts create \ --api-key 'My API Key' \ --item '{alias: tel-nicks, text: Telnyx, type: alias}' \ --name 'Brand Names' components: schemas: CreatePronunciationDictRequest: type: object description: Request body for creating a pronunciation dictionary. required: - name - items properties: name: type: string description: Human-readable name. Must be unique within the organization. minLength: 1 maxLength: 255 example: Brand Names items: type: array description: >- List of pronunciation items (alias or phoneme type). At least one item is required. minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/PronunciationDictItem' PronunciationDictResponse: type: object description: Response containing a single pronunciation dictionary. properties: data: $ref: '#/components/schemas/PronunciationDictData' ErrorResponse: type: object description: Standard Telnyx error response. properties: errors: type: array items: $ref: '#/components/schemas/ErrorObject' PronunciationDictItem: description: >- 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. oneOf: - $ref: '#/components/schemas/PronunciationDictAliasItem' - $ref: '#/components/schemas/PronunciationDictPhonemeItem' discriminator: propertyName: type mapping: alias: $ref: '#/components/schemas/PronunciationDictAliasItem' phoneme: $ref: '#/components/schemas/PronunciationDictPhonemeItem' PronunciationDictData: type: object description: A pronunciation dictionary record. properties: record_type: type: string description: Identifies the resource type. enum: - pronunciation_dict example: pronunciation_dict id: type: string format: uuid description: Unique identifier for the pronunciation dictionary. example: c215a3e1-be41-4701-97e8-1d3c22f9a5b7 name: type: string description: >- Human-readable name for the dictionary. Must be unique within the organization. example: Brand Names items: type: array description: List of pronunciation items (alias or phoneme type). items: $ref: '#/components/schemas/PronunciationDictItem' version: type: integer description: >- Auto-incrementing version number. Increases by 1 on each update. Used for optimistic concurrency control and cache invalidation. example: 1 created_at: type: string format: date-time description: ISO 8601 timestamp with millisecond precision. example: '2026-03-25T12:00:00.000Z' updated_at: type: string format: date-time description: ISO 8601 timestamp with millisecond precision. example: '2026-03-25T12:00:00.000Z' ErrorObject: type: object properties: code: type: string description: Machine-readable error code. example: '90202' title: type: string description: Short human-readable error title. example: Validation failed detail: type: string description: Detailed error description. example: items must have at least one item source: type: object description: Source of the error. properties: pointer: type: string description: JSON pointer to the field that caused the error. example: /items PronunciationDictAliasItem: type: object description: >- An alias pronunciation item. When the `text` value is found in input, it is replaced with the `alias` before speech synthesis. required: - text - type - alias additionalProperties: false properties: text: type: string description: >- The text to match in the input. Case-insensitive matching is used during synthesis. minLength: 1 maxLength: 200 example: Telnyx type: type: string description: The item type. enum: - alias example: alias alias: type: string description: The replacement text that will be spoken instead. minLength: 1 maxLength: 500 example: tel-nicks PronunciationDictPhonemeItem: type: object description: >- A phoneme pronunciation item. When the `text` value is found in input, it is pronounced using the specified IPA phoneme notation. required: - text - type - phoneme - alphabet additionalProperties: false properties: text: type: string description: >- The text to match in the input. Case-insensitive matching is used during synthesis. minLength: 1 maxLength: 200 example: Telnyx type: type: string description: The item type. enum: - phoneme example: phoneme phoneme: type: string description: The phoneme notation representing the desired pronunciation. minLength: 1 maxLength: 500 example: ˈtɛl.nɪks alphabet: type: string description: The phonetic alphabet used for the phoneme notation. enum: - ipa example: ipa securitySchemes: bearerAuth: type: http scheme: bearer description: Telnyx API v2 key. Obtain from https://portal.telnyx.com ````