Videos

Get Video Scenes

Returns the video’s scenes together with the video-level context needed to use them, read together rather than assembled from separate calls. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated.

Each scene splits by the role a thing plays: background fills the frame, elements are placed within it, and script is the audio delivered over it. A whole-frame image or clip lands in background, so code that reads only elements misses it.

Element types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in elements, so the count is always truthful, but only avatar, image and video are described in full; group and mask carry their children; the rest carry an id and a type and nothing more.

What this does not describe. A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which are withheld to keep this version small and are returned on request.

GET

videos

{video_id}

scenes

Get Video Scenes

curl --request GET \
  --url https://api.heygen.com/v3/videos/{video_id}/scenes \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.heygen.com/v3/videos/{video_id}/scenes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/videos/{video_id}/scenes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/videos/{video_id}/scenes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/videos/{video_id}/scenes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "error": null,
  "data": {
    "video_id": "<string>",
    "video": {
      "title": "<string>",
      "aspect_ratio": "16:9",
      "resolution": "4k",
      "caption": {
        "enabled": true
      },
      "brand_glossary_id": "<string>"
    },
    "scenes": [
      {
        "id": "<string>",
        "background": {
          "color": "<string>",
          "type": "color"
        },
        "elements": [
          {
            "id": "<string>",
            "avatar_id": "<string>",
            "type": "avatar",
            "engine": "avatar_v",
            "expressiveness": "high",
            "motion_prompt": "<string>"
          }
        ],
        "script": [
          {
            "id": "<string>",
            "text": "<string>",
            "type": "text",
            "voice_id": "<string>",
            "voice_settings": {
              "speed": 123,
              "pitch": 123,
              "volume": 123,
              "locale": "<string>",
              "engine_settings": {
                "engine_type": "elevenlabs",
                "model": "eleven_multilingual_v2",
                "similarity_boost": 0.5,
                "stability": 0.5,
                "style": 0.5,
                "use_speaker_boost": true
              }
            },
            "trim_to_speech": true
          }
        ]
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Video not found",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "unknown_node_type",
        "message": "Unknown node type",
        "node_id": "<string>",
        "port": "<string>",
        "path": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Video not found.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Path Parameters

video_id

string

required

Unique video identifier

Response

Successful response

error

object | null

data

VideoScenesResponse · object

The composite document: one video's context and every one of its scenes.

Show child attributes

⌘I

Get Video Scenes

curl --request GET \
  --url https://api.heygen.com/v3/videos/{video_id}/scenes \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.heygen.com/v3/videos/{video_id}/scenes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/videos/{video_id}/scenes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/videos/{video_id}/scenes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/videos/{video_id}/scenes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "error": null,
  "data": {
    "video_id": "<string>",
    "video": {
      "title": "<string>",
      "aspect_ratio": "16:9",
      "resolution": "4k",
      "caption": {
        "enabled": true
      },
      "brand_glossary_id": "<string>"
    },
    "scenes": [
      {
        "id": "<string>",
        "background": {
          "color": "<string>",
          "type": "color"
        },
        "elements": [
          {
            "id": "<string>",
            "avatar_id": "<string>",
            "type": "avatar",
            "engine": "avatar_v",
            "expressiveness": "high",
            "motion_prompt": "<string>"
          }
        ],
        "script": [
          {
            "id": "<string>",
            "text": "<string>",
            "type": "text",
            "voice_id": "<string>",
            "voice_settings": {
              "speed": 123,
              "pitch": 123,
              "volume": 123,
              "locale": "<string>",
              "engine_settings": {
                "engine_type": "elevenlabs",
                "model": "eleven_multilingual_v2",
                "similarity_boost": 0.5,
                "stability": 0.5,
                "style": 0.5,
                "use_speaker_boost": true
              }
            },
            "trim_to_speech": true
          }
        ]
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Video not found",
    "param": "<string>",
    "doc_url": "<string>",
    "errors": [
      {
        "code": "unknown_node_type",
        "message": "Unknown node type",
        "node_id": "<string>",
        "port": "<string>",
        "path": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Video not found.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

Video Agent

Brand

Avatars

Audio

Voices

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

Webhooks

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Get Video Scenes

Authorizations

Path Parameters

Response