> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Background Color Overlay
> Tint any scene background with a color overlay: improve subtitle readability, apply your brand color, or set a mood without editing the source footage
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
Darken busy footage so white captions stay easy to read
Wash every scene with your brand color for a uniform look
Cool blue for calm topics, warm amber for energetic ones
Works on stock, uploaded, and AI-generated visuals as-is
## Before You Begin
Make sure you have:
* A [Pictory API key](https://app.pictory.ai/api-access)
* Basic understanding of [scene configuration](/guides/text-to-video/text-to-video-basic) 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` |
```jsonc theme={null}
"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](/guides/advanced-features/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
```jsonc theme={null}
"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
```javascript Node.js theme={null}
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();
```
```python Python theme={null}
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 |
## Next Steps
Overlay videos and images on a scene, with their own color overlays
Control mute, loop, and zoom behavior of background media