HeyGen Streaming Avatar API: Custom Background Colors (Code Examples)

If you searched for HeyGen StreamingAvatarAPI NewSessionRequest background type color value hex, you probably have the HeyGen docs open in one tab and a broken API call in the other. This guide gives you the straight answer: which HeyGen API endpoints accept the background parameter, which ones ignore it, and exactly how to get a custom background color on a streaming avatar session.

All code examples below are verified against HeyGen's v2 API documentation and the LiveAvatar Web SDK as of May 2026.

The Background Parameter: Where It Works

HeyGen has two fundamentally different APIs for avatar video:

The confusion happens because the Studio Video API and the Streaming Avatar API share similar parameter shapes, but the background object only works in the Studio Video API. HeyGen's own team confirmed this in their developer forums: “The background color of the interactive avatar cannot be customized using the provided parameter. You’ll need to handle the background removal on your side.”

Studio Video API: Working Code (Color, Image, Transparent)

If you are generating pre-rendered avatar videos (not real-time streaming), this is the API you want. The background object goes inside each element of video_inputs.

Solid Color Background (Hex)

cURL

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": "YOUR_AVATAR_ID",
        "avatar_style": "normal"
      },
      "voice": {
        "type": "text",
        "input_text": "Hello from a custom background.",
        "voice_id": "YOUR_VOICE_ID"
      },
      "background": {
        "type": "color",
        "value": "#FAFAFA"
      }
    }],
    "dimension": { "width": 1920, "height": 1080 }
  }'

Python (requests)

Python

import requests

url = "https://api.heygen.com/v2/video/generate"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "video_inputs": [{
        "character": {
            "type": "avatar",
            "avatar_id": "YOUR_AVATAR_ID",
            "avatar_style": "normal"
        },
        "voice": {
            "type": "text",
            "input_text": "Hello from a custom background.",
            "voice_id": "YOUR_VOICE_ID"
        },
        "background": {
            "type": "color",
            "value": "#1a1a2e"  # dark navy
        }
    }],
    "dimension": {"width": 1920, "height": 1080}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Other Background Types

The Studio Video API supports four background types:

Streaming Avatar API: Why Background Does Not Work

The old @heygen/streaming-avatar SDK (v1.x–2.x) accepted a background field in createStartAvatar(). Developers tried passing it like this:

JavaScript (broken)

// THIS DOES NOT WORK - shown for reference only
const sessionData = await avatar.createStartAvatar({
  quality: AvatarQuality.High,
  avatarName: "YOUR_AVATAR_ID",
  voice: { voiceId: "YOUR_VOICE_ID" },
  background: {
    type: "color",        // ignored by the API
    value: "#000000"      // ignored by the API
  }
});

The API either silently ignores the background field or returns an error, depending on the SDK version. The streaming session always renders the avatar on a green screen regardless of what you pass.

LiveAvatar: Client-Side Chroma-Key Workaround

Since neither the old Streaming Avatar API nor the new LiveAvatar API supports server-side background customization, you handle it on the client. The approach: receive the green-screen video stream, remove the green pixels using canvas compositing, then composite your desired background underneath.

HeyGen provides an official reference implementation in their liveavatar-web-sdk repository. The apps/bg-removal-demo app demonstrates:

• Client-side chroma-key on the green-screen video stream
• Swap background to any hex color, image URL, or video URL
• No session restart required when changing backgrounds

How It Works (Simplified)

JavaScript

// 1. Capture each video frame onto a hidden canvas
const ctx = canvas.getContext("2d");
ctx.drawImage(videoElement, 0, 0, canvas.width, canvas.height);

// 2. Read pixel data
const frame = ctx.getImageData(0, 0, canvas.width, canvas.height);
const data = frame.data;

// 3. Replace green pixels with transparent
for (let i = 0; i < data.length; i += 4) {
  const r = data[i], g = data[i + 1], b = data[i + 2];
  // Check if pixel is "green screen" green
  if (g > 80 && r < 100 && b < 100) {
    data[i + 3] = 0; // set alpha to 0 (transparent)
  }
}

// 4. Put modified frame back
ctx.putImageData(frame, 0, 0);

// 5. Composite over your desired background
// (render your background color/image on a layer behind the canvas)

For production use, consider a WebGL shader instead of per-pixel canvas manipulation — it offloads the work to the GPU and handles edge anti-aliasing more gracefully. The HeyGen bg-removal-demo app uses this approach.

To run the official demo locally:

Terminal

git clone https://github.com/heygen-com/liveavatar-web-sdk.git
cd liveavatar-web-sdk
pnpm install
pnpm demo:bg-removal    # starts on port 3002

Common Hex Color Values for HeyGen Backgrounds

Whether you are using the Studio Video API (where you pass the hex directly) or a chroma-key replacement (where you render the hex on your background layer), these are the most-used values:

The hex format for HeyGen's Studio Video API requires the # prefix followed by six hexadecimal digits (e.g., #FAFAFA). Three-digit shorthand (#FFF) is not documented as supported — always use the full six-digit format.

Frequently Asked Questions

Related Guides

• HeyGen Review 2026: 30+ Features Tested — full platform review including Avatar V, Interactive Avatars, and API features
• Best AI Talking Head Tools 2026 — how HeyGen compares to Synthesia, D-ID, and others for avatar video
• HeyGen Pricing 2026: Plans & Cost Per Minute — API credit costs, plan breakdowns, and per-minute economics
• Best AI Video Tools 2026 (Top 10 Ranked) — the definitive ranking of all AI video platforms

Last updated: May 21, 2026. Pricing and API behavior verified against HeyGen documentation and developer forum responses.