How to Create a Transparent HeyGen WebM Avatar With Codex

Codex can create a transparent HeyGen WebM avatar by discovering the current HeyGen WebM video Action in Aident Loadout, selecting a compatible studio avatar pose, supplying either text and a voice or an uploaded audio asset, and preflighting the request before generation. The output is a WebM video with an alpha channel, so the presenter can sit over a product demo, slide, website, or another video without a rectangular background.

Use this workflow when transparency is part of the final composition. If you need a normal full-frame presenter video, MP4 is usually simpler and more widely supported.

Why Transparent Video Needs WebM

An ordinary MP4 does not carry the alpha channel needed for a transparent background. HeyGen's current transparent-video path returns WebM instead. When a compatible player or editor composites that file over another visual, only the avatar remains visible.

That makes WebM useful for:

• a presenter over a screen recording or product tour;

• a guide layered into a help center or onboarding page;

• a speaker in the corner of a slide or training video;

• a reusable avatar clip that several editors can place over different backgrounds.

Transparency does not make the clip universally compatible. Confirm that your website, video editor, rendering library, and delivery pipeline preserve WebM alpha before paying to generate a production asset.

What You Need

Prepare these inputs before asking Codex to create anything:

• a HeyGen studio avatar pose that supports WebM output;

• either a short script plus a HeyGen voice ID, or an uploaded audio asset ID;

• the intended width and height, such as 1280 by 720;

• an avatar style, normally the default unless the current schema documents another supported value;

• a description of where the transparent clip will be composited.

The Aident Action inspected on August 10, 2026 does not support custom avatars for this WebM endpoint. It requires a compatible HeyGen studio avatar pose. HeyGen's broader API now documents WebM output for avatars with matting support, but the discovered Aident Action is the contract Codex must follow for this workflow.

Do not paste a HeyGen API key into chat. Aident Loadout uses the connected HeyGen integration and lets Codex validate the request without exposing provider credentials.

Set Up Aident Loadout in Codex

Start with the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then ask Codex to check account authentication and Vault status, search the staging capability catalog for the public HeyGen Action that creates transparent WebM avatar videos, and inspect its live schema. Do not copy an internal capability identifier from an article or old run. Discovery keeps the workflow tied to the version available to your account.

The inspected Action exposed these inputs:

The successful response contains a video ID, not necessarily a finished downloadable file. Keep that ID for status checks.

Choose a Compatible Avatar and Voice

Ask Codex to discover the read-only HeyGen Actions for listing avatars and voices. Inspect their schemas before execution, then return a short set of candidates instead of dumping the whole catalog.

Use a bounded prompt:

Check Aident Loadout authentication and Vault status.
Discover and inspect the current read-only HeyGen avatar and voice listing Actions.
Return five public studio avatar poses that support transparent WebM output and
five English voices suitable for a concise product tour. Include names and IDs.
Do not create, update, delete, or publish anything

Do not assume every avatar can be rendered with a transparent background. If the listing result does not establish WebM or matting support, stop and verify the pose against HeyGen's current documentation before generation.

For a script, read it aloud before submission. Remove unsupported markup, stage directions, private customer data, and accidental instructions that should not be spoken. For recorded audio, upload only material you have permission to use and keep the returned asset ID with the job record.

Preflight the Exact WebM Request

Preflight validates the fields and returns the Aident credit quote without sending the generation request to HeyGen. The sample below validated at exactly 50 Loadout credits on August 10, 2026. Treat that as a dated observation because pricing and schemas can change.

Find and inspect the current public HeyGen Action for a transparent WebM avatar.
Preflight this request without executing it:

- avatar pose: <reviewed studio avatar pose ID>
- input text: Welcome to the product tour. I will show you the three key steps.
- voice: <reviewed voice ID>

Stop if the quote is unavailable, the pose is rejected, the input requires an unexpected credential, or the schema no longer matches the plan. A failed preflight is useful evidence. It is not permission to call HeyGen directly or guess a replacement field.

Generate Exactly Once

After reviewing the script, avatar rights, voice, dimensions, and quote, approve one execution:

Execute the exact preflighted HeyGen WebM request once.
Do not change any input and do not retry if the response is slow or ambiguous.
Record the returned video ID, provider status, and execution time.
Do not publish or distribute the output

The no-retry rule matters because a client timeout can occur after HeyGen accepts the paid job. Submitting again may create a duplicate video and a second charge. If the response is ambiguous, inspect the Action audit and provider job state before making another write.

Poll the Matching Video Status

Ask Codex to discover the read-only HeyGen status Action and use the returned video ID:

Discover and inspect the current read-only HeyGen video status Action.
Poll the recorded video ID at moderate intervals for up to 30 minutes.
Stop on a completed or failed state. On success, return the WebM download URL,
dimensions, and available expiry information. On failure, return the provider
message and do not create another 

Save the completed file to approved durable storage before a temporary delivery URL expires. Store the original video ID, inputs, quote, and source rights with the asset so the result can be reproduced or audited.

Verify the Alpha Channel Before Compositing

A filename ending in .webm does not by itself prove that transparency survived every step. Test the downloaded file over two contrasting backgrounds, one light and one dark.

Confirm all of these behaviors:

1. no solid rectangle appears around the avatar;

2. hair, hands, clothing, and moving edges remain clean on both backgrounds;

3. the player or editor does not replace transparency with black;

4. audio starts in sync and remains synchronized through the final frame;

5. the pixel dimensions match the preflighted request;

6. the clip can be rendered through the final production pipeline without losing alpha.

For a browser embed, test the exact browsers and devices your audience uses. For an editor or code-based renderer, export a short sample before building the entire composition.

Common Failures

The Avatar Pose Is Rejected

The pose may not support WebM or matting. Return to the read-only avatar listing, choose a confirmed compatible studio pose, and preflight again. Do not turn a compatibility error into a custom-avatar experiment on an Action that explicitly excludes custom avatars.

Text Is Present but the Voice Is Missing

The inspected contract requires a voice ID when input_text is used. Select a current voice and repeat preflight. If you want to keep recorded delivery, upload audio through the current HeyGen asset workflow and use its asset ID instead of text.

The Result Has a Black Background

First test the WebM in a player known to support alpha. If transparency works there, the later player, editor, conversion, or CDN step is flattening it. Do not convert to MP4 and expect the alpha channel to remain.

The Job Stays in Processing

Keep the video ID and continue bounded status checks. A render delay is not evidence that the create call failed. Check provider status, then resume polling later rather than issuing an automatic duplicate.

The Composition Looks Too Small or Soft

Generate at the dimensions needed by the final placement, not by the source avatar preview. Avoid enlarging a small completed WebM after the fact. Requote and approve a new render only after confirming that the final canvas truly needs a larger source.

When to Use a Different Workflow

Use this transparent WebM path when an avatar must be composited over other content. Use the HeyGen translation workflow when the source video already exists and only its spoken language must change. Use the HeyGen, HyperFrames, and API comparison when you are still choosing the production method. Use Claude Code with HyperFrames when the main work is timing, typography, animation, or a code-driven layout.

The measurable success condition is one quoted and approved generation, one retained video ID, one completed WebM, a verified alpha channel over light and dark backgrounds, and no duplicate paid job.

Set up Aident Loadout and create one reviewed WebM avatar.

Sources

• HeyGen: Transparent Background Videos

• HeyGen: Create Video

• HeyGen: Create a WebM Video

• HeyGen: Create WebM Avatar Videos

Refresh this guide when the Aident HeyGen WebM Action schema or quote changes, HeyGen changes avatar matting requirements, or the supported WebM inputs and status contract change.