Manage a Glossary

Create, update, read, and delete a HeyGen brand glossary over the API, with full-list updates that preserve per-language rules and a field map from the v1 brand voice lists.

A workspace has one brand glossary. Create it once, then keep it current with updates. Workspaces that made several glossaries before this limit keep all of them, and each stays usable.

Create

POST /v3/brand-glossaries takes a name (1 to 64 characters) and any of the three lists. The 201 response is the full glossary, usable immediately. If the workspace already has a glossary, the request returns 409 conflict; find it with GET /v3/brand-glossaries and change it with an update.

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" }
    ]
  }'

Send an Idempotency-Key so a retry replays the first response instead of failing.

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})

Entries read back this way keep their IPA and language fields. Tone settings are managed in the HeyGen app under Brand Kit and stay as they are.

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 keep their audio and text. This cannot be undone.

Migrating from v1 brand voice

brand_voice_id is the 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 takes brand_glossary_id.

The lists of the legacy POST /v1/brand_voice/{brand_voice_id} map to the v3 glossary as follows (see the 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.