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:
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 colorstring Yes The tint color: rgb(...), rgba(...), or hex (#rrggbb) opacitynumber 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()
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 #6E6F843, 6, or 8 digit codes accepted
Next Steps
Media Elements Overlay videos and images on a scene, with their own color overlays
Background Video Settings Control mute, loop, and zoom behavior of background media
