> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciations

> Set how HeyGen voices say your custom terms with a brand glossary: respellings for every voice, IPA for exact sounds and stress, and per-language pronunciations.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=3e4c2594813dcfd56985f3d63e3ba321)

The `terms` list of a [brand glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md) sets how the voice says each term. Every entry has a `term`, matched case-insensitively in the script, and at least one way to say it: a respelling in `pronunciation`, an IPA transcription in `ipa`, or both. Pronunciations change the audio only; captions and subtitles keep the original spelling.

| Field | Read by |
| - | - |
| `pronunciation` | Every voice |
| `ipa` | HeyGen Voice, ElevenLabs, and Cartesia voices, which use it in place of `pronunciation` |

## Respellings

A respelling is written the way you would coach someone to say the term: `hey-jen`, `hyper frames`, `twenty twenty-four`. Add a term once you have heard it come out wrong.

```json theme={null}
{
  "terms": [
    { "term": "HeyGen", "pronunciation": "hey-jen" },
    { "term": "HyperFrames", "pronunciation": "hyper frames" },
    { "term": "2024", "pronunciation": "twenty twenty-four" }
  ]
}
```

## IPA

> [!NOTE]
>
> IPA is enabled per account. [Contact sales](https://www.heygen.com/contact-us/sales) to turn it on. Accounts without it get `400 invalid_parameter` on any request that sends `ipa`, and responses leave the field out.

An [IPA](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) transcription fixes the exact sounds and stress, so it is the better choice for drug names, personal names, and words a respelling cannot pin down.

```bash theme={null}
curl -X PATCH "https://api.heygen.com/v3/brand-glossaries/8c2d5e91a47b4f3c8d1e6a9b2f5c7d40" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      { "term": "HeyGen", "pronunciation": "hey-jen", "ipa": "/ˈheɪ.dʒɛn/" },
      { "term": "Keytruda", "ipa": "/kiːˈtruː.də/" },
      { "term": "Siobhan", "ipa": "/ʃɪˈvɔːn/" },
      { "term": "Acme", "ipa": "/ˈæk.mi/" },
      { "term": "Acme", "ipa": "/ak.me/", "pronunciation_language": { "scope": "specific", "code": "fr" } }
    ]
  }'
```

* Send `pronunciation`, `ipa`, or both. With `ipa` alone, HeyGen writes the respelling for you and returns it, so every voice has a pronunciation to read.
* HeyGen generates up to 10 respellings per minute, and up to 10 per request. Send `pronunciation` with any further entries, or spread them over several requests that each send the full list.
* Write `ipa` between slashes, as in `/ˈheɪ.dʒɛn/`, in up to 512 characters.
* Respelling generation runs on Google AI. If the workspace's [AI vendor policy](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md#ai-vendor-access-restricted) blocks it, send both fields. If generation fails, the request returns `503` and nothing is saved.

The response shows what was stored, including generated respellings:

```json theme={null}
{
  "term": "Keytruda",
  "pronunciation": "kee-TROO-duh",
  "ipa": "/kiːˈtruː.də/"
}
```

### Editing IPA

[Updates](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/manage.md#update) replace the `terms` list in full. Within that list:

* An entry sent back with the same `pronunciation` and language keeps its IPA, with or without `ipa` in the body.
* Changing `pronunciation` without sending `ipa` clears the old IPA, since it no longer matches.
* `"ipa": null` with a `pronunciation` removes IPA from the entry.
* Teammates without IPA access can still edit the glossary, and the entries they leave unchanged keep their IPA.

## Per-language pronunciations

Add `pronunciation_language` to apply a pronunciation in one language:

```json theme={null}
{
  "terms": [
    { "term": "Acme", "pronunciation": "ack-mee" },
    { "term": "Acme", "pronunciation": "ak-may", "pronunciation_language": { "scope": "specific", "code": "fr" } }
  ]
}
```

Here French videos say `ak-may` and every other language says `ack-mee`.

* Omit the field, or send `{ "scope": "all" }`, for a rule that applies to all languages.
* `code` is a base language code: `fr`, `es`, `de`.
* A language-specific rule takes precedence over an all-languages rule for that language.
* A term can appear once per language.

Responses include `pronunciation_language` only on language-specific rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.