Import a Brand Kit

Import a brand kit from a public website with POST /v3/brand-kits, then poll GET /v3/brand-kits/ until its colors, logos, and fonts are assembled.

Import 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 brand kit. A workspace that has never opened the HeyGen app can 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.

curl -X POST "https://api.heygen.com/v3/brand-kits" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "url": "https://www.acme.com", "name": "Acme Corp, Primary" }'

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 409 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.

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 then. A website import usually settles in under two minutes. Logos land first and fonts last, so a kit with colors and a logo may still be loading, and both the collections and the roles are provisional until then.

import time, requests

url = "https://api.heygen.com/v3/brand-kits/3f9a1c47b8e24d5fa0c61e8b7d24f6a1"
headers = {"X-Api-Key": HEYGEN_API_KEY}

while (kit := requests.get(url, headers=headers).json()["data"])["status"] == "loading":
    time.sleep(3)

status is error when the import stopped early. The kit keeps whatever was assembled and remains usable: check the collections to see what made it through, and fill the gaps in the app.

Read a kit robustly

Two habits keep a kit reader robust once someone edits 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. Read color_roles for roles and colors for the palette.
• A role can name an asset that is gone. 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.

Next, correct any roles the importer read differently than you would.