Customize Video Background

Source: https://docs.heygen.com/docs/customize-video-background Generated: 2025-09-18 10:44:29

With HeyGen you can create videos with custom backgrounds. You can choose from Color , Image or Video sources as the background. To do this you need to change the "Background Settings " type to the appropriate option.

Learn more about Video Translate

Color Background

See detailed API reference
To select the background as color , you need change the background type to color. Then enter a color hex code in the value field.

RequestResponse

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

iframe

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

iframe

Image Background

See detailed API reference
To select the background as image , you need change the background type to image. Then you need to provide either url for external image url or image_asset_id for image asset from HeyGen.

RequestResponse

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

iframe

Video Background

See detailed API reference
To select the background as video , you need change the background type to video. Then you need to provide either url for external videos or video_asset_id for video assets from HeyGen.

Learn more about AI video avatar

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

RequestResponse

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

iframe

__Updated 4 months ago

Ask AI

customize video background

Customize Video Background