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 are authored in the HeyGen web app under Brand Kit. Over the API they are read-only: list them, read their terms, and reference them by ID.

API reference: List Brand Glossaries · Get Brand Glossary

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.

List your glossaries

Full schema: GET /v3/brand-glossaries. Returns the glossaries in the authenticated workspace.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	10	Results per page.
`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
}

Field	Type	Description
`brand_glossary_id`	string	Unique identifier. This is the value you pass when creating a video or translation.
`name`	string	Display name. Glossaries created without a name come back as an empty string.
`created_at`	string	Creation timestamp (UTC).
`updated_at`	string	Last update timestamp (UTC). Use this to tell which of several glossaries is the one your team still maintains.

The list gives you names and IDs but not contents — to see what a glossary actually changes, read it by ID.

Read a glossary’s terms

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"

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

Field	Type	Description
`terms`	array	Every mapping in the glossary.
`terms[].term`	string	The term as written in a script. Matched case-insensitively.
`terms[].pronunciation`	string	The respelling handed to the voice in place of `term`.

Terms are not limited to brand names. Numerals, years, and units are common entries, since a written 2024 can be read several defensible ways and a glossary is how you pick one.

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

Reading a glossary that does not exist in the workspace returns 404 with the resource_not_found code:

{
  "error": {
    "code": "resource_not_found",
    "message": "Brand glossary not found.",
    "param": null,
    "doc_url": null
  }
}

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

List your glossaries

Query parameters

Read a glossary’s terms

Apply a glossary

What a glossary leaves alone

Errors

`brand_voice_id` is the former name

​One glossary, two jobs

​List your glossaries

​Query parameters

​Read a glossary’s terms

​Apply a glossary

​What a glossary leaves alone

​Errors

​brand_voice_id is the former name

One glossary, two jobs

List your glossaries

Query parameters

Read a glossary’s terms

Apply a glossary

What a glossary leaves alone

Errors

`brand_voice_id` is the former name