Customize Video Background

With HeyGen, you can create videos with custom backgrounds. You can choose one of the following three sources for the background:

Color
Image
Video

To do this, you need to change the "Background Settings" type to the appropriate option in the Create Avatar Video (V2) endpoint.

Color Background

In this example, we’re setting a solid color background for the avatar video.
To do this, set the background type to color. and specify the desired color using a hex code in the value field (for example, here we set it to #FAFAFA which corresponds to a light gray color).

📘
Note:
To retrieve the avatar_id and voice_id used in this request, refer to the following APIs: List All Avatars (V2) and List All Voices (V2).

curl -X POST https://api.heygen.com/v2/video/generate \
-H 'X-Api-Key: <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Brain_public_pro4_20230613",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "With HeyGen, it is very easy to create avatar videos with custom backgrounds.",
        "voice_id": "d7bbcdd6964c47bdaae26decade4a933"
      },
      "background": {
        "type": "color",
        "value": "#FAFAFA"
      }
    }
  ]
}'

{
  "code": 100,
  "data": {
    "video_id": "<video_id>"
  },
  "message": "Success"
}

Avatar Video with Color Background

You can also set the color code to #008000 if you want to create green screen videos.

Image Background

In this example, we’re setting an image background for the avatar video.
To set the background as image, you need change the background type to image. Then, you need to provide either the url or image_asset_id for the image asset from Heygen. Exactly one of these parameters must be provided. Omitting both, or defining both, will result in an error. These parameters can be obtained from the response of the Upload Asset API.

curl -X POST https://api.heygen.com/v2/video/generate \
-H 'X-Api-Key: <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Brain_public_pro4_20230613",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "With HeyGen, it is very easy to create avatar videos with custom backgrounds.",
        "voice_id": "d7bbcdd6964c47bdaae26decade4a933"
      },
      "background": {
        "type": "image",
        "image_asset_id": "<asset_id>"
      }
    }
  ]
}'

{
  "code": 100,
  "data": {
    "video_id": "<video_id>"
  },
  "message": "Success"
}

Avatar Video with Image Background

Video Background

In this example, we’re setting a video background for the avatar video.
To set the background as video, you need change the background type to video. Then, you need to provide either the url or video_asset_id for video asset from HeyGen. Exactly one of these parameters must be provided. Omitting both, or defining both, will result in an error. These parameters can be obtained from the response of the Upload Asset API.

You can also specify video playback style with play_style. Supported values are fit_to_scene, freeze, loop, full_video.

curl -X POST https://api.heygen.com/v2/video/generate \
-H 'X-Api-Key: <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "video_inputs": [
    {
      "character": {
        "type": "avatar",
        "avatar_id": "Brain_public_pro4_20230613",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "With HeyGen, it is very easy to create avatar videos with custom backgrounds.",
        "voice_id": "d7bbcdd6964c47bdaae26decade4a933"
      },
      "background": {
        "type": "video",
        "video_asset_id": "<asset_id>",
        "play_style": "loop"
      }
    }
  ]
}'

{
  "code": 100,
  "data": {
    "video_id": "<video_id>"
  },
  "message": "Success"
}

Avatar Video with Video Background

For more details on background configuration options, supported values, and additional parameters for video generation, see detailed API Reference: Create Avatar Video (V2)