Brand Glossary

Control how HeyGen says and translates your custom terms. Create a brand glossary over the API with pronunciations, do-not-translate terms, and forced translations, then pass its brand_glossary_id on videos and translations.

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. Glossaries can be authored in the HeyGen app under Brand Kit or over the API; the API is how you give each of your own customers their own vocabulary.

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

Three lists

List	Applies in	Effect
terms	Generation: Studio, Templates, avatar and image videos, Video Agent	The voice says pronunciation 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 in every target language.

Translation rules take effect only through a translation feature; plain video generation and text-to-speech use terms alone. Matching is case-insensitive. A translation is inserted verbatim with no inflection, so pick a form that reads correctly on its own. Put a term in do_not_translate_terms or forced_translations, not both.

Create

POST /v3/brand-glossaries takes a name (1–64 characters, unique per workspace) and any of the three lists. The 201 response is the full glossary, usable immediately.

curl -X POST "https://api.heygen.com/v3/brand-glossaries" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Acme Product Names",
    "terms": [
      { "term": "HeyGen", "pronunciation": "hey-jen" },
      { "term": "2024", "pronunciation": "twenty twenty-four" }
    ],
    "do_not_translate_terms": [
      { "term": "HeyGen" }
    ],
    "forced_translations": [
      { "term": "CEO", "translation": "Geschäftsführer" }
    ]
  }'

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

Update

PATCH /v3/brand-glossaries/{brand_glossary_id} replaces each field independently. Omit a field to leave it alone, send a list to replace it in full, send [] to clear it. Send at least one field. A term repeated within one list returns 409 conflict.

To add a single entry, read the glossary, append, and send the whole list back:

import requests

base = "https://api.heygen.com/v3/brand-glossaries/8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
headers = {"X-Api-Key": HEYGEN_API_KEY}

current = requests.get(base, headers=headers).json()["data"]["terms"]
current.append({"term": "Reformer", "pronunciation": "ree-form-er"})

requests.patch(base, headers=headers, json={"terms": current})

Tone settings are managed in the HeyGen app under Brand Kit and are untouched by PATCH.

Read

GET /v3/brand-glossaries lists names, IDs, and timestamps, paged with limit and token. GET /v3/brand-glossaries/{brand_glossary_id} returns the full glossary; do_not_translate_terms and forced_translations appear whenever the glossary has rules of that kind, including rules set in the app. Read it when a video pronounces or translates a term unexpectedly.

Delete

DELETE /v3/brand-glossaries/{brand_glossary_id} removes a glossary. Videos and translations already created with it are unaffected. This cannot be undone.

Apply

Pass brand_glossary_id at the top level of the request, one glossary per call:

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": "HeyGen shipped this in 2024.",
    "voice_id": "YOUR_VOICE_ID"
  }'

On Brand lists every endpoint that accepts the field. On POST /v3/video-agents it is set once per session. In a translation batch or video batch it is set per item. Scenes with their own audio_url or audio_asset_id have no synthesis step, so terms leaves them unchanged.

An unknown brand_glossary_id fails the request with 400 before rendering, so no credits are spent. Glossaries are workspace-scoped: an ID visible in the app is rejected if the API key belongs to another workspace.

Errors

Status	Code	Meaning
400	invalid_parameter	A field is out of range. param names the field.
404	resource_not_found	No glossary with that ID in this workspace.
409	conflict	A glossary with this name already exists, or a term is repeated within one list.
409	request_in_progress	A request with this Idempotency-Key is still running. Retry shortly.
429	rate_limit_exceeded	Retry after Retry-After.

Migrating from v1 brand voice

brand_voice_id is the deprecated former name of brand_glossary_id. It is still accepted on POST /v3/templates/{template_id}, POST /v3/video-translations, and POST /v3/video-translations/proofreads. POST /v3/videos accepts brand_glossary_id only.

The legacy POST /v1/brand_voice/{brand_voice_id} lists map to the v3 glossary as follows, ahead of the October 31, 2026 v1/v2 sunset:

v1 field	v1 shape	v3 field	v3 shape
vocabulary	[["HeyGen", "hey-jen"]]	terms	[{ "term": "HeyGen", "pronunciation": "hey-jen" }]
blacklist	["HeyGen"]	do_not_translate_terms	[{ "term": "HeyGen" }]
whitelist	[["CEO", "Geschäftsführer"]]	forced_translations	[{ "term": "CEO", "translation": "Geschäftsführer" }]
tones, tone	—	—	Managed in the HeyGen app under Brand Kit.