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.

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`. Each scene is center-cropped to this canvas.
`resolution`	string	No	—	Global output resolution: `720p`, `1080p`, or `4k`.
`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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Overview

Quick Example

Request Body

Scene Types

Avatar Video Scenes

Choosing an engine

Image Scenes

Video Scenes

Playback and scene duration

Asset input

Captions

Brand Glossary

Rendering at Scale

​Overview

​Quick Example

​Request Body

​Scene Types

​Avatar Video Scenes

​Choosing an engine

​Image Scenes

​Video Scenes

​Playback and scene duration

​Asset input

​Captions

​Brand Glossary

​Rendering at Scale

Overview

Quick Example

Request Body

Scene Types

Avatar Video Scenes

Choosing an engine

Image Scenes

Video Scenes

Playback and scene duration

Asset input

Captions

Brand Glossary

Rendering at Scale