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. 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. If a term is in both do_not_translate_terms and forced_translations, it stays untranslated.

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.

Language-specific rules

A pronunciation or forced translation can apply to one language. Add pronunciation_language to a terms entry or target_language to a forced_translations entry:

{
  "terms": [
    { "term": "Acme", "pronunciation": "ack-mee" },
    { "term": "Acme", "pronunciation": "ak-may", "pronunciation_language": { "scope": "specific", "code": "fr" } }
  ],
  "forced_translations": [
    { "term": "Hello", "translation": "Bonjour", "target_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.
The same term can appear once per language in each list.
do_not_translate_terms always applies to all languages.

Responses include the language field only on language-specific rules, so all-languages entries keep their existing shape.

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 list replaces that kind of rule across every language, so send language-specific entries back with their language fields. A term repeated for the same language 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, 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. Retry shortly.

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.

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

Three lists

Create

Language-specific rules

Update

Read

Delete

Apply

Errors

Migrating from v1 brand voice

​Three lists

​Create

​Language-specific rules

​Update

​Read

​Delete

​Apply

​Errors

​Migrating from v1 brand voice

Three lists

Create

Language-specific rules

Update

Read

Delete

Apply

Errors

Migrating from v1 brand voice