Background Color Overlay

This guide shows you how to add a color overlay to your scene backgrounds. A color overlay is a semi-transparent layer of color placed on top of the background visual, like looking at your footage through tinted glass. The footage underneath is not modified; the tint is applied on top when the video is rendered.

Why Use a Color Overlay

Readable Subtitles

Darken busy footage so white captions stay easy to read

Brand Consistency

Wash every scene with your brand color for a uniform look

Mood and Tone

Cool blue for calm topics, warm amber for energetic ones

No Re-Editing

Works on stock, uploaded, and AI-generated visuals as-is

Before You Begin

Make sure you have:

A Pictory API key
Basic understanding of scene configuration in the Pictory API

Color overlays are processed by the v3 storyboard engine. Any scene that includes a colorOverlay is automatically routed to v3; you do not need to set storyboardVersion yourself.

How It Works

Add a colorOverlay object to any scene background. It has two fields:

Field	Type	Required	Description
`color`	string	Yes	The tint color: `rgb(...)`, `rgba(...)`, or hex (`#rrggbb`)
`opacity`	number	No	How strong the tint is, from `0` (invisible) to `1` (solid). Defaults to `0.4`

"scenes": [
  {
    "story": "Your scene narration here.",
    "background": {
      "colorOverlay": {
        "color": "rgb(110, 111, 132)",
        "opacity": 0.4
      }
    }
  }
]

That is all that is required. In this example Pictory picks a stock visual for the scene automatically (because no visualUrl is given) and renders it with a 40% gray-violet tint on top.

The overlay strength is controlled only by opacity. If you pass an rgba(...) color, its alpha channel is ignored: rgba(0, 0, 0, 0.9) with opacity: 0.4 produces the same result as rgb(0, 0, 0) with opacity: 0.4.

Where You Can Apply It

A color overlay works on every kind of background:

Background source	Works with overlay	Example
Auto-selected stock visual (from `story` text)	Yes	Overlay only, no other background fields
Explicit stock search (`searchFilter`)	Yes	Search plus tint in one request
Direct URL (`visualUrl`)	Yes	Tint your own uploaded footage
AI-generated visual (`aiVisual`)	Yes	Tint generated images and clips
Solid color (`color`)	Yes	Layer one color over another
B-rolls (`backgroundBrolls[]`)	Yes	Each B-roll can carry its own overlay
Media elements	Yes	Tint an individual video or image overlay

When a B-roll defines its own colorOverlay, that overlay wins for the time the B-roll is on screen; otherwise the scene background’s overlay is used.

Choosing Color and Opacity

A few practical starting points:

Goal	Suggested overlay
Make white subtitles readable on bright footage	`{ "color": "rgb(0, 0, 0)", "opacity": 0.4 }`
Subtle brand wash	Your brand color at `opacity` 0.2–0.3
Strong intro/outro branding	Your brand color at `opacity` 0.5–0.6
Muted, documentary feel	`{ "color": "rgb(110, 111, 132)", "opacity": 0.4 }`
Dramatic dark look	`{ "color": "rgb(26, 26, 46)", "opacity": 0.6 }`

Opacity above 0.7 hides most of the underlying footage; if that is what you want, consider a solid color background instead.

Examples

"scenes": [
  // 1. Auto-selected visual with a readability tint for captions
  {
    "story": "Our platform helps teams move faster.",
    "background": {
      "colorOverlay": { "color": "rgb(0, 0, 0)", "opacity": 0.4 }
    }
  },

  // 2. Explicit stock search with a hex brand color at default opacity (0.4)
  {
    "story": "Trusted by five thousand companies worldwide.",
    "background": {
      "searchFilter": { "keywords": ["city skyline", "night"] },
      "type": "video",
      "colorOverlay": { "color": "#1A1A2E" }
    }
  },

  // 3. Your own footage with a strong dark tint
  {
    "story": "Here is the product in action.",
    "background": {
      "visualUrl": "https://example.com/videos/product-demo.mp4",
      "type": "video",
      "colorOverlay": { "color": "rgb(0, 0, 0)", "opacity": 0.6 }
    }
  },

  // 4. A tinted solid background
  {
    "story": "Thanks for watching.",
    "background": {
      "color": "#FFFFFF",
      "colorOverlay": { "color": "rgb(110, 111, 132)", "opacity": 0.3 }
    }
  }
]

Complete Example

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY";

async function createVideoWithOverlays() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard`,
    {
      videoName: "video_with_color_overlay",
      scenes: [
        {
          story: "Every great product starts with a problem worth solving.",
          background: {
            colorOverlay: { color: "rgb(26, 26, 46)", opacity: 0.45 },
          },
        },
        {
          story: "We built ours after hearing the same complaint a hundred times.",
          background: {
            searchFilter: { keywords: ["team meeting", "whiteboard"] },
            type: "video",
            colorOverlay: { color: "#1A1A2E" },
          },
        },
      ],
    },
    {
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
    }
  );

  console.log("✓ Storyboard creation started!");
  console.log("Job ID:", response.data.data.jobId);
}

createVideoWithOverlays();

import requests

API_BASE_URL = "https://api.pictory.ai/pictoryapis"
API_KEY = "YOUR_API_KEY"

def create_video_with_overlays():
    response = requests.post(
        f"{API_BASE_URL}/v2/video/storyboard",
        headers={"Content-Type": "application/json", "Authorization": API_KEY},
        json={
            "videoName": "video_with_color_overlay",
            "scenes": [
                {
                    "story": "Every great product starts with a problem worth solving.",
                    "background": {
                        "colorOverlay": {"color": "rgb(26, 26, 46)", "opacity": 0.45},
                    },
                },
                {
                    "story": "We built ours after hearing the same complaint a hundred times.",
                    "background": {
                        "searchFilter": {"keywords": ["team meeting", "whiteboard"]},
                        "type": "video",
                        "colorOverlay": {"color": "#1A1A2E"},
                    },
                },
            ],
        },
    )

    print("✓ Storyboard creation started!")
    print("Job ID:", response.json()["data"]["jobId"])

create_video_with_overlays()

Color Formats

All color fields in the v2 API accept three formats:

Format	Example	Notes
RGB	`rgb(110, 111, 132)`	Channels 0–255
RGBA	`rgba(110, 111, 132, 1)`	The alpha channel is ignored for `colorOverlay.color`. Use `opacity` instead
Hex	`#6E6F84`	3, 6, or 8 digit codes accepted

Background Color Overlay

Why Use a Color Overlay

Readable Subtitles

Brand Consistency

Mood and Tone

No Re-Editing

Before You Begin

How It Works

Where You Can Apply It

Choosing Color and Opacity

Examples

Complete Example

Color Formats

Next Steps

Media Elements

Background Video Settings

​Why Use a Color Overlay

Readable Subtitles

Brand Consistency

Mood and Tone

No Re-Editing

​Before You Begin

​How It Works

​Where You Can Apply It

​Choosing Color and Opacity

​Examples

​Complete Example

​Color Formats

​Next Steps

Media Elements

Background Video Settings

Why Use a Color Overlay

Before You Begin

How It Works

Where You Can Apply It

Choosing Color and Opacity

Examples

Complete Example

Color Formats

Next Steps