HeyGen Studio

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 — the same endpoint that renders avatar, image, and cinematic_avatar videos:

{
  "type": "studio",
  "scenes": [ ... ]
}

Each scene is one of three types:

Scene `type`	What it renders	Duration comes from
`avatar_video`	An avatar or animated image speaking a script or audio track	The audio
`image`	A still image, silent or narrated	`duration` (silent) or the audio (narrated)
`video`	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.

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

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} until status is completed, then read the download URL — or pass a callback_url to receive a webhook when the video is ready.

Request Body

The full schema is in the Create Video reference. scenes takes 1–50 scene types. Output settings are global: aspect_ratio (default 16:9, see Scene framing), resolution (720p or 1080p), caption, and brand_glossary_id, 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, 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 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. The input also takes voice_settings (including volume, 0.0–1.0), engine, motion_prompt, expressiveness, background, and remove_background.

To lip-sync your own photo, register it as a photo avatar first via the photo-avatar API, 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 when omitted. Pass { "type": "avatar_v" } for cross-reference-driven animation on Avatar V — 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.

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

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.

{
  "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. 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, 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 controls how the clip fills that time — hold the last frame, loop, or adjust speed to fit.

{
  "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. Omit playback 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, 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` (see Assets).

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 scenes and narrated image 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 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, and see which terms a glossary remaps with GET /v3/brand-glossaries/{brand_glossary_id}. 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 rejects a "type": "studio" item.

Get started

Video

Avatar

Voice

Audio

Image

Decision

Video editing

Brand

Platform

Overview

Quick Example

Request Body

Scene framing

Scene Types

Avatar Video Scenes

Choosing an engine

Scene backgrounds

Image Scenes

Video Scenes

Playback and scene duration

Asset input

Captions

Brand Glossary

Rendering at Scale