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.
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:
- Returns a WebM file with a real alpha channel.
- Applies background removal for you, so
remove_backgroundis optional (passing it too is harmless). - Rejects any
backgroundvalue in the same request (you can’t both remove and set a background).
Step 1 — Create the video
Send aPOST to /v3/videos with type: "avatar", your avatar and voice, and output_format: "webm":
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
PollGET /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 themp4 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.
