Skip to main content
A brand kit is a saved set of brand colors, fonts, and logos. Pass its brand_kit_id to the Video Agent and the agent applies it to everything it builds — scene backgrounds, text treatments, chart palettes, logo placement — so output ships on-brand without describing your brand in the prompt. Author a kit in the HeyGen app under Brand Kit, or import one from a public website over the API. Either way you get a brand_kit_id, and a kit created over the API stays editable in the app. A brand kit governs how a video looks. To control how your terms are spoken, pair it with a brand glossary — see On Brand.
API reference: Create Brand Kit · Get Brand Kit · List Brand Kits · Update Brand Kit · Delete Brand Kit · Create Session · Send Message

​
Import a kit from a website

POST /v3/brand-kits visits a public URL, imports the logos, colors, and font files it finds, and assembles them into a kit. This is the path to on-brand output for a workspace that has never opened the HeyGen app — onboard a customer by their own domain and generate their first branded video in the same run.
By calling this endpoint you confirm you have the rights and licenses necessary to upload, store, and use the imported assets in HeyGen.
201 returns { "brand_kit_id": "…", "status": "loading" } as soon as the record exists, before any asset has been imported. The ID is usable immediately, including on a Video Agent request. Send an Idempotency-Key so a retry is free: a repeat within 24 hours replays the original response instead of importing the same site twice. A retry that arrives while the first is still in flight gets a 409 with request_in_progress. The key is matched on its own rather than against the body, so reusing one with a different url replays the first kit instead of importing the new site.

​
Read a kit and wait for the import

GET /v3/brand-kits/{brand_kit_id} returns the kit’s colors, logos, and fonts alongside the color_roles, logo_roles, and font_roles that say which of them plays which part. Poll every 2 to 5 seconds until status is completed, and read the palette only then. A website import usually settles in under two minutes; fonts are typically last to land, so a kit that already has colors and a logo may still be loading. Both the collections and the roles are provisional until then. Two habits keep a kit reader robust once a human starts editing the kit in the app:
  • A role can name a color outside colors. The palette lists the brand’s core swatches; a role such as tertiary may point at a supporting surface color that isn’t one of them. Read color_roles for roles and colors for the palette rather than deriving one from the other.
  • A role can name an asset that no longer exists. Deleting a logo or font leaves the role that referenced it in place, so look the logo_id or font_id up in logos or fonts and handle the miss.
status is error when the import failed. The kit still exists and keeps whatever was assembled first, so it remains usable — check the collections to see what made it through, and fill the gaps in the app.

​
List your brand kits

GET /v3/brand-kits returns the kits in the authenticated workspace — the endpoint to reach for when you need the ID of a kit somebody else created in the app. Page with limit and token; the response carries data, has_more, and next_token at the top level. The listing is a summary: it carries logo_url for the primary logo and the color list, but not fonts or role assignments. Read a kit by ID for those. logo_url is null when a kit defines colors and fonts but no logo, which is common.

​
Correct a kit’s roles

Creation assigns roles automatically, with no human in the loop, so PATCH /v3/brand-kits/{brand_kit_id} is how a caller fixes a slot the importer read differently than you would. It sets the kit’s name and its role assignments — color_roles (primary, secondary, tertiary, accent), logo_roles (primary), and font_roles (title_text and body_text, each with a font_id and weight). The colors, logos, and font files themselves are curated in the HeyGen app.
An omitted field is left unchanged, so send only what you are changing. A role object you do send is replaced in full rather than merged — a role left out of it is cleared, which is why the example above clears tertiary and accent — and {} clears a group outright and stays cleared.
Clearing is {}, never null — a null on any field is rejected. Generated clients serialize with exclude_none and drop a null before it reaches the wire, so honoring it would clear the role over raw HTTP and silently do nothing through an SDK.
Role edits need an assembled kit and return 409 while status is loading or error. Renaming is allowed at any time, so a kit can be titled the moment its import starts.

​
Delete a kit

DELETE /v3/brand-kits/{brand_kit_id} removes a kit along with the colors, logos, and fonts it holds, and cannot be undone — the API has no way to restore one. A kit that is still assembling can be deleted at any time. Videos already generated with the kit keep their branding, since the colors were applied at render time. A Video Agent session still configured with the deleted brand_kit_id reports it as invalid on its next use.

​
Apply a brand kit to a video

Pass brand_kit_id when you create the session. It works in both generate and chat modes.
In an interactive session, brand_kit_id is also accepted on each follow-up message, so you can re-brand without starting over — useful when producing the same video for several brands or sub-brands. brand_kit_id and style_id are independent and compose: a style picks the look, the brand kit makes that look yours.

​
Errors

An unknown or inaccessible brand_kit_id on a Video Agent request is rejected with 400 invalid_parameter when the request is made, rather than failing partway through the render — so a bad ID costs you nothing. Brand kits are workspace-scoped: if you get this with an ID that exists, confirm the API key belongs to the workspace that owns the kit.