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

# HeyGen Studio

> Compose avatar clips, images, and video footage into a single rendered video with one API call — HeyGen handles layout, timing, and the final export.

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

## Overview

A **studio video** is a single video composed from an ordered list of whole-frame scenes — avatar clips, still images, and existing video footage — concatenated in the order you send them. You describe the scenes; HeyGen owns the layout, derives each scene's duration, center-crops every scene to one global output canvas, and returns a single `video_id` for the finished MP4.

Create one by passing `"type": "studio"` to [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) — the same endpoint that renders `avatar`, `image`, and `cinematic_avatar` videos:

```json theme={null}
{
  "type": "studio",
  "scenes": [ ... ]
}
```

Each scene is one of three types:

| Scene `type` | What it renders | Duration comes from |
| - | - | - |
| [`avatar_video`](#avatar-video-scenes) | An avatar or animated image speaking a script or audio track | The audio |
| [`image`](#image-scenes) | A still image, silent or narrated | `duration` (silent) or the audio (narrated) |
| [`video`](#video-scenes) | An existing video clip, silent or narrated | The clip itself (silent) or the voiceover (narrated) |

Rendering is all-or-nothing: one request produces one video, and every scene renders or none do. Output settings — aspect ratio, resolution, captions — are global, set once per request.

Each scene renders up to **30 minutes**. When a scene's duration comes from an audio track longer than that, split the audio and send it as consecutive scenes — see [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#output-video-specifications).

> [!NOTE]
>
> Studio videos define their scenes **in the request**, which is ideal for programmatic composition. To render a reusable layout you've designed visually in HeyGen Studio, use a [HeyGen Studio Template](https://heygen-1fa696a7.mintlify.site/templates.md) instead.

## Quick Example

A three-scene video: a title card held for three seconds, an avatar delivering the message, and an existing clip as the outro.

```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": "studio",
    "title": "Product update — July",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "scenes": [
      {
        "type": "image",
        "source": { "type": "url", "url": "https://example.com/title-card.png" },
        "duration": 3
      },
      {
        "type": "avatar_video",
        "input": {
          "type": "avatar",
          "avatar_id": "YOUR_AVATAR_ID",
          "script": "Here is everything we shipped this month.",
          "voice_id": "YOUR_VOICE_ID",
          "background": { "type": "color", "color": "#0b1220" }
        }
      },
      {
        "type": "video",
        "source": { "type": "url", "url": "https://example.com/outro.mp4" },
        "playback": { "volume": 0.6 }
      }
    ]
  }'
```

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed`, then read the download URL — or pass a `callback_url` to receive a [webhook](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md) when the video is ready.

## Request Body

The full schema is in the [Create Video reference](https://heygen-1fa696a7.mintlify.site/reference/create-video.md). `scenes` takes `1`–`50` [scene types](#scene-types). Output settings are global: `aspect_ratio` (default `16:9`, see [Scene framing](#scene-framing)), `resolution` (`720p` or `1080p`), [`caption`](#captions), and [`brand_glossary_id`](#brand-glossary), alongside `title`, `callback_url`, and `callback_id`. A custom `watermark` image overlay (PNG or JPEG) is a premium option for select Enterprise customers: contact support to request access. The output container is MP4.

### Scene framing

A scene keeps its own shape inside the canvas rather than being cropped to fill it: where the two differ, the scene is scaled to fit and the remainder is padded. On a `1:1` canvas at `1080p`, an `avatar_video` scene from a 16:9 avatar renders as 1080x612 with padding above and below, and an `image` scene renders as a 608x1080 column with padding to either side.

Match `aspect_ratio` to the shape your scenes already are when you want an edge-to-edge frame.

## Scene Types

Every scene fills the whole frame and carries a `type` discriminator that determines its remaining fields.

### Avatar Video Scenes

`"type": "avatar_video"` renders a speaking scene. Its `input` object has `"type": "avatar"` and references an avatar you already have by `avatar_id`. The scene's duration is derived from the audio.

Mirrors the standalone [avatar creation mode](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md), minus the output settings, which are global on the studio request. Any avatar look works, exactly as in the standalone mode: **video avatars, studio avatars, and photo avatars**. To use a photo avatar (a "talking photo"), pass its look id as `avatar_id`. The [Quick Example](#quick-example) shows a complete scene.

Provide exactly one audio source: `script` (with `voice_id`, or omit `voice_id` to use the avatar's default voice), `audio_url`, or `audio_asset_id` from [Assets](https://heygen-1fa696a7.mintlify.site/assets.md). The input also takes `voice_settings` (including `volume`, `0.0`–`1.0`), [`engine`](#choosing-an-engine), `motion_prompt`, `expressiveness`, [`background`](#scene-backgrounds), and `remove_background`.

> [!NOTE]
>
> To lip-sync your own photo, register it as a photo avatar first via the [photo-avatar API](https://heygen-1fa696a7.mintlify.site/photo-avatar.md), then use its look id as `avatar_id` here. A studio scene references existing avatars; it does not animate a raw image inline.

#### Choosing an engine

The `avatar` input accepts an optional `engine` object, defaulting to [Avatar IV](https://heygen-1fa696a7.mintlify.site/avatar-iv.md) when omitted. Pass `{ "type": "avatar_v" }` for cross-reference-driven animation on [Avatar V](https://heygen-1fa696a7.mintlify.site/avatar-v.md) — check `supported_api_engines` on the avatar look to confirm eligibility. On Avatar V you may also set `engine.reference_look_id` to a `digital_twin` look in the same avatar group to pin the animation reference; when omitted, video avatars self-reference and photo avatars pick an eligible look from the group. `expressiveness` applies on Avatar IV; `motion_prompt` applies to photo avatars on either engine and to video avatars on Avatar V.

> [!NOTE]
>
> Avatar V uses a reference look from the avatar's group. If a photo avatar's group has none, Avatar V renders directly from the photo, and a `motion_prompt` is rejected with a `400`. A non-public `digital_twin` reference must also clear its group's consent requirements, whether you supplied it or it was selected for you. To see what a group already has, use [`GET /v3/avatars/looks?group_id=...&avatar_type=digital_twin`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks); the group id is the `group_id` field on any look in that group. Filtering by `avatar_type` alone searches your whole workspace and can return a digital twin from a different group, which is rejected. The listing shows candidates, and a non-public group needs [consent](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md). A look with `status: processing` (still training) can still be used as a reference.

#### Scene backgrounds

`background` sets what appears behind the avatar in an `avatar_video` scene. Pass one of:

| `type` | Shape | Behavior |
| - | - | - |
| `color` | `{ "type": "color", "color": "#RRGGBB" }` | Solid color. |
| `image` | `{ "type": "image", "source": { ... } }` | Image scaled to cover the frame. |
| `video` | `{ "type": "video", "source": { ... } }` | Clip scaled to cover the frame, muted, and looped for the whole scene. |

`source` takes the same [asset input](#asset-input) as image and video scenes: a public URL or an uploaded `asset_id`.

Most avatars have their own backdrop in the footage or photo, and it fills the frame, so an image or video background stays hidden behind it. Set `remove_background: true` on the same input to cut the avatar out and show your background.

> [!NOTE]
>
> `remove_background` on a video avatar needs a look trained with matting, the default for recently created digital twins. Otherwise the request fails with a `400`: *"This video avatar does not support background removal. The avatar must have native alpha or be trained with matting enabled."* Photo avatars are supported.

### Image Scenes

`"type": "image"` shows a still image in one of two modes — choose exactly one:

* **Silent** — set `duration` (seconds) and no audio source. The image holds on screen for that long.
* **Narrated** — set exactly one audio source and omit `duration`. The scene length follows the audio.

```json theme={null}
{
  "type": "image",
  "source": { "type": "url", "url": "https://example.com/chart.png" },
  "script": "Revenue grew forty percent quarter over quarter.",
  "voice_id": "YOUR_VOICE_ID"
}
```

`source` takes an [asset input](#asset-input). A silent image holds for up to `300` seconds. Both narrated scene types accept `voice_settings` with a `script`.

### Video Scenes

`"type": "video"` drops an existing clip into the sequence. Like an [image scene](#image-scenes), it plays in one of two modes:

* **Silent** — no audio source. The clip plays full-length at its own duration.
* **Narrated** — set exactly one voiceover source (the same audio inputs a narrated image scene accepts). The voiceover drives the scene's duration, and [`playback.mode`](#playback-and-scene-duration) controls how the clip fills that time — hold the last frame, loop, or adjust speed to fit.

```json theme={null}
{
  "type": "video",
  "source": { "type": "asset_id", "asset_id": "YOUR_ASSET_ID" },
  "script": "Here is the feature in action.",
  "voice_id": "YOUR_VOICE_ID",
  "playback": { "mode": "fit_to_scene", "mute": true }
}
```

`source` takes an [asset input](#asset-input). Omit [`playback`](#playback-and-scene-duration) to hold the last frame (narrated) and keep the clip's source volume.

#### Playback and scene duration

The `playback` object carries two composable controls: how the clip aligns to a voiceover-driven scene duration, and the clip's own audio level.

| Field | Type | Default | Description |
| - | - | - | - |
| `mode` | string | `freeze` | Narrated scenes only — how the clip fills the voiceover-driven duration. `freeze` plays the clip once and holds the last frame; `loop` repeats the clip; `fit_to_scene` adjusts playback speed so the clip ends exactly with the voiceover. |
| `volume` | number | `1.0` | Clip audio volume, `0.0`–`1.0`, where `1.0` is the source level. |
| `mute` | boolean | `false` | Force the clip silent regardless of `volume`. |

`mode` requires a voiceover, since the voiceover is what defines the target scene duration — a silent clip always plays full-length. The voiceover and the clip's own audio mix independently: there is no automatic ducking, so set `playback.volume` (or `mute`) yourself to bring the clip down under narration. With `fit_to_scene`, mute the clip when its source audio shouldn't be speed-adjusted along with the visuals.

## Asset input

The image/video scene `source` field, and the `source` of an image or video [scene background](#scene-backgrounds), take an asset object, discriminated by `type`. Provide one of:

| Form | Shape |
| - | - |
| Public URL | `{ "type": "url", "url": "https://..." }` |
| Uploaded asset | `{ "type": "asset_id", "asset_id": "..." }` — from [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset) (see [Assets](https://heygen-1fa696a7.mintlify.site/assets.md)). |

Use one of these two forms for scene sources and backgrounds; inline base64 returns a `400`.

## Captions

Pass a `caption` object to generate captions across the full composed video. Captions are derived from the speech in [`avatar_video`](#avatar-video-scenes) scenes and narrated [`image`](#image-scenes) scenes. A sidecar subtitle file is always returned via `subtitle_url` in the chosen `file_format` (default `srt`); add `"style": "default"` to also burn the captions into the rendered video.

## Brand Glossary

A [brand glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md) is a set of custom pronunciations, for example speaking `HeyGen` as `hey-jen`. Glossaries are created and edited in the HeyGen web app under Brand Kit. Pass one with the top-level `brand_glossary_id`, a **global** setting that applies to the whole request. Find your ids with [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries), and see which terms a glossary remaps with [`GET /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-glossary).

A glossary applies wherever HeyGen generates the speech: an `avatar_video` scene, or an `image` or `video` scene narrated with `script`. Scenes that supply finished audio (`audio_url` or `audio_asset_id`) play unchanged.

> A glossary changes the **spoken audio only**. Captions and the `.srt` sidecar keep the original spelling, so a term written `HeyGen` still reads `HeyGen` on screen while being spoken as `hey-jen`.

An id that does not exist in your workspace returns `400` and no video is created.

## Rendering at Scale

A studio request composes its scenes into a single video, so send studio videos one per request to `POST /v3/videos` and track each returned `video_id`. [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) rejects a `"type": "studio"` item.


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