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.

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 }
      }
    ]
  }'

Response

{
  "data": {
    "video_id": "vid_9f2c..."
  }
}

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

Parameter	Type	Required	Default	Description
type	string	Yes	—	Must be studio.
scenes	array	Yes	—	Ordered list of whole-frame scenes to concatenate, 1–50. Each is one of the scene types below.
title	string	No	—	Display title for the video in the HeyGen dashboard.
aspect_ratio	string	No	16:9	Global output aspect ratio: 16:9, 9:16, 4:5, 5:4, 1:1, or auto. Every scene is rendered onto this one canvas — see Scene framing.
resolution	string	No	—	Global output resolution: 720p, 1080p, or 4k.

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.

| brand_glossary_id | string | No | — | Brand glossary controlling how custom terms are pronounced — see Brand Glossary. | | caption | object | No | — | Caption settings — see Captions. | | callback_url | string | No | — | Webhook URL to receive a POST notification when the video is ready. | | callback_id | string | No | — | Caller-defined identifier echoed back in the webhook payload. | | watermark | object | No | — | Custom watermark image overlay (PNG or JPEG). A premium option for select Enterprise customers — contact support to request access. |

The output container is MP4.

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

{
  "type": "avatar_video",
  "input": {
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "script": "Welcome back.",
    "voice_id": "YOUR_VOICE_ID"
  }
}

Field	Type	Required	Description
type	string	Yes	Must be avatar.
avatar_id	string	Yes	HeyGen avatar ID (video avatar or photo avatar look ID).
script	string	One audio source required	Text for the avatar to speak. Pair with voice_id, or omit voice_id to use the avatar’s default voice.
voice_id	string	With script	Voice for text-to-speech. Browse with GET /v3/voices. Optional when the avatar has a default voice.
audio_url	string	One audio source required	Public URL of an audio file to lip-sync.
audio_asset_id	string	One audio source required	Asset ID of an uploaded audio file — see Asset Management.
voice_settings	object	No	Voice tuning: speed (0.5–1.5), pitch (-50–50 semitones), volume (0.0–1.0), locale.
engine	object	No	Generation engine — see Choosing an engine.
motion_prompt	string	No	Natural-language prompt controlling body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars on Avatar V.
expressiveness	string	No	Expressiveness level for photo avatars on Avatar IV. Defaults to low.
background	object	No	Solid-color background composited behind the avatar: { "type": "color", "color": "#RRGGBB" }.

Provide exactly one audio source: script (with voice_id or a default voice), audio_url, or audio_asset_id.

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 needs a usable reference look in the avatar’s group, so it is not available for every photo avatar: if the group has none, the request fails 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 rather than guaranteeing eligibility: a non-public group needs consent. A look with status: processing (still training) can still be used as a reference.

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"
}

Field	Type	Required	Description
type	string	Yes	Must be image.
source	object	Yes	Still image to display — see Asset input.
duration	number	Silent mode	Seconds to hold the image, up to 300.
script	string	Narrated mode	Text to speak over the image. Pair with voice_id.
voice_id	string	With script	Voice for text-to-speech.
audio_url	string	Narrated mode	Public URL of an audio file to play over the image.
audio_asset_id	string	Narrated mode	Asset ID of an uploaded audio file.
voice_settings	object	No	Voice tuning (speed, pitch, locale).

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

Field	Type	Required	Description
type	string	Yes	Must be video.
source	object	Yes	Video clip to include — see Asset input.
script	string	Narrated mode	Voiceover text to speak over the clip. Pair with voice_id.
voice_id	string	With script	Voice for text-to-speech. Browse with GET /v3/voices.
audio_url	string	Narrated mode	Public URL of an audio file to play over the clip.
audio_asset_id	string	Narrated mode	Asset ID of an uploaded audio file — see Asset Management.
voice_settings	object	No	Voice tuning (speed, pitch, locale) for a script voiceover.
playback	object	No	Scene-duration alignment and clip audio control — see Playback and scene duration. Omit to hold the last frame (narrated) and keep the clip’s source volume.

In narrated mode, provide exactly one voiceover source: script (with voice_id), audio_url, or audio_asset_id.

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 takes 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 Asset Management).
Inline base64	{ "type": "base64", "media_type": "image/png", "data": "<base64>" }

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; add style to additionally burn the captions into the rendered video — the sidecar is still delivered.

Field	Type	Required	Default	Description
file_format	string	No	srt	Format of the sidecar caption file.
style	string	No	—	Visual style for burned-in captions: default. Omit for sidecar-only captions.

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.

{ "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40" }

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 it is not accepted by the batch endpoint. A "type": "studio" item in POST /v3/videos/batches is rejected. Send studio videos one per request to POST /v3/videos and track each returned video_id.