Customize Video Background

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.

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.

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"
      }
    }
  ],
  "test": true,
  "aspect_ratio": "16:9"
}'

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

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

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.

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>"
      }
    }
  ],
  "test": true,
  "aspect_ratio": "16:9"
}'

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

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.

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

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