> ## Documentation Index
> Fetch the complete documentation index at: https://dev.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.
The service assigns the dictionary ID. Keep the returned `name` as the stable resource identifier and the returned `etag` for subsequent updates or deletion.
Every entry is validated before the dictionary is committed. An invalid entry, an entry that duplicates another entry after language-aware lexical matching, or a dictionary that exceeds a limit causes the complete request to fail.
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.
## OpenAPI
````yaml post /pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries
openapi: 3.0.0
info:
title: Inworld Pronunciation Dictionaries API
version: v1
description: >-
Create and manage named pronunciation dictionaries. Each dictionary contains
its complete set of pronunciation entries; create and update validate the
supplied contents before committing them atomically.
contact:
name: Inworld AI
url: https://inworld.ai
email: support@inworld.ai
servers:
- url: https://api.inworld.ai
security:
- inworld_basic: []
tags:
- name: Pronunciation dictionaries
description: Manage workspace-owned named pronunciation dictionaries.
paths:
/pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries:
post:
tags:
- Pronunciation dictionaries
summary: Create a pronunciation dictionary
description: >-
Creates a named pronunciation dictionary with its complete contents. The
service validates and canonicalizes every entry before committing the
dictionary, then assigns its resource ID. If any entry is invalid or
duplicates another entry's normalized lexical identity, the entire
request fails without creating a partial dictionary.
operationId: Pronunciations_CreatePronunciationDictionary
parameters:
- $ref: '#/components/parameters/workspaceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PronunciationDictionaryCreate'
example:
displayName: Product names
pronunciations:
- displayHeadword: Hello
languageCode: en-US
phoneSymbols:
- h
- ə
- l
- oʊ
- displayHeadword: World
languageCode: en-US
phoneSymbols:
- w
- ɜː
- l
- d
responses:
'200':
description: The dictionary was created.
content:
application/json:
schema:
$ref: '#/components/schemas/PronunciationDictionary'
examples:
createdDictionary:
$ref: '#/components/examples/pronunciationDictionary'
default:
$ref: '#/components/responses/error'
x-codeSamples:
- lang: bash
label: cURL
source: |-
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": "Hello",
"languageCode": "en-US",
"phoneSymbols": ["h", "ə", "l", "oʊ"]
}
]
}'
- lang: python
label: Python
source: |-
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": "Hello",
"languageCode": "en-US",
"phoneSymbols": ["h", "ə", "l", "oʊ"],
}
],
},
)
response.raise_for_status()
print(response.json())
- lang: javascript
label: JavaScript
source: >-
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: 'Hello',
languageCode: 'en-US',
phoneSymbols: ['h', 'ə', 'l', 'oʊ'],
},
],
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
components:
parameters:
workspaceId:
name: workspaceId
in: path
required: true
description: >-
ID of the workspace that owns the dictionary. It must match a workspace
accessible to the API key.
schema:
type: string
minLength: 1
maxLength: 61
pattern: ^[a-z0-9_-]+$
example: my-workspace
schemas:
PronunciationDictionaryCreate:
type: object
required:
- displayName
properties:
displayName:
$ref: '#/components/schemas/PronunciationDictionaryDisplayName'
pronunciations:
$ref: '#/components/schemas/PronunciationEntries'
additionalProperties: false
PronunciationDictionary:
type: object
description: >-
A workspace-owned named pronunciation dictionary with its complete
contents.
required:
- name
- displayName
- pronunciations
- etag
- createTime
- updateTime
properties:
name:
type: string
readOnly: true
description: >-
Service-assigned resource name in the form
`workspaces/{workspace}/pronunciationDictionaries/{uuid}`.
example: >-
workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988
displayName:
$ref: '#/components/schemas/PronunciationDictionaryDisplayName'
pronunciations:
$ref: '#/components/schemas/PronunciationEntries'
etag:
type: string
description: >-
Optimistic-concurrency token. Include the current value when
updating or deleting the dictionary.
createTime:
type: string
format: date-time
readOnly: true
description: Time at which the dictionary was created.
updateTime:
type: string
format: date-time
readOnly: true
description: Time at which the dictionary's metadata or contents last changed.
additionalProperties: false
PronunciationDictionaryDisplayName:
type: string
minLength: 1
maxLength: 64
description: >-
Non-blank human-readable dictionary name, containing at most 64 Unicode
code points.
example: Product names
PronunciationEntries:
type: array
maxItems: 1000
description: >-
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.
items:
$ref: '#/components/schemas/PronunciationEntry'
default: []
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
description: gRPC status code.
message:
type: string
description: Developer-facing error message.
details:
type: array
description: >-
Structured error details. Validation failures can include
`google.rpc.BadRequest` field violations without echoing
customer-authored pronunciation content.
items:
$ref: '#/components/schemas/protobufAny'
PronunciationEntry:
type: object
description: >-
One validated pronunciation override. The service can canonicalize
supported phone aliases before returning the saved entry.
required:
- displayHeadword
- languageCode
- phoneSymbols
properties:
displayHeadword:
type: string
minLength: 1
maxLength: 128
description: >-
Caller-facing spelling. It must be non-blank and tokenize to exactly
one replaceable lexical token.
example: Hello
languageCode:
type: string
minLength: 1
description: >-
Supported canonical BCP-47 language code, such as `en-US`. Use the
exact canonical spelling; `auto` and unspecified languages are not
accepted.
example: en-US
phoneSymbols:
type: array
minItems: 1
maxItems: 64
description: >-
Ordered phone tokens or supported aliases. Each token can contain at
most 16 Unicode code points and must be valid for the selected
language. Send symbols without `/` delimiters.
items:
type: string
minLength: 1
maxLength: 16
example:
- h
- ə
- l
- oʊ
additionalProperties: false
protobufAny:
type: object
properties:
'@type':
type: string
description: A URL identifying the serialized protocol-buffer message type.
additionalProperties: true
examples:
pronunciationDictionary:
summary: A complete pronunciation dictionary
value:
name: >-
workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988
displayName: Product names
pronunciations:
- displayHeadword: Hello
languageCode: en-US
phoneSymbols:
- h
- ə
- l
- oʊ
- displayHeadword: World
languageCode: en-US
phoneSymbols:
- w
- ɜː
- l
- d
etag: tLKwUsvfq4TjPZQYhA9Dg3pM
createTime: '2026-08-14T18:22:31.145Z'
updateTime: '2026-08-14T18:22:31.145Z'
responses:
error:
description: The request failed.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
securitySchemes:
inworld_basic:
type: apiKey
in: header
name: Authorization
description: >-
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.
````