> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Brand Glossary

> Creates a brand glossary. Pass the returned `brand_glossary_id` when creating a video or translation to apply it. `name` must be unique in the workspace, ignoring case; a duplicate returns 409. Term lists are optional and can be added later with PATCH. `pronunciation_language` and `target_language` accept scope 'all' or scope 'specific' with a base language code such as 'fr'; omission means all languages and null is invalid. Duplicate term/rule-type/language combinations return 409; distinct languages for the same term are allowed. The response includes language fields for specific-language rules. Temporary access-evaluation failures return 503; retry the request.



## OpenAPI

````yaml /openapi/external-api.json post /v3/brand-glossaries
openapi: 3.1.0
info:
  title: HeyGen External API
  version: 1.0.0
  description: >-
    HeyGen's external API for programmatic AI video creation. See
    https://docs.heygen.com for full documentation.
  contact:
    name: HeyGen Product Infra
    url: https://heygen.com
servers:
  - url: https://api.heygen.com
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Video
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Feedback
    description: Tell HeyGen how a generated result turned out
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/brand-glossaries:
    post:
      tags:
        - Brand
      summary: Create Brand Glossary
      description: >-
        Creates a brand glossary. Pass the returned `brand_glossary_id` when
        creating a video or translation to apply it. `name` must be unique in
        the workspace, ignoring case; a duplicate returns 409. Term lists are
        optional and can be added later with PATCH. `pronunciation_language` and
        `target_language` accept scope 'all' or scope 'specific' with a base
        language code such as 'fr'; omission means all languages and null is
        invalid. Duplicate term/rule-type/language combinations return 409;
        distinct languages for the same term are allowed. The response includes
        language fields for specific-language rules. Temporary access-evaluation
        failures return 503; retry the request.
      operationId: createBrandGlossary
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandGlossaryRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BrandGlossaryDetail'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: '''name'' must be between 1 and 64 characters.'
                  param: name
                  doc_url: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '403':
          description: >-
            Forbidden — `error.code` is one of: `resource_access_denied`,
            `insufficient_api_key_scope`, `ai_vendor_access_restricted`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                glossary_edit_restricted:
                  value:
                    error:
                      code: resource_access_denied
                      message: >-
                        Glossary editing is restricted by your workspace
                        settings.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#resource-access-denied
                insufficient_api_key_scope:
                  value:
                    error:
                      code: insufficient_api_key_scope
                      message: >-
                        This API key does not have permission to perform this
                        action. Required scope: brand:write.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#insufficient-api-key-scope
                ai_vendor_access_restricted:
                  value:
                    error:
                      code: ai_vendor_access_restricted
                      message: >-
                        Workspace AI vendor policy blocks google for this
                        request.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#ai-vendor-access-restricted
        '409':
          description: >-
            Conflict — either the request conflicts with existing state, or a
            prior request with this `Idempotency-Key` is still in progress
            (`request_in_progress`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                conflict:
                  summary: Resource conflict
                  value:
                    error:
                      code: conflict
                      message: A brand glossary with this name already exists.
                      param: null
                      doc_url: null
                request_in_progress:
                  summary: Concurrent retry with same Idempotency-Key
                  value:
                    error:
                      code: request_in_progress
                      message: >-
                        A request with this Idempotency-Key is already in
                        progress. Retry shortly.
                      param: null
                      doc_url: null
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Retry after the duration specified in the
                    Retry-After header.
                  param: null
                  doc_url: null
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
        '503':
          description: >-
            Temporarily unavailable — the request did not complete and is safe
            to retry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Brand glossary access is temporarily unavailable. Please
                    retry the request.
                  param: null
                  doc_url: null
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional client-supplied key for safely retrying mutations. Subsequent
        calls within 24 hours that share this key replay the original response —
        even if the request body differs slightly (a warning is logged). A retry
        that arrives while the original is still in flight gets a 409
        `request_in_progress`. Keys must be 1–255 characters from
        `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and
        per-resource: the same key on a different route or path parameter is
        independent.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_\-:.]{1,255}$
        maxLength: 255
        minLength: 1
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    CreateBrandGlossaryRequest:
      additionalProperties: false
      description: Request body for POST /v3/brand-glossaries.
      properties:
        name:
          description: >-
            Display name for the glossary. Surrounding whitespace is removed,
            and the trimmed name must be 1-64 characters and unique within your
            workspace, compared without regard to case.
          maxLength: 64
          minLength: 1
          title: Name
          type: string
        terms:
          default: []
          description: >-
            Term-to-pronunciation mappings. Omit it, or pass an empty array, to
            create a glossary you fill in later.
          items:
            $ref: '#/components/schemas/BrandGlossaryTermWrite'
          title: Terms
          type: array
        do_not_translate_terms:
          default: []
          description: >-
            Terms to keep untranslated when this glossary is used by a
            translation feature. Omit it, or pass an empty array, to add none.
          items:
            $ref: '#/components/schemas/DoNotTranslateEntryWrite'
          title: Do Not Translate Terms
          type: array
        forced_translations:
          default: []
          description: >-
            Force Translate rules: terms translated into an exact replacement
            when this glossary is used by a translation feature. Omit it, or
            pass an empty array, to add none. If a term also appears in
            `do_not_translate_terms`, Don't Translate takes precedence without
            deleting its Force Translate rules.
          items:
            $ref: '#/components/schemas/ForcedTranslationEntryWrite'
          title: Forced Translations
          type: array
      required:
        - name
      title: CreateBrandGlossaryRequest
      type: object
      x-mcp-exclude-unset: true
      x-mcp-omit-invalid-nulls: true
    BrandGlossaryDetail:
      description: >-
        A single brand glossary with its full term list (GET
        /v3/brand-glossaries/{id}).
      properties:
        brand_glossary_id:
          description: >-
            Unique brand glossary ID. Pass it as `brand_glossary_id` when
            creating a video or translation to apply this glossary.
          title: Brand Glossary Id
          type: string
        name:
          description: Display name of the brand glossary.
          title: Name
          type: string
        created_at:
          description: Creation timestamp (UTC).
          format: date-time
          title: Created At
          type: string
        updated_at:
          description: Last update timestamp (UTC).
          format: date-time
          title: Updated At
          type: string
        terms:
          description: >-
            Every term mapping in this glossary. Empty when the glossary has no
            terms yet, in which case applying it has no effect.
          items:
            $ref: '#/components/schemas/BrandGlossaryTerm'
          title: Terms
          type: array
        do_not_translate_terms:
          default: null
          description: Don't Translate rules in this glossary. Omitted when it has none.
          items:
            $ref: '#/components/schemas/DoNotTranslateEntry'
          title: Do Not Translate Terms
          type: array
        forced_translations:
          default: null
          description: >-
            Force Translate rules in this glossary. Omitted when it has none. If
            a term also appears in `do_not_translate_terms`, Don't Translate
            takes precedence without deleting its Force Translate rules.
          items:
            $ref: '#/components/schemas/ForcedTranslationEntry'
          title: Forced Translations
          type: array
      required:
        - brand_glossary_id
        - name
        - created_at
        - updated_at
        - terms
      title: BrandGlossaryDetail
      type: object
      x-mcp-exclude-unset: true
    StandardAPIError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message
          example: Video not found
        param:
          type:
            - string
            - 'null'
          description: Which request field caused the error
        doc_url:
          type:
            - string
            - 'null'
          description: Link to error documentation
        errors:
          type: array
          description: >-
            Per-item error details for batch/multi-node failures (e.g. graph
            compilation errors by node).
          items:
            $ref: '#/components/schemas/StandardAPIErrorDetail'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    BrandGlossaryTermWrite:
      additionalProperties: false
      anyOf:
        - required:
            - pronunciation
        - properties:
            ipa:
              type: string
          required:
            - ipa
      description: >-
        One glossary entry as accepted on POST / PATCH: a written term and how
        it should be spoken.
      properties:
        term:
          description: >-
            The term as written in a script, matched case-insensitively.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
        pronunciation:
          description: >-
            Respelling handed to the speech synthesizer in place of `term` (for
            example 'hey-jen' for 'HeyGen'). Affects generated audio only —
            captions and subtitles keep the original `term` spelling.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty. May be omitted when IPA is supplied and glossary IPA
            access is enabled; a Respelling fallback is generated before saving.
            Conversion failure leaves the glossary unchanged. Null is not
            accepted.
          minLength: 1
          title: Pronunciation
          type: string
        pronunciation_language:
          default: null
          description: >-
            Language in which this pronunciation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Pronunciation Language
        ipa:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            IPA pronunciation, for example '/ˈæk.mi/'. Requires glossary IPA
            access. Supply pronunciation, IPA, or both. Null clears IPA when
            pronunciation is provided. Omission preserves saved IPA only when
            Respelling and language are unchanged. New or changed pronunciations
            prefer IPA on supported engines, with Respelling as the fallback.
            Unchanged pronunciations retain their saved internal preference.
          title: Ipa
      required:
        - term
      title: BrandGlossaryTermWrite
      type: object
      x-mcp-omit-invalid-nulls: true
    DoNotTranslateEntryWrite:
      additionalProperties: false
      description: One Don't Translate rule as accepted on POST / PATCH bodies.
      properties:
        term:
          description: >-
            A term to keep untranslated. When this glossary is used by a
            translation feature, each occurrence of the term — matched
            case-insensitively — is kept untranslated in every target language.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
      required:
        - term
      title: DoNotTranslateEntryWrite
      type: object
    ForcedTranslationEntryWrite:
      additionalProperties: false
      description: One Force Translate rule as accepted on POST / PATCH bodies.
      properties:
        term:
          description: >-
            The term to replace, matched in the source text case-insensitively.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
        translation:
          description: >-
            The exact text used in place of `term` in the translated output for
            the selected target language scope. Inserted verbatim: grammatical
            inflection (case, gender, number) is not adapted to the surrounding
            sentence. Surrounding whitespace is removed and the trimmed value
            must be non-empty.
          minLength: 1
          title: Translation
          type: string
        target_language:
          default: null
          description: >-
            Target language in which this translation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Target Language
      required:
        - term
        - translation
      title: ForcedTranslationEntryWrite
      type: object
      x-mcp-omit-invalid-nulls: true
    BrandGlossaryTerm:
      description: 'One glossary entry: a written term and how it should be spoken.'
      properties:
        term:
          description: The term as written in a script, matched case-insensitively.
          title: Term
          type: string
        pronunciation:
          description: >-
            Respelling handed to the speech synthesizer in place of `term` (for
            example 'hey-jen' for 'HeyGen'). Affects generated audio only —
            captions and subtitles keep the original `term` spelling.
          title: Pronunciation
          type: string
        pronunciation_language:
          default: null
          description: >-
            Language in which this pronunciation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Pronunciation Language
        ipa:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Stored IPA pronunciation. Returned only when glossary IPA access is
            enabled.
          title: Ipa
      required:
        - term
        - pronunciation
      title: BrandGlossaryTerm
      type: object
    DoNotTranslateEntry:
      description: >-
        One Don't Translate rule: a term kept untranslated when content is
        translated.
      properties:
        term:
          description: >-
            A term to keep untranslated. When this glossary is used by a
            translation feature, each occurrence of the term — matched
            case-insensitively — is kept untranslated in every target language.
          title: Term
          type: string
      required:
        - term
      title: DoNotTranslateEntry
      type: object
    ForcedTranslationEntry:
      description: >-
        One Force Translate rule: a term and the exact translation that replaces
        it.
      properties:
        term:
          description: The term to replace, matched in the source text case-insensitively.
          title: Term
          type: string
        translation:
          description: >-
            The exact text used in place of `term` in the translated output for
            the selected target language scope. Inserted verbatim: grammatical
            inflection (case, gender, number) is not adapted to the surrounding
            sentence.
          title: Translation
          type: string
        target_language:
          default: null
          description: >-
            Target language in which this translation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Target Language
      required:
        - term
        - translation
      title: ForcedTranslationEntry
      type: object
    StandardAPIErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: unknown_node_type
        message:
          type: string
          description: Human-readable error message
          example: Unknown node type
        node_id:
          type: string
          description: Graph node id this error pertains to, if applicable
        port:
          type: string
          description: Port name on the node this error pertains to, if applicable
        path:
          type: string
          description: Field path within the item this error pertains to, if applicable
      required:
        - code
        - message
    AllBrandGlossaryLanguages:
      additionalProperties: false
      description: Apply the rule in every language.
      properties:
        scope:
          const: all
          description: Apply this rule in every language.
          title: Scope
          type: string
      required:
        - scope
      title: AllBrandGlossaryLanguages
      type: object
    SpecificBrandGlossaryLanguage:
      additionalProperties: false
      description: Apply the rule in one language.
      properties:
        scope:
          const: specific
          description: Apply this rule only in the specified language.
          title: Scope
          type: string
        code:
          description: >-
            Language code, such as 'en' or 'fr'. Locale codes such as 'en-US'
            are not accepted.
          maxLength: 32
          title: Code
          type: string
      required:
        - scope
        - code
      title: SpecificBrandGlossaryLanguage
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: HeyGen API key. Obtain from your HeyGen dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.