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.

The terms list of a brand glossary 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.

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

IPA

IPA is enabled per account. Contact 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 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.

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 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:

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

Editing IPA

Updates 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:

{
  "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.