Brand Glossary

A brand glossary holds your terms and how HeyGen should treat them: how the voice pronounces them, and whether translation keeps or replaces them. Pass its brand_glossary_id on a video or translation request to apply it. Each workspace has one glossary, and it holds rules for any number of languages. Author it in the HeyGen app under Brand Kit or over the API; edits in either place show up in the other.

API reference: Create Brand Glossary · Update Brand Glossary · Get Brand Glossary · List Brand Glossaries · Delete Brand Glossary

What a glossary holds

List	Applies in	Effect
`terms`	Generation: Studio, Templates, `avatar` and `image` videos, Video Agent	The voice says the `pronunciation` or `ipa` instead of `term`. Captions keep the original spelling.
`do_not_translate_terms`	Translation: video translation over the API, and a Studio or Video Agent draft translated in the HeyGen app	`term` stays untranslated in every target language.
`forced_translations`	Translation, as above	`term` becomes its exact `translation`.

Matching is case-insensitive. Any rule in terms or forced_translations can apply to all languages or to one.

Quickstart

Find the workspace glossary, or create it if there is none:

curl "https://api.heygen.com/v3/brand-glossaries" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl -X POST "https://api.heygen.com/v3/brand-glossaries" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Product Names",
    "terms": [{ "term": "HeyGen", "pronunciation": "hey-jen" }]
  }'

Then pass its ID on a video:

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
    "avatar_id": "YOUR_AVATAR_ID",
    "script": "Welcome to HeyGen.",
    "voice_id": "YOUR_VOICE_ID"
  }'

Pronunciations

Respellings, IPA, and per-language pronunciations.

Translation rules

Keep terms untranslated or force an exact translation.

Manage a glossary

Create, update, read, and delete over the API.

Apply a glossary

Use it on videos, templates, Video Agent, and translations.

Errors

Status	Code	Meaning
`400`	`invalid_parameter`	A field is out of range, `ipa` was sent by an account without IPA, or more than 10 entries need a generated respelling. `param` names the field.
`403`	`ai_vendor_access_restricted`	The workspace’s AI vendor policy blocks respelling generation. Send `pronunciation` with each `ipa`.
`404`	`resource_not_found`	No glossary with that ID in this workspace.
`409`	`conflict`	The workspace already has a glossary, a glossary with this name already exists, a term is repeated for the same language within one list, or the glossary changed during the update. Read it again and retry.
`409`	`request_in_progress`	A request with this `Idempotency-Key` is still running. Retry shortly.
`429`	`rate_limit_exceeded`	Retry after `Retry-After`.
`503`	`service_unavailable`	Temporary, including a failed respelling generation. Nothing was saved. Retry shortly.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

What a glossary holds

Quickstart

Pronunciations

Translation rules

Manage a glossary

Apply a glossary

Errors

​What a glossary holds

​Quickstart

Pronunciations

Translation rules

Manage a glossary

Apply a glossary

​Errors

What a glossary holds

Quickstart

Errors