Brand Glossary

A brand glossary is a list of your terms and the pronunciation each one should get. Pass its brand_glossary_id when you create a video and every term in the list is respelled for the voice — so HeyGen is spoken hey-jen rather than hey-gen, and an acronym your team says as a word isn’t spelled out letter by letter. Glossaries can be authored in the HeyGen app under Brand Kit or created and edited over the API. Creating them over the API is what lets each of your own customers get their own vocabulary: mint a glossary per tenant, keep it in sync with their product catalog, and pass its ID on every render.

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

One glossary, two jobs

The same glossary record behaves differently depending on where you pass it, because the two pipelines need different things from it:

In generation — Studio, Templates, and single-scene avatar and image videos — it sets pronunciation. The term keeps its spelling in the script and in captions; only the audio changes.
In translation — it pins terminology. A term that a general translator would render literally stays your term instead, so Reformer arrives as the Pilates equipment rather than a political activist.

One list serves both, so a term you add for a Studio voiceover is also honored the next time you translate that video.

Create a glossary

POST /v3/brand-glossaries takes a name and an optional list of terms. Include the terms to populate the glossary in the same call, or omit them and fill the list in later.

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

import requests, uuid

resp = requests.post(
    "https://api.heygen.com/v3/brand-glossaries",
    headers={
        "X-Api-Key": HEYGEN_API_KEY,
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Acme Product Names",
        "terms": [
            {"term": "HeyGen", "pronunciation": "hey-jen"},
            {"term": "2024", "pronunciation": "twenty twenty-four"},
        ],
    },
)
brand_glossary_id = resp.json()["data"]["brand_glossary_id"]

const resp = await fetch("https://api.heygen.com/v3/brand-glossaries", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.HEYGEN_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: "Acme Product Names",
    terms: [
      { term: "HeyGen", pronunciation: "hey-jen" },
      { term: "2024", pronunciation: "twenty twenty-four" },
    ],
  }),
});
const { data } = await resp.json();

Parameter	Type	Required	Description
`name`	string	Yes	Display name. Surrounding whitespace is trimmed; the trimmed name must be 1–64 characters and unique within your workspace, compared without regard to case.
`terms`	array	No	Term-to-pronunciation mappings. Omit it, or pass an empty array, to create a glossary you populate later.
`terms[].term`	string	Yes	The term as written in a script. Matched case-insensitively.
`terms[].pronunciation`	string	Yes	The respelling handed to the voice in place of `term`, for example `hey-jen`.

Send an Idempotency-Key header so a retry is safe: a repeat within 24 hours replays the original response rather than creating a second glossary. 201 returns the full glossary, the same shape you read back later:

{
  "data": {
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
    "name": "Acme Product Names",
    "created_at": "2026-03-10T18:22:22",
    "updated_at": "2026-03-10T18:22:22",
    "terms": [
      { "term": "HeyGen", "pronunciation": "hey-jen" },
      { "term": "2024", "pronunciation": "twenty twenty-four" }
    ]
  }
}

The glossary is usable immediately — there is no build step to wait on. Pass brand_glossary_id on your next creation request and it takes effect on that render.

Choosing terms

A pronunciation is a respelling, not a phonetic alphabet: write the term the way you would coach a person to say it, in syllables the voice can read. Hyphens and spaces are how you break it up.

Brand and product names — HeyGen → hey-jen, HyperFrames → hyper frames.
Acronyms your team says as a word — an acronym spelled out letter by letter when you say it as a word is a glossary entry, and so is the reverse.
Numerals, years, and units — a written 2024 can be read several defensible ways, and a glossary is how you pick one.

Terms the voice already reads correctly need no entry; add a term when you have heard it come out wrong, and confirm the fix by rendering the same script with and without the glossary.

Update a glossary

PATCH /v3/brand-glossaries/{brand_glossary_id} edits an existing glossary. Each field is replaced independently:

A field you omit is left untouched.
A field you send replaces that value in full.
An empty terms array removes every term.

curl -X PATCH "https://api.heygen.com/v3/brand-glossaries/8c2d5e91a47b4f3c8d1e6a9b2f5c7d40" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Product Names (2026)"
  }'

The response is the same data object the create call returns, with updated_at moved forward. Send at least one of name or terms; an empty body is a 400 with "Provide at least one field to update."

Adding one term

terms is replace-in-full, so adding a single term means reading the glossary, appending to the list, and sending the whole list back. Read first every time rather than from a cached copy — a teammate editing the same glossary in the app is otherwise overwritten.

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

A glossary can also carry translation rules, which control how terms are handled when a video is translated. Those are managed in the HeyGen app under Brand Kit and are never modified by a PATCH here, so a glossary edited in the app keeps them through an update made over the API.

Find and inspect glossaries

GET /v3/brand-glossaries returns the glossaries in the authenticated workspace.

Parameter	Type	Default	Description
`limit`	integer	10	Results per page, 1–100.
`token`	string	—	Opaque cursor from a previous response’s `next_token`.

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

{
  "data": [
    {
      "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
      "name": "Acme Product Names",
      "created_at": "2026-03-10T18:22:22",
      "updated_at": "2026-06-19T17:34:52"
    }
  ],
  "has_more": false,
  "next_token": null
}

The list gives you names, IDs, and timestamps but not contents — updated_at is how you tell which of several similarly named glossaries your team still maintains. GET /v3/brand-glossaries/{brand_glossary_id} returns one glossary with its full term list. This is the endpoint to reach for when a generated video pronounces something unexpectedly — it tells you whether the term is in the list at all, and exactly what respelling it was given.

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

A glossary with "terms": [] is valid and applying it is accepted, but it changes nothing. An empty term list is the usual explanation for a glossary that appears to have no effect.

Apply a glossary

Pass brand_glossary_id at the top level of the creation request. It is global to 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": "studio",
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
    "scenes": [
      {
        "type": "avatar_video",
        "input": {
          "type": "avatar",
          "avatar_id": "YOUR_AVATAR_ID",
          "script": "HeyGen shipped this in 2024.",
          "voice_id": "YOUR_VOICE_ID"
        }
      }
    ]
  }'

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

curl -X POST "https://api.heygen.com/v3/video-translations" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/source.mp4" },
    "output_languages": ["Spanish (Spain)"],
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
  }'

curl -X POST "https://api.heygen.com/v3/templates/$TEMPLATE_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
    "variables": {}
  }'

See On Brand for the full list of endpoints that accept the field. On POST /v3/videos it applies to "type" of studio, avatar, or image, and in a translation batch or a video batch it is set per item.

What a glossary leaves alone

Captions and subtitles keep the original spelling. A term written HeyGen still reads HeyGen on screen and in the .srt sidecar while being spoken hey-jen. The respelling is for the voice, not the viewer.
Scenes with finished audio are untouched. A Studio scene that supplies audio_url or audio_asset_id already has its audio, so there is no synthesis step for the glossary to influence.

Errors

Status	Code	Meaning
`400`	`invalid_parameter`	A field is out of range — for example `"'name' must be between 1 and 64 characters."` The `param` field names the offending field.
`404`	`resource_not_found`	No glossary with that ID in the authenticated workspace.
`409`	`conflict`	`"A brand glossary with this name already exists."` Names are unique per workspace, compared without regard to case — list your glossaries to find the existing one.
`409`	`request_in_progress`	A request with this `Idempotency-Key` is still running. Retry shortly.
`429`	`rate_limit_exceeded`	Retry after the duration in the `Retry-After` header.

On a creation request, an unknown or inaccessible brand_glossary_id is rejected with 400 when the request is made, rather than failing partway through a render — so a bad ID produces no video and consumes no credits. Glossaries are workspace-scoped, so if an ID you can see in the app is rejected, check that the API key belongs to that same workspace.

`brand_voice_id` is the former name

brand_voice_id was the original name for this field and is deprecated. It is accepted on three endpoints — POST /v3/templates/{template_id}, POST /v3/video-translations, and POST /v3/video-translations/proofreads — where it resolves to the same workspace record, so existing requests keep working. It is not accepted on POST /v3/videos, on any composition type. That request rejects unknown fields outright, so brand_voice_id there is a 400 rather than a silently ignored field — use brand_glossary_id. This is the trap for anyone porting a working translation payload over to Studio. Prefer brand_glossary_id everywhere in new code. The old name is also misleading: a glossary never changes which voice speaks.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

One glossary, two jobs

Create a glossary

Choosing terms

Update a glossary

Adding one term

Find and inspect glossaries

Apply a glossary

What a glossary leaves alone

Errors

`brand_voice_id` is the former name

​One glossary, two jobs

​Create a glossary

​Choosing terms

​Update a glossary

​Adding one term

​Find and inspect glossaries

​Apply a glossary

​What a glossary leaves alone

​Errors

​brand_voice_id is the former name

One glossary, two jobs

Create a glossary

Choosing terms

Update a glossary

Adding one term

Find and inspect glossaries

Apply a glossary

What a glossary leaves alone

Errors

`brand_voice_id` is the former name