Skip to main content
To get an avatar video with a transparent background, request the WebM output format on POST /v3/videos. WebM carries an alpha channel; MP4 does not. This is the single most-missed setting — the default output is a standard MP4 with an opaque background, so if you don’t ask for WebM you will never get transparency.
Your avatar must support matting. Transparent output requires an avatar trained with matting (background separation) — the default for recently-created avatars, so most Digital Twins and Studio Avatars qualify. If an avatar doesn’t support it, the WebM request is rejected with the error “This video avatar does not support webm output. The avatar must be trained with matting enabled.” — if you hit it, use a more recently-created avatar.

Prerequisites

An avatar_id for a matting-trained avatar — matting is the default for recently-created avatars. Use GET /v3/avatars/looks to browse your looks and copy an id.
A voice_id for the voice you want. Use GET /v3/models/audio/voices to browse voices. (You can omit voice_id when using an avatar_id — the avatar’s default voice is used.)

The one required switch: output_format

output_format takes mp4 (the default, opaque) or webm. Selecting output_format: "webm" does three things automatically:
  1. Returns a WebM file with a real alpha channel.
  2. Applies background removal for you, so remove_background is optional (passing it too is harmless).
  3. Rejects any background value in the same request (you can’t both remove and set a background).

Step 1 — Create the video

Send a POST to /v3/videos with type: "avatar", your avatar and voice, and output_format: "webm":
The create response echoes data.output_format. If it comes back as mp4, the request did not select WebM: recheck the field name and value.

Step 2 — Poll for completion

Poll GET /v3/videos/{video_id} until status is completed. data.video_url is then a presigned download link to your transparent .webm file.

Why MP4 can’t be transparent

MP4 (H.264/H.265) has no alpha channel, so a request left at the mp4 default is opaque even with remove_background: true. If you need a different alpha-capable container (for example MOV/ProRes 4444 for a video editor), render the WebM and transcode it locally. Renaming an MP4 to .webm adds no transparency.

Engines

output_format is a top-level field, independent of the engine, so transparency works the same on Avatar 6 ("engine": {"type": "heygen-avatar-6"}), Avatar IV (the default), Avatar V (avatar_v), and Avatar III (avatar_iii), with digital twin, studio avatar, and photo avatar looks alike. Cinematic Avatar (type: "cinematic_avatar") renders MP4 and has no output_format field.