> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transparent Background Videos

> Generate avatar videos with a transparent background (alpha channel) using the HeyGen API. Set output_format to webm to get a compositing-ready video with no background.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

To get an avatar video with a transparent background, request the **WebM** output format on [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video). 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.

> [!WARNING]
>
> **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

> [!TIP]
>
> 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`.

> [!TIP]
>
> 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"`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_LOOK_ID",
    "engine": { "type": "heygen-avatar-6" },
    "script": "Hi! This video has a transparent background, ready to drop onto any scene.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "Transparent Background Demo",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "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}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) 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](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md) (`"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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.