Update a pronunciation dictionary - Inworld AI Documentation

cURL

curl --request PATCH \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"displayName\":\"Product names v2\",\"pronunciations\":[{\"displayHeadword\":\"World\",\"languageCode\":\"en-US\",\"phoneSymbols\":[\"w\",\"ɜː\",\"l\",\"d\"]}],\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"

import os
import requests

workspace_id = os.environ["INWORLD_WORKSPACE_ID"]
dictionary_id = os.environ["PRONUNCIATION_DICTIONARY_ID"]
url = (
    "https://api.inworld.ai/pronunciations/v1/"
    f"workspaces/{workspace_id}/pronunciationDictionaries/{dictionary_id}"
)
response = requests.patch(
    url,
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "displayName": "Product names v2",
        "pronunciations": [
            {
                "displayHeadword": "World",
                "languageCode": "en-US",
                "phoneSymbols": ["w", "ɜː", "l", "d"],
            }
        ],
        "etag": os.environ["PRONUNCIATION_DICTIONARY_ETAG"],
    },
)
response.raise_for_status()
print(response.json())

const { INWORLD_API_KEY, INWORLD_WORKSPACE_ID, PRONUNCIATION_DICTIONARY_ID, PRONUNCIATION_DICTIONARY_ETAG } = process.env;
const url = `https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}`;

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    Authorization: `Basic ${INWORLD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    displayName: 'Product names v2',
    pronunciations: [
      {
        displayHeadword: 'World',
        languageCode: 'en-US',
        phoneSymbols: ['w', 'ɜː', 'l', 'd'],
      },
    ],
    etag: PRONUNCIATION_DICTIONARY_ETAG,
  }),
});

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

{
  "name": "workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988",
  "displayName": "Product names",
  "pronunciations": [],
  "etag": "<string>",
  "createTime": "2023-11-07T05:31:56Z",
  "updateTime": "2023-11-07T05:31:56Z"
}

{
  "code": 10,
  "message": "Pronunciation dictionary etag does not match",
  "details": []
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

PATCH

pronunciations

workspaces

{workspaceId}

pronunciationDictionaries

{pronunciationDictionaryId}

cURL

curl --request PATCH \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"displayName\":\"Product names v2\",\"pronunciations\":[{\"displayHeadword\":\"World\",\"languageCode\":\"en-US\",\"phoneSymbols\":[\"w\",\"ɜː\",\"l\",\"d\"]}],\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"

import os
import requests

workspace_id = os.environ["INWORLD_WORKSPACE_ID"]
dictionary_id = os.environ["PRONUNCIATION_DICTIONARY_ID"]
url = (
    "https://api.inworld.ai/pronunciations/v1/"
    f"workspaces/{workspace_id}/pronunciationDictionaries/{dictionary_id}"
)
response = requests.patch(
    url,
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "displayName": "Product names v2",
        "pronunciations": [
            {
                "displayHeadword": "World",
                "languageCode": "en-US",
                "phoneSymbols": ["w", "ɜː", "l", "d"],
            }
        ],
        "etag": os.environ["PRONUNCIATION_DICTIONARY_ETAG"],
    },
)
response.raise_for_status()
print(response.json())

const { INWORLD_API_KEY, INWORLD_WORKSPACE_ID, PRONUNCIATION_DICTIONARY_ID, PRONUNCIATION_DICTIONARY_ETAG } = process.env;
const url = `https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}`;

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    Authorization: `Basic ${INWORLD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    displayName: 'Product names v2',
    pronunciations: [
      {
        displayHeadword: 'World',
        languageCode: 'en-US',
        phoneSymbols: ['w', 'ɜː', 'l', 'd'],
      },
    ],
    etag: PRONUNCIATION_DICTIONARY_ETAG,
  }),
});

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

{
  "name": "workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988",
  "displayName": "Product names",
  "pronunciations": [],
  "etag": "<string>",
  "createTime": "2023-11-07T05:31:56Z",
  "updateTime": "2023-11-07T05:31:56Z"
}

{
  "code": 10,
  "message": "Pronunciation dictionary etag does not match",
  "details": []
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Updating pronunciations replaces the complete entry list. Entries omitted from the request are deleted, and an empty list clears the dictionary.

The request must include the current etag. If another writer has changed the dictionary, the stale etag returns HTTP 409 Conflict instead of overwriting the newer state. Get the dictionary again, reconcile the changes, and retry with the new value. The primary example supplies both mutable fields and omits updateMask, so both displayName and pronunciations are updated. The pronunciations value must contain the complete desired dictionary; entries omitted from it are deleted.

Update selected fields

Use the optional updateMask query parameter for a partial update. Its comma-separated field names use the same lowerCamelCase spelling as the JSON request body. For example, rename a dictionary without changing its entries:

curl --request PATCH \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}?updateMask=displayName" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"displayName\":\"Product names v2\",\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"

Supported fields are displayName and pronunciations. Omit updateMask or set it to * only when you intend to update both fields and supply both values.

Authorizations

Authorization

string

header

required

Your authentication 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.

Required string length: 1 - 61

Pattern: ^[a-z0-9_-]+$

Example:

"my-workspace"

pronunciationDictionaryId

string<uuid>

required

Service-assigned UUID from the dictionary's resource name.

Example:

"2d470a1e-0262-4f22-9b46-5353d454d988"

Query Parameters

updateMask

string

Comma-separated fields to update, using lowerCamelCase JSON names. Supported fields are displayName and pronunciations. Omit this parameter or set it to * to update all mutable fields.

Example:

"displayName,pronunciations"

Body

application/json

Mutable dictionary fields and the current concurrency token. When updateMask is omitted, supply both mutable fields because both are applied; an explicit mask selects a partial update.

etag

string

required

Current dictionary etag. A stale value fails the update rather than overwriting a concurrent change.

Minimum string length: 1

displayName

string

Non-blank human-readable dictionary name, containing at most 64 Unicode code points.

Required string length: 1 - 64

Example:

"Product names"

pronunciations

object[]

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.

Maximum array length: 1000

Show child attributes

Response

The updated complete dictionary.

A workspace-owned named pronunciation dictionary with its complete contents.

name

string

required

read-only

Service-assigned resource name in the form workspaces/{workspace}/pronunciationDictionaries/{uuid}.

Example:

"workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988"

displayName

string

required

Non-blank human-readable dictionary name, containing at most 64 Unicode code points.

Required string length: 1 - 64

Example:

"Product names"

pronunciations

object[]

required

Maximum array length: 1000

Show child attributes

etag

string

required

Optimistic-concurrency token. Include the current value when updating or deleting the dictionary.

createTime

string<date-time>

required

read-only

Time at which the dictionary was created.

updateTime

string<date-time>

required

read-only

Time at which the dictionary's metadata or contents last changed.

​Update selected fields

Authorizations

Path Parameters

Query Parameters

Body

Response

Update selected fields