> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a pronunciation dictionary

> Create a named pronunciation dictionary and validate its complete contents atomically.

<Note>
The service assigns the dictionary ID. Keep the returned `name` as the stable resource identifier and the returned `etag` for subsequent updates or deletion.
</Note>

The service validates every entry before saving the dictionary. The complete request fails if an entry is invalid, two entries match after language-aware lexical matching, or the dictionary exceeds a limit.

<Warning>
Create has no idempotency key. If the connection fails before you receive a response, do not retry blindly: the service might have committed the dictionary. List the workspace's dictionaries and reconcile the result first, or a retry can create a duplicate resource.
</Warning>

## API reference

**Endpoint:** `POST https://api.inworld.ai/pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, send `Basic $INWORLD_API_KEY`. Use a Standard API key for the target workspace. Voices Read access permits list and get; Voices Write access permits all five methods.

### Path parameters

- `workspaceId` (string; required) — ID of the workspace that owns the dictionary. It must match a workspace accessible to the API key.

### Request body

Content type: `application/json`

- `displayName` (string; required) — Non-blank human-readable dictionary name, containing at most 64 Unicode code points.
- `pronunciations` (object[]; default: []) — Complete dictionary contents. A dictionary can contain up to 1,000 entries and must remain within the 512 KiB encoded dictionary limit. Entries must be unique after language-aware lexical canonicalization.
  - `displayHeadword` (string; required) — Caller-facing spelling. It must be non-blank and tokenize to exactly one replaceable lexical token.
  - `languageCode` (string; required) — Concrete language supported for pronunciation entries, in its exact canonical BCP-47 spelling: for example, `en-US`, not `en-us`, `EN_US`, or `en`. Blank values and `auto` are not accepted. The general TTS language list is not a pronunciation catalog. See [Author pronunciation entries](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#author-pronunciation-entries).
  - `phoneSymbols` (string[]; required) — Ordered array of complete phone tokens supported for the selected language, not a slash-delimited or whitespace-separated IPA string. Each token can contain at most 16 Unicode code points. Preserve compound-phone token boundaries; do not split by Unicode character. Supported aliases may be canonicalized in the response. See [phone-token guidance and examples](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#send-phone-tokens-not-an-ipa-string).

#### Request example

```json
{
  "displayName": "Product names",
  "pronunciations": [
    {
      "displayHeadword": "Cat",
      "languageCode": "en-US",
      "phoneSymbols": [
        "k",
        "æ",
        "t"
      ]
    },
    {
      "displayHeadword": "Ship",
      "languageCode": "en-US",
      "phoneSymbols": [
        "ʃ",
        "ɪ",
        "p"
      ]
    }
  ]
}
```

### Response

Status: `200`. Content type: `application/json`.

- `name` (string; required) — Service-assigned resource name in the form `workspaces/{workspace}/pronunciationDictionaries/{uuid}`.
- `displayName` (string; required) — Non-blank human-readable dictionary name, containing at most 64 Unicode code points.
- `pronunciations` (object[]; required; default: []) — Complete dictionary contents. A dictionary can contain up to 1,000 entries and must remain within the 512 KiB encoded dictionary limit. Entries must be unique after language-aware lexical canonicalization.
  - `displayHeadword` (string; required) — Caller-facing spelling. It must be non-blank and tokenize to exactly one replaceable lexical token.
  - `languageCode` (string; required) — Concrete language supported for pronunciation entries, in its exact canonical BCP-47 spelling: for example, `en-US`, not `en-us`, `EN_US`, or `en`. Blank values and `auto` are not accepted. The general TTS language list is not a pronunciation catalog. See [Author pronunciation entries](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#author-pronunciation-entries).
  - `phoneSymbols` (string[]; required) — Ordered array of complete phone tokens supported for the selected language, not a slash-delimited or whitespace-separated IPA string. Each token can contain at most 16 Unicode code points. Preserve compound-phone token boundaries; do not split by Unicode character. Supported aliases may be canonicalized in the response. See [phone-token guidance and examples](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#send-phone-tokens-not-an-ipa-string).
- `etag` (string; required) — Optimistic-concurrency token. Include the current value when updating or deleting the dictionary.
- `createTime` (string; required) — Time at which the dictionary was created.
- `updateTime` (string; required) — Time at which the dictionary's metadata or contents last changed.

### Response examples

#### 200: createdDictionary

```json
{
  "name": "workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988",
  "displayName": "Product names",
  "pronunciations": [
    {
      "displayHeadword": "Cat",
      "languageCode": "en-US",
      "phoneSymbols": [
        "k",
        "æ",
        "t"
      ]
    },
    {
      "displayHeadword": "Ship",
      "languageCode": "en-US",
      "phoneSymbols": [
        "ʃ",
        "ɪ",
        "p"
      ]
    }
  ],
  "etag": "tLKwUsvfq4TjPZQYhA9Dg3pM",
  "createTime": "2026-08-14T18:22:31.145Z",
  "updateTime": "2026-08-14T18:22:31.145Z"
}
```

#### default: default_response

```json
{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}
```

### Code examples

#### cURL

```bash
curl --request POST \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "displayName": "Product names",
    "pronunciations": [
      {
        "displayHeadword": "Cat",
        "languageCode": "en-US",
        "phoneSymbols": ["k", "æ", "t"]
      }
    ]
  }'
```

#### Python

```python
import os
import requests

workspace_id = os.environ["INWORLD_WORKSPACE_ID"]
url = (
    "https://api.inworld.ai/pronunciations/v1/"
    f"workspaces/{workspace_id}/pronunciationDictionaries"
)
response = requests.post(
    url,
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "displayName": "Product names",
        "pronunciations": [
            {
                "displayHeadword": "Cat",
                "languageCode": "en-US",
                "phoneSymbols": ["k", "æ", "t"],
            }
        ],
    },
)
response.raise_for_status()
print(response.json())
```

#### JavaScript

```javascript
const workspaceId = process.env.INWORLD_WORKSPACE_ID;
const url = `https://api.inworld.ai/pronunciations/v1/workspaces/${workspaceId}/pronunciationDictionaries`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${process.env.INWORLD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    displayName: 'Product names',
    pronunciations: [
      {
        displayHeadword: 'Cat',
        languageCode: 'en-US',
        phoneSymbols: ['k', 'æ', 't'],
      },
    ],
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```