Skip to main content
POST
Create Storyboard Preview

​
Overview

The Storyboard Preview API generates a preview of your video project, allowing you to review the storyboard structure, scene breakdown, visual selections, and configuration before committing to the final render. This is an essential step in the video creation workflow that helps you validate your content and make adjustments without incurring full rendering costs.
The storyboard preview creates a project with scene thumbnails and metadata. To generate the final rendered video, use the Render from Preview API after reviewing and approving the preview.
Recommended Workflow: Create Preview → Review Scenes → Make Adjustments → Render Final Video

​
Render Workflow Options

​
Preview vs. Final Render

​
Use Cases

Content Review

Preview how your text will be split into scenes before rendering

Visual Validation

Review AI-selected visuals and backgrounds for each scene

Scene Adjustment

Identify scenes that need text or visual changes

Approval Workflow

Share previews with stakeholders before final render

Cost Optimization

Validate content before using rendering resources

Iterative Creation

Quickly iterate on content and settings

Template Testing

Test templates and brand settings before production

Batch Preparation

Prepare multiple video projects for batch rendering

AI-Designed Scenes

Review AI-designed layouts and on-screen text before rendering (aiStoryboard)

​
API Endpoint

​
Request Headers

​
string
required
API key for authentication
​
string
required
Must be application/json

​
Request Body Parameters

​
string
required
Name for your video project (alphanumeric, spaces, underscores, and hyphens only, max 150 characters)Optional when aiStoryboard is enabled with a brief scene: if omitted, the AI-generated title is used as the project name.
​
integer
Width of the generated video in pixels. Must be provided together with videoHeight.
​
integer
Height of the generated video in pixels. Must be provided together with videoWidth.
​
string
Video aspect ratio. Options: 1:1, 16:9, 9:16, 4:5
​
string
Language of the text content.Allowed values: zh, nl, en, fr, de, hi, it, ja, ko, mr, pt, ru, es, tazh Chinese, nl Dutch, en English, fr French, de German, hi Hindi, it Italian, ja Japanese, ko Korean, mr Marathi, pt Portuguese, ru Russian, es Spanish, ta Tamil
​
boolean
Whether to save the project in your Pictory account for later editing. Default: false
​
string
URL where the completed storyboard preview output will be sent via POST request when finished (max 500 characters)
​
object
Custom data object that will be included in the webhook POST payload when the job completes. Use this to pass through any metadata (e.g., internal IDs, tracking info) that you need in your webhook handler.
​
string
ID of a template to use. Get from Get Templates API.
​
object
Key-value object for template variables. Only applicable when templateId is provided.
​
string
ID of the brand to apply. Get from Get Video Brands API. Cannot be used with brandName.
​
string
Name of the brand to apply. Cannot be used with brandId.
​
string
Name of the smart layout to apply. Get available layouts from Get Smart Layouts API. Cannot be used with smartLayoutId.
​
string
ID of the smart layout to apply. Get from Get Smart Layouts API. Cannot be used with smartLayoutName.
​
object
Let AI design every scene (layout, on-screen text elements, color palette) or, with a brief scene, write the script as well. Set { "enabled": true } to turn it on. See aiStoryboard Object.
​
string
Experimental: This field is currently experimental. In the future, all storyboards will automatically use the latest version, and this field will be ignored. There is no need to remove it from your requests when that happens.
Specifies which storyboard version to use. Set to v3 to create a latest Pictory storyboard. Omit this field to use the classic storyboard.Options:
  • v3: Uses the latest Pictory storyboard
  • Omit or any other value: Uses the classic/legacy storyboard
​
string
ID of a saved text style for subtitles. Get from Get Text Styles API. Cannot be used with subtitleStyleName.
​
string
Name of a saved text style for subtitles. Cannot be used with subtitleStyleId.
​
object
Inline subtitle style configuration. See subtitleStyle Object.
​
string
AWS connection ID for accessing private S3 assets. Get from Get AWS Connections API.
​
string
Vimeo connection ID for uploading videos directly to Vimeo. Get from Get Vimeo Connections API.
​
array
Array of destination configurations for uploading the generated video (max 5). See destinations Array.
​
object
Voice-over configuration for AI narration. See voiceOver Object.
​
object
Background music configuration for the video. See backgroundMusic Object.
Logo overlay configuration. See logo Object.
​
array
required
Array of scene objects containing the content to convert into video. Required unless using templateId. See scenes Array.
​
object
AI avatar configuration for presenter-style videos. See avatar Object.

​
aiStoryboard Object

Turns on the AI Storyboard: instead of a full-screen visual with subtitles, every scene receives a layout, on-screen text elements, and a color palette chosen by AI. With a story or blogUrl scene the AI designs around your narration (script mode); with a single brief scene it writes the narration and designs the storyboard in the same pass (brief mode). See the AI Storyboard guide.
​
boolean
required
Set to true to have the AI design the storyboard. The object is optional; omit it or set false for the standard storyboard.
Text-to-video only. With aiStoryboard enabled, each scene must use story, brief, or blogUrl. The following are rejected with a 400 response: templateId, variables, smartLayoutName, smartLayoutId, aspectRatio: "4:5", and the scene fields pptUrl, audioUrl, videoUrl, transcript, mediaRepurposeSettings, audioLanguage, useSpeakerNotes, isSSMLStory, backgroundBrolls, backgroundCorpus, and templateOverride.
Scene rules. A story scene without a split option is split into one designed scene per sentence; a scene that cannot be split and exceeds 1500 characters is rejected. A brief must be the only scene, its duration, if set, must be 8–500 seconds, its prompt at most 3900 characters, and it cannot use createSceneOnNewLine or createSceneOnEndOfSentence. A video can have at most 250 designed scenes. Each scene’s background configuration (stock search, visualUrl, aiVisual, color) is placed into the designed layout; in brief mode the single scene’s configuration applies to every generated scene.
Response. In brief mode storyboard.scenes[].story holds the generated narration. Rendering the preview with Render Video from Preview keeps the design; re-submitting the storyboard to this endpoint designs it again. The design step adds 1–3 minutes to the job.

​
voiceOver Object

Voice-over configuration for AI narration.
The following fields are nested inside the top-level voiceOver object. For example, voiceOver.enabled means enabled is a property of the voiceOver object.
​
boolean
required
Enable or disable voice-over.
​
array
Array of AI voice configurations (max 10). See aiVoices Array.
​
object
External voice file configuration. See externalVoice Object. Cannot be used with aiVoices.

​
aiVoices Array

The following fields are nested inside each element of the voiceOver.aiVoices array. For example, voiceOver.aiVoices[].speaker means speaker is a property of each item in the aiVoices array, which itself is nested inside the voiceOver object. The [] notation indicates an array element.
​
string
required
Voice speaker name (e.g., “Brian”, “Emma”). Get available voices from Get Voiceover Tracks API.
​
number
Speech speed from 50 to 200. Default: 100
​
number
Volume level from -1 to 1. Default: 0
​
object
ElevenLabs premium voice settings. See premiumVoiceSettings Object.

​
premiumVoiceSettings Object

The following fields are nested inside premiumVoiceSettings, which is a property of each voiceOver.aiVoices[] element. For example, voiceOver.aiVoices[].premiumVoiceSettings.modelId means modelId is inside premiumVoiceSettings, inside each voice in the aiVoices array, inside the voiceOver object.
​
string
ElevenLabs model. Options: eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5, eleven_turbo_v2_5, eleven_turbo_v2, eleven_flash_v2, eleven_multilingual_v1, eleven_monolingual_v1
​
string
Voice stability as percentage (e.g., “50%”)
​
boolean
Enable speaker boost enhancement.
​
string
Similarity boost as percentage (e.g., “75%”)
​
string
Voice style as percentage (e.g., “50%“)

​
externalVoice Object

The following fields are nested inside the voiceOver.externalVoice object. For example, voiceOver.externalVoice.voiceUrl means voiceUrl is a property of externalVoice, which itself is nested inside the voiceOver object.
​
string
required
URL to external voice audio file.
​
boolean
Auto-synchronize voice with video subtitles.
​
number
Audio amplification level from -1 to 1. Default: 0

​
avatar Object

AI avatar configuration for creating presenter-style videos with lifelike avatars that lip-sync to AI narration.
Avatars require voice-over to be enabled. Use the Get Avatars API to retrieve available avatarId values.
​
string
required
Unique identifier for the avatar look (e.g., “Annie_expressive12_public”). Get from Get Avatars API.
​
string
Preset position for the avatar. Options: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-rightDefault: bottom-right
​
string
Avatar width as percentage (e.g., “20%”, “25%”, “30%”). Must be an integer percentage from 0% to 100%.Default: "20%"
​
string
Corner rounding. Options: 0 (square), 50 (rounded), 100 (circular)
​
string
Border color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,1)”, “rgba(132,44,254,1)”)
​
number
Border width in pixels. Minimum: 0
​
string
Background color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,0.5)”)
​
boolean
Hide the avatar globally across all scenes. When true, the entire avatar pipeline is skipped. Can be overridden per scene.Default: false
Avatar settings can be overridden at the scene level. See scenes[].avatar Object for scene-specific customization.

​
backgroundMusic Object

Background music configuration for the video.
The following fields are nested inside the top-level backgroundMusic object. For example, backgroundMusic.enabled means enabled is a property of the backgroundMusic object.
​
boolean
required
Enable or disable background music.
​
boolean
Auto-select background music. Cannot be used with musicUrl.
​
string
Any publicly accessible URL to an audio file, on your own hosting or a CDN. It is not limited to Pictory-provided tracks. Cannot be used with autoMusic. An audioUrl returned by Search Music Tracks is also a valid value; pass it exactly as returned and Pictory licenses the track at render time.
​
number
Volume level from 0 to 1. Default: 0.5. Scene tracks without their own volume use this value.
​
array
Time clips to use from the music (max 10). Each clip has start and end numbers in seconds.

​
logo Object

Logo overlay configuration.
The following fields are nested inside the top-level logo object. For example, logo.url means url is a property of the logo object.
​
string
required
URL to logo image file.
​
string
Logo position. Options: top-left, top-right, top-center, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right
​
string
Logo width as percentage (e.g., “15%“)

​
subtitleStyle Object

Inline subtitle style configuration. Can be used at video level or scene level.
The following fields are nested inside the subtitleStyle object. For example, subtitleStyle.fontFamily means fontFamily is a property of the subtitleStyle object. This object can be used at the top level or inside scenes[] as scenes[].subtitleStyle.
​
string
URL to custom font file. When provided, fontFamily is required.
​
string
Font family name. Required when fontUrl is provided. See Supported Font Families.
​
integer
Font size in pixels. Minimum: 1
​
string
Text color in RGBA format (e.g., “rgba(255,255,255,1)”)
​
string
Background color in RGBA format (e.g., “rgba(0,0,0,0.5)”).
​
string
Shadow color.
​
string
Shadow width as percentage (e.g., “10%”)
​
string
Color for highlighted keywords in RGBA format (e.g., “rgba(255,255,0,1)”).
​
string
Text position. Options: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right
​
string
Text alignment. Options: left, center, right
​
array
Text decorations. Options: bold, underline, italics, linethrough
​
string
Text case. Options: uppercase, lowercase, capitalize, smallcapitalize
​
string
Paragraph width as percentage (e.g., “80%”)
​
array
Text animations (max 2: one entry, one exit). See animations Array.
See Text Animations Guide for all animation types and examples.

​
animations Array

The following fields are nested inside each element of the subtitleStyle.animations array. For example, subtitleStyle.animations[].name means name is a property of each item in the animations array, which itself is nested inside the subtitleStyle object. The [] notation indicates an array element.
​
string
required
Animation name. Options: none, fade, drift, wipe, text reveal, elastic, typewriter, blur, bulletin
​
string
required
Animation type. Options: entry, exit
​
string
required
Animation speed. Options: slow, medium, fast, custom
​
number
Custom speed value (min 0.5). Required when speed is custom.
​
string
Animation direction. Options: up, down, left, right
​
string
Writing style for text animations. Options: character, word, line, paragraph
​
string
Controls how upcoming words appear on screen. Only available with fade and blur entry animations. When AI voiceover is enabled, words sync with the spoken audio.Options:
  • "hidden": Upcoming words are invisible, words appear only when spoken
  • "subtle": Upcoming words are faintly visible, current word is highlighted
  • "prominent": All text is clearly visible, spoken word is highlighted brighter
See Text Animations Guide for examples.

​
Supported Font Families

Anton, Archivo Narrow, Arial, Averia Libre, Barlow, Barlow Black, Bebas Neue, Calibri, Caprasimo, Capriola, Carter One, Caveat, Chakra Petch, Chewy, Comfortaa, Courier Prime, Dancing Script, Dangrek, Delius Unicase, DM Sans, Grandstander, Gruppo, Heartbeat, Helvetica, Helvetica Neue Medium, JM Modern, Josefin Sans, Julius Sans One, Laisha, Lato, Lato Extrabold, Lexend, LT Wave, Manrope, Merriweather, Montserrat, Moon dance, Mustard, Notosans, Opensans, Optik, Party Confetti, Patua One, Playfair Display, Plus Jakarta Sans, Poppins, Poppins Extrabold, Proxima Nova, Quicksand, Raleway, Raleway Black, Raleway Thin, Roboto, Rokkitt, Rowdies, Russo One, Satisfy, Sora, Source Sans Pro, Space Grotesk, Space mono, Special Elite, Strive, Titillium Web, Titillium Web Black, Ubuntu, Unbounded, Work Sans, Noto Sans JP, Noto Serif JP, Noto Sans Tamil, Noto Sans Devanagari, Noto Serif Devanagari

​
destinations Array

Array of destination configurations for uploading the generated video (max 5).

​
Vimeo Destination

The following fields are nested inside each element of the top-level destinations array. For example, destinations[].type means type is a property of each item in the destinations array. The [] notation indicates an array element.
​
string
required
Must be vimeo
​
string
Vimeo folder URI.
​
array
Content rating. Options: violence, drugs, language, nudity, advertisement, safe, unrated
​
object
Privacy settings. See Vimeo Privacy Object.

​
Vimeo Privacy Object

The following fields are nested inside the privacy object of each destinations[] element. For example, destinations[].privacy.view means view is a property of privacy, which itself is nested inside each item of the destinations array.
​
string
View access. Options: anybody, contacts, disable, nobody, password, unlisted, users
​
string
Embed access. Options: private, public, whitelist
​
string
Comment access. Options: anybody, contacts, nobody
​
boolean
Allow adding to albums/channels.
​
boolean
Allow downloads.

​
scenes Array

Each scene in the scenes array can contain various content sources and settings.
Each scene can only have ONE content source. Choose one of: story, brief, blogUrl, pptUrl, audioUrl, or videoUrl.
A scene may have no content source when its background fills the frame: a visualUrl, a color, or an aiVisual. A scene carried by an AI-generated background alone must set background.aiVisual.prompt, because there is no story to write one from. An AI video clip generated with audio: true plays its own sound, such as dialogue spoken in the clip or ambience, unless settings.mute is true. Set background.aiVisual.videoDuration and minimumDuration to the same length so the scene lasts as long as the clip.
The following fields are nested inside each element of the top-level scenes array. For example, scenes[].story means story is a property of each item in the scenes array. The [] notation indicates an array element.
​
string
Text content for creating video from text (max 15000 characters).
​
object
AI script generation from an idea. See brief Object. With aiStoryboard enabled, the AI also designs the storyboard.
​
string
URL to blog/article content.
​
string
URL to PowerPoint presentation file.
​
string
URL to audio file for audio-to-video conversion. Requires audioLanguage.
​
string
URL to video file for video repurposing. Requires audioLanguage.
​
boolean
Create new scene on each new line. Default: false
​
boolean
Create new scene at end of each sentence. Default: false
​
integer
Maximum number of caption lines displayed simultaneously. Integer from 1 to 4. When omitted, all caption lines for the scene are displayed at once.
  • 1: Single line (ideal for TikTok/Reels)
  • 2: Two lines (standard for most content)
  • 3: Three lines (educational/detailed content)
  • 4: Four lines (information-heavy content)
Cannot be used with smart layouts (smartLayoutId or smartLayoutName). When AI voiceover is enabled, caption lines sync with the spoken audio. See Dynamic Captions Guide.
​
boolean
Highlight keywords in subtitles.
​
boolean
Hide subtitles for this scene.
​
number
Minimum duration for the scene in seconds.
​
number
Pause duration at the end of the scene in seconds.
​
string
Transition effect. Options: none, wipeup, wipedown, wipeleft, wiperight, smoothleft, smoothright, radial, circlecrop, hblur, fade
​
string
Language of audio content. Required for audioUrl and videoUrl.Allowed values: en-US, en-AU, en-GB, en-IN, en-IE, en-AB, en-WL, fr-CA, fr-FR, de-CH, de-DE, it-IT, es-ES, es-US, nl-NL, pt-BR, ja-JP, ko-KR, ru-RU, hi-IN, ta-IN, mr-INen-US English (US), en-AU English (Australia), en-GB English (UK), en-IN English (India), en-IE English (Ireland), en-AB English (Arabic accent), en-WL English (Wales), fr-CA French (Canada), fr-FR French (France), de-CH German (Switzerland), de-DE German (Germany), it-IT Italian (Italy), es-ES Spanish (Spain), es-US Spanish (US), nl-NL Dutch (Netherlands), pt-BR Portuguese (Brazil), ja-JP Japanese (Japan), ko-KR Korean (Korea), ru-RU Russian (Russia), hi-IN Hindi (India), ta-IN Tamil (India), mr-IN Marathi (India)
​
boolean
Use speaker notes from PowerPoint. Only valid with pptUrl.
​
object
Animate PowerPoint slides into short video backgrounds. Each still slide is sent to an image-to-video model using the slide itself as the first frame, so the clip opens on the original slide. The clip loops for the length of the scene, so the slide returns at the start of every cycle. Slides that already contain video, including slides that use PowerPoint build animations, are left unchanged. Only valid with pptUrl.
​
boolean
Whether story text contains SSML markup. Only valid with story. Default: false
​
string
Separate caption text for the scene (max 3000 characters). Requires story.
​
string
Language of caption text. Only valid with caption.Allowed values: zh, nl, en, fr, de, hi, it, ja, ko, mr, pt, ru, es, tazh Chinese, nl Dutch, en English, fr French, de German, hi Hindi, it Italian, ja Japanese, ko Korean, mr Marathi, pt Portuguese, ru Russian, es Spanish, ta Tamil
​
string
ID of a saved text style for this scene’s subtitles. Cannot be used with subtitleStyleName.
​
string
Name of a saved text style for this scene’s subtitles. Cannot be used with subtitleStyleId.
​
object
Inline subtitle style for this scene. Overrides video-level subtitle style. See subtitleStyle Object.
​
object
Voice-over configuration specific to this scene. Overrides video-level settings. See scenes[].voiceOver Object.
​
object
This scene’s own music track and volume, or music turned off for the scene. See scenes[].backgroundMusic Object.
​
object
Avatar customization specific to this scene. Overrides global avatar settings. See scenes[].avatar Object.
​
object
Background media configuration for this scene. See background Object.
​
array
Array of B-roll background configurations. See backgroundBrolls Array.
​
array
Array of background images to use as a corpus (max 100). See backgroundCorpus Array.
​
array
Transcription of input video or audio. Required when repurposing audioUrl or videoUrl. See transcript Array.
​
object
Settings for repurposing media content. Only valid with audioUrl or videoUrl. See mediaRepurposeSettings Object.
​
object
Configuration for manipulating template scenes. Only available when templateId is provided. See templateOverride Object.
​
array
Overlay elements placed on top of the scene background (max 20 per scene). Each element has a type of shape, text, video, or image. See elements Array.

​
brief Object

Describe the video you want and the AI writes the script. Without aiStoryboard, the generated script is split into scenes according to the scene split options and built as a standard storyboard. With aiStoryboard enabled, the AI also decides the scenes and designs each of them; the brief must then be the only scene.
The following fields are nested inside the brief object, which is a property of each scenes[] element. For example, scenes[].brief.prompt means prompt is a property of brief, which itself is nested inside each item of the scenes array.
​
string
required
Topic or description for AI to generate content (1–5000 characters; at most 3900 with aiStoryboard).
​
string
Goal of the video. Options: Explainer, Marketing, Internal Communication, Tutorial, Product. Default: Explainer
​
integer
Target duration in seconds (1–600; 8–500 with aiStoryboard, where omitting it lets the AI choose).
​
string
Target platform for script generation. Options: YouTube, TikTok, Instagram, Facebook, LinkedIn, Twitter. Not used by the AI Storyboard.
​
string
Tone of the generated content. Options: professional, casual, friendly, informative, persuasive, exciting, educational, humorous, serious, conversational

​
scenes[].voiceOver Object

Voice-over configuration specific to a scene. Overrides video-level voice-over settings.
The following fields are nested inside the voiceOver object at the scene level. For example, scenes[].voiceOver.enabled means enabled is a property of voiceOver, which itself is nested inside each item of the scenes array. This is separate from the top-level voiceOver object.
​
boolean
required
Enable or disable voice-over for this scene.
​
array
Array of AI voice configurations (max 10). Same structure as aiVoices Array.
​
object
External voice configuration with voiceUrl, clips array, and amplificationLevel.

​
scenes[].backgroundMusic Object

Use this object to give one scene its own music, set how loud it is, or turn music off for that scene. Set musicUrl, enabled, or both. See the Scene-Level Music guide.
The following fields are nested inside the backgroundMusic object at the scene level. For example, scenes[].backgroundMusic.enabled means enabled is a property of backgroundMusic, which itself is nested inside each item of the scenes array. This is separate from the top-level backgroundMusic object.
​
string
The music for this scene. It plays instead of the video’s music.Use a public link to an audio file, or an audioUrl from Search Music Tracks copied exactly as returned.
  • If the next scene uses the same link, the music keeps playing without starting over.
  • If the track is shorter than the scene, it repeats.
​
number
How loud this scene’s music is, from 0 (silent) to 1 (full volume). Use it only with musicUrl.If you leave it out, the scene uses the video’s music volume. If the video has no music volume, the scene plays at full volume.
​
boolean
Set to false for no music in this scene.Required when you do not set musicUrl. When you set musicUrl, it is true unless you set it to false.
How the music plays
  • All the scene music is joined into one soundtrack for the video.
  • Scenes without their own musicUrl play the video’s music. It continues from where it would have been, as if it had played the whole time.
  • To keep those scenes silent, set the top-level backgroundMusic.enabled to false.
  • When one track changes to another, the music fades over half a second or less.
  • Tracks from Search Music Tracks are licensed for you. If the video uses more than one of them, the youtubeClearanceCode on the render job covers the one that plays the longest.

​
scenes[].avatar Object

Scene-level avatar customization. Overrides global avatar Object settings for this specific scene.
Scene-level settings override global avatar configuration. Any property not specified at the scene level inherits from the global avatar settings.
​
string
Preset position for the avatar in this scene. Options: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right
​
string
Distance from top edge as percentage (e.g., “10%”, “25%”, “50%”). Integer percentages only (0%-100%). Cannot be used with position.
​
string
Distance from left edge as percentage (e.g., “5%”, “50%”, “80%”). Integer percentages only (0%-100%). Cannot be used with position.
​
string
Avatar width as percentage for this scene (e.g., “20%”, “25%”, “30%”). Must be an integer percentage from 0% to 100%.
​
string
Corner rounding for this scene. Options: 0 (square), 50 (rounded), 100 (circular)
​
string
Border color in RGBA format for this scene (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,1)”, “rgba(132,44,254,1)”)
​
number
Border width in pixels for this scene. Minimum: 0
​
string
Background color in RGBA format for this scene (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,0.5)”)
​
boolean
Hide avatar for this specific scene (true or false)
Important: You cannot change avatarId at the scene level. The same avatar must be used throughout the video. You can only override styling and positioning properties.

​
background Object

Background media configuration for a scene.
Background can only have ONE of: visualUrl, color, or aiVisual - not multiple.
The following fields are nested inside the background object, which is a property of each scenes[] element. For example, scenes[].background.visualUrl means visualUrl is a property of background, which itself is nested inside each item of the scenes array.
​
string
URL to background video or image. Cannot be used with color or aiVisual.
​
string
Solid background color in RGB, RGBA, or hex format (e.g., “rgb(0,0,0)”, “rgba(0,0,0,1)”, “#000000”). Cannot be used with visualUrl or aiVisual.
​
object
AI-generated visual configuration. Cannot be used with visualUrl or color. See aiVisual Object.
​
string
Media type. Options: video, image. Required when aiVisual is provided. It determines whether an AI image or AI video clip is generated.
​
object
Search filter for auto-selecting visuals. See searchFilter Object.
​
array
Time clips to use from background video. Only valid when type is video and visualUrl is provided. Each clip has start and end numbers in seconds.
​
object
Background playback settings. See background.settings Object.
​
object
Semi-transparent color tint rendered on top of the background. Works with every background source, including solid colors. See colorOverlay Object and the Background Color Overlay guide.

​
aiVisual Object

AI-generated visual configuration. Use with background.type set to "image" for AI-generated images or "video" for AI-generated video clips.
The following fields are nested inside the aiVisual object, which is a property of scenes[].background. For example, scenes[].background.aiVisual.prompt means prompt is a property of aiVisual, which itself is nested inside background, inside each item of the scenes array.
​
string
Text prompt describing the visual to generate (max 500 characters). If omitted, the system auto-generates a prompt from the scene’s story text. Required when the scene has no content source, because there is no story text to generate a prompt from.When a story is split into multiple scenes (using createSceneOnEndOfSentence or createSceneOnNewLine), this prompt acts as a creative direction for the entire video rather than a prompt for a specific scene. The system uses it to guide the auto-generated prompts for each individual scene, ensuring a consistent visual tone. A good creative direction prompt follows this structure: [Action/Movement] + [Scene/Environment] + [Camera Technique] + [Visual Style]. For example: "Smooth cinematic tracking shots in modern creative workspaces with warm golden-hour lighting and shallow depth of field".A prompt you write for a single scene is sent to the model exactly as written unless you set enhancePrompt to true, send a trainingPreset, or set mediaStyle on an image.
​
string
required
AI model to use. The valid options depend on background.type:Image models (when type is "image"): flux-schnell, seedream3.0, nanobanana, nanobanana-pro, nanobanana2, nanobanana-lite2, nova-canvasVideo models (when type is "video"): pixverse6, pixverse5.6, pixverse5.5, veo3.1_fast, veo3.1, omni-flash
​
string
Visual style for generated images. Only applicable when type is "image". Options: photorealistic, artistic, cartoon, minimalist, vintage, futuristic
​
string
Duration of the generated video clip. Only applicable when type is "video". Valid values depend on the model:
  • pixverse6: "5s", "8s", "10s", "15s" (default: "5s")
  • pixverse5.6, pixverse5.5: "5s", "8s", "10s" (default: "5s")
  • veo3.1_fast, veo3.1: "4s", "6s", "8s" (default: "4s")
  • omni-flash: "10s"
If omitted or invalid, the model’s shortest duration is used. Credits are charged for the generated clip’s duration, even when the scene is shorter and the clip is trimmed to fit. omni-flash always generates 10s, so use it for scenes of about 10 seconds.
​
boolean
When set to true, enables visual continuity between consecutive AI-generated scenes. The system automatically uses the output of the previous scene as a reference for the next scene, creating smooth visual transitions. For video scenes, the last frame of the previous video is used. For image scenes, the generated image of the previous scene is used. This field works with both "video" and "image" types.Visual continuity applies in two scenarios:
  • Within the same story: Consecutive scenes that were split from the same original story use the previous scene’s output as a reference for the next scene.
  • Across consecutive stories: Continuity is also maintained between the last scene of one story and the first scene of the next story, enabling seamless transitions across story boundaries.
In both cases, visualContinuity must be set to true for the system to use the previous scene’s output as a reference. If visualContinuity is not set or is false, the following behavior applies for consecutive scenes from the same story:
  • Image scenes: All user-provided reference images (such as referenceImageUrl) are cleared, and visuals are generated independently.
  • Video scenes: Only firstFrameImageUrl is cleared if it was provided. However, referenceImageUrls are preserved and still used for generation.
This field has no effect on the first scene in a sequence. When continuity is active and the previous scene’s output is unavailable, the system falls back to generating the visual without a reference image.
​
string
URL of an image to use as the first frame of the generated video clip. The AI model generates a video that begins from this image and transitions into the content described in the prompt. Only applicable when type is "video". Cannot be used together with referenceImageUrls.
​
string
URL of an image the clip ends on. Used together with firstFrameImageUrl, it generates a transition from the first image to this one. Only applicable when type is "video", on pixverse6, pixverse5.6 and pixverse5.5. When a story is split into several scenes, only the first scene starts on firstFrameImageUrl, so the end frame is ignored for the scenes after it. With visualContinuity, those scenes instead start on the previous scene’s last frame and transition to the end frame.
​
string
URL of a single reference image to guide the generated image. Only applicable when type is "image". Kept for existing integrations; new integrations can use referenceImageUrls, which accepts several images. Do not send both.
​
string[]
Reference image URLs that guide the generated visual. Cannot be used together with firstFrameImageUrl.
  • Video: up to 4 on pixverse6, pixverse5.6 and pixverse5.5, up to 3 on veo3.1 and veo3.1_fast, and 1 on omni-flash.
  • Image: up to 4 on seedream3.0, nanobanana, nanobanana-pro, nanobanana2 and nanobanana-lite2, and 1 on nova-canvas. flux-schnell does not accept reference images.
When using referenceImageUrls (without firstFrameImageUrl) with the veo3.1 or veo3.1_fast models, the video duration is automatically set to "8s".
​
boolean
Generate sound (effects, ambience, speech) in the clip. Off by default. Supported on pixverse6, pixverse5.6, veo3.1 and veo3.1_fast, billed at the model’s with-audio rate. omni-flash always generates audio, so audio: false is rejected for it. Only applicable when type is "video". The clip’s audio plays in the video alongside any voice-over and background music you configure. To keep it silent, set scenes[].background.settings.mute to true.
​
string
Steers the visual toward a training-content use case: sales-training, product-training or soft-skills-training. Applies to both auto-generated and written prompts. The preset is applied by the prompt enhancer, so on a written prompt it always turns enhancement on, even when enhancePrompt is false.
​
boolean
Whether a prompt you wrote is rewritten by Pictory’s AI enhancer before generation. Off by default: your prompt is sent as written. A trainingPreset always turns it on. mediaStyle on images also turns it on, unless you set enhancePrompt: false. Scenes without a prompt are unaffected: their prompt is generated from the scene text.
​
string
Output resolution of the generated video clip: "1080p" (default) or "720p". Models deliver the highest resolution they support up to this value: omni-flash is always 720p, pixverse6 at 15s is 720p, and Veo is 1080p at 8s only. Only applicable when type is "video".

​
Reference Image Fields: Quick Reference

Mutual exclusivity rules:
  • firstFrameImageUrl and referenceImageUrls cannot be provided together. Use one or the other.
  • referenceImageUrl is only for image generation, and cannot be sent together with referenceImageUrls.
  • firstFrameImageUrl and endFrameImageUrl are only for video generation.

​
Image Models: AI Credit Cost

​
Video Models: AI Credit Cost

Credits are charged per second of video generated.
For detailed guides on configuring AI-generated visuals, see:

​
searchFilter Object

The following fields are nested inside the searchFilter object, which is a property of scenes[].background. For example, scenes[].background.searchFilter.category means category is a property of searchFilter, which itself is nested inside background, inside each item of the scenes array.
​
string
Category filter for media search. See Visual Filter Categories.
​
string
Custom search query to find relevant visuals for your scene (max 3000 characters). Use descriptive terms to get more accurate background media results (e.g., “business team collaborating in modern office”, “aerial view of city skyline at sunset”).
​
array
Keywords for search (max 10, each 2-100 characters).
​
array
Media libraries to search. Options: story_blocks, getty

​
background.settings Object

The following fields are nested inside the settings object, which is a property of scenes[].background. For example, scenes[].background.settings.mute means mute is a property of settings, which itself is nested inside background, inside each item of the scenes array.
​
boolean
Mute audio from background media. Background videos are muted by default, except an AI-generated clip made with audio (aiVisual.audio, or omni-flash), which plays its audio unless this is true.
​
boolean
Loop the background media.
​
boolean
Apply zoom and pan effects. Cannot be used with kenBurnsEffect.
​
boolean
Apply Ken Burns effect (images only). Cannot be used with zoomAndPan.

​
colorOverlay Object

A semi-transparent color tint rendered on top of the background, commonly used to keep subtitles readable on busy footage or to apply a brand color across scenes. The underlying media is not modified.
The following fields are nested inside the colorOverlay object, which is a property of scenes[].background. For example, scenes[].background.colorOverlay.color means color is a property of colorOverlay, which itself is nested inside background, inside each item of the scenes array.
​
string
required
The tint color in RGB, RGBA, or hex format. If an RGBA value is provided, its alpha channel is ignored; transparency is controlled only by opacity.
​
number
default:"0.4"
Tint strength from 0 (invisible) to 1 (solid). Defaults to 0.4.
colorOverlay is also supported on each backgroundBrolls[] item (a B-roll’s own overlay takes precedence while it is on screen) and on video/image items in the scene elements Array. Scenes using colorOverlay are processed by the v3 storyboard engine automatically.

​
Visual Filter Categories

Aerial: Aerial, Aerial/Coastal_and_Marine, Aerial/Infrastructure, Aerial/Natural_Landscapes, Aerial/Urban_LandscapesAnimals: Animals, Animals/Farm_Animals, Animals/Marine_Life, Animals/Pets, Animals/WildlifeBusiness: Business_and_Professions, Business_and_Professions/Business_Concepts, Business_and_Professions/Office_Work, Business_and_Professions/ProfessionsEffects: Effects, Effects/Chemical_Reactions, Effects/Explosions, Effects/Fire_and_Smoke, Effects/Glitches, Effects/Lighting_Effects, Effects/ParticlesFood: Food_and_Beverage, Food_and_Beverage/Beverages, Food_and_Beverage/Food_Preparation, Food_and_Beverage/MealsGraphics: Graphics, Graphics/Backgrounds, Graphics/Effects, Graphics/PatternsHistorical: Historical, Historical/Eras, Historical/Events, Historical/FiguresHolidays: Holidays_and_Celebrations, Holidays_and_Celebrations/Cultural_Celebrations, Holidays_and_Celebrations/Festivals, Holidays_and_Celebrations/Life_EventsLifestyle: Lifestyle, Lifestyle/Health_and_Fitness, Lifestyle/Hobbies, Lifestyle/Home_and_FamilyMedical: MedicalNature: Nature, Nature/Landscapes, Nature/Plants_and_Trees, Nature/Sunrises_and_Sunsets, Nature/Waterfalls, Nature/WeatherPeople: People, People/Activities, People/Groups, People/PortraitsPlaces: Places_and_Landmarks, Places_and_Landmarks/Rural_Areas, Places_and_Landmarks/Tourist_Attractions, Places_and_Landmarks/Urban_AreasSports: Sports_and_Recreation, Sports_and_Recreation/Individual_Sports, Sports_and_Recreation/Outdoor_Activities, Sports_and_Recreation/Team_SportsTechnology: Technology, Technology/Devices, Technology/Innovation

​
backgroundBrolls Array

Array of B-roll background configurations for creating dynamic scene transitions.
Each B-roll item supports all background Object properties plus:
The following fields are nested inside each element of the scenes[].backgroundBrolls array. For example, scenes[].backgroundBrolls[].brollClip means brollClip is a property of each item in the backgroundBrolls array, which itself is nested inside each item of the scenes array.
​
object
Time clip configuration for B-roll. Contains start (number, required) and end (number, required) in seconds.

​
backgroundCorpus Array

Array of background images to use as a corpus for the scene (max 100 items).
The following fields are nested inside each element of the scenes[].backgroundCorpus array. For example, scenes[].backgroundCorpus[].visualUrl means visualUrl is a property of each item in the backgroundCorpus array, which itself is nested inside each item of the scenes array.
​
string
URL to background image.
​
string
Must be image.
​
boolean
Mark as preferred image for selection.

​
elements Array

Overlay elements placed on top of the scene background (max 20 per scene). Four element types are supported: shape and text (see the Scene Elements guide) and video and image (see the Media Elements guide).
The following fields are nested inside each item of the scenes[].elements array. Fields marked “media only” apply to video and image elements; fields marked “shape only” or “text only” apply to those types.
​
string
required
Element type. Options: shape, text, video, image.
​
string
Shape only (required). Shape name, e.g. rectangle, circle, badge-3. See the shape gallery.
​
string
Shape only. Fill color in RGB, RGBA, or hex format. Omit it to keep a library shape’s own colors.
​
string
Shape only. Outline color in RGB, RGBA, or hex format.
​
number
Shape only. Outline thickness in pixels.
​
number
Shape only. Corner radius in pixels. Applies to the rectangle shape only.
​
string
Shape only, and only for the rectangle, circle and line shapes. Element height as a percentage of the canvas, e.g. "6%". With width it sets the box the shape is drawn to, so a rectangle can be a bar or a panel of any proportions and a circle becomes an ellipse. Without height these shapes keep their default proportions (a rectangle is a square). Every other shape keeps its own proportions and rejects height.
​
string
Text only (required). The text to display (max 2000 characters).
​
string
Text only. Decorative preset that seeds the font size, position, and width: heading (66 pt, centered, 90% width), subheading (42 pt, top center, 90% width), or body (20 pt, centered, 37% width). Defaults to body. Any value can be overridden with style or position.
​
object
Text only. Inline text style: font, size, color, background color, alignment, case, decorations, and up to two animations (one entry, one exit). Same fields as the subtitleStyle Object. Cannot be combined with styleId or styleName.
​
string
Text only. Apply a saved text style by ID. Retrieve IDs from Get Text Styles. Cannot be combined with styleName.
​
string
Text only. Apply a saved text style by name. Retrieve names from Get Text Styles. Cannot be combined with styleId.
​
string
Media only. URL of the video or image file to overlay. Exactly one of visualUrl, searchFilter, or aiVisual is required for media elements. A preview.url returned by Search Videos and Images is a valid value: pass it exactly as returned, query string included, and Pictory licenses the stock clip at render time.
​
object
Media only. Stock library search. Contains a single required field query (string): what to search for, in plain language. If no match is found, the element is skipped and the request still succeeds.
​
object
Media only. Generate the element with AI. Same fields as scenes[].background.aiVisual except visualContinuity: prompt, model (required), mediaStyle, videoDuration, firstFrameImageUrl, endFrameImageUrl, referenceImageUrl, referenceImageUrls, audio, trainingPreset, enhancePrompt, resolution. Consumes AI Credits according to the selected model’s rate. If credits are insufficient or generation fails, the element is skipped. Video elements are muted by default, except a clip generated with audio (audio: true, or omni-flash), which plays its audio unless settings.mute is true.
​
object
Video elements only. Playback settings: loop (boolean, default true) and mute (boolean, default true, or false for an AI-generated clip made with audio).
​
object
Media only. Color tint applied to this element, with the same fields as the background colorOverlay Object: color (required) and opacity (default 0.4).
​
string
Anchor preset: top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right. Cannot be combined with top/left.
​
string
Vertical offset as a percentage from the top, e.g. "10%". Cannot be combined with position.
​
string
Horizontal offset as a percentage from the left, e.g. "10%". Cannot be combined with position.
​
string
Element width as a percentage of the canvas, e.g. "30%". For media elements, omitting width enables automatic sizing: the element starts at 30% of the canvas and shrinks so it stays fully on screen given its position and aspect ratio.

​
transcript Array

Transcription of input video or audio content.
The following fields are nested inside the scenes[].transcript array. For example, scenes[].transcript[].speakerId means speakerId is a property of each item in the transcript array, which itself is nested inside each item of the scenes array. Fields like scenes[].transcript[].words[].word go one level deeper: word is inside each item of the words array, which is inside each transcript element.
​
integer
Speaker identifier.
​
array
required
Array of word objects.
​
string
required
The word text.
​
number
required
Start time in seconds (min 0).
​
number
required
End time in seconds (must be >= start_time).
​
boolean
Whether this is a pause.
​
boolean
Whether this is a filler word.
​
integer
Speaker identifier for this word.

​
mediaRepurposeSettings Object

Settings for repurposing audio or video content.
The following fields are nested inside the mediaRepurposeSettings object, which is a property of each scenes[] element. For example, scenes[].mediaRepurposeSettings.highlightLength means highlightLength is a property of mediaRepurposeSettings, which itself is nested inside each item of the scenes array.
​
number
Length of highlight in seconds (5-180).
​
boolean
Remove filler words from the content.
​
boolean
Remove silences from the content.
​
number
Silence threshold in seconds (0-10).

​
templateOverride Object

Configuration for manipulating template scenes. Only available when templateId is provided.
The following fields are nested inside the templateOverride object, which is a property of each scenes[] element. For example, scenes[].templateOverride.sceneId means sceneId is a property of templateOverride, which itself is nested inside each item of the scenes array.
​
string
ID of the existing scene to modify. Cannot be used with scenePosition.
​
number
Position of the existing scene to modify (1-based). Cannot be used with sceneId.
​
number
New position for a newly inserted scene (1-based). Only for new scenes.
​
string
Insert new scene after this scene ID. Only for new scenes. Cannot be used with newScenePosition.
​
string
Insert new scene before this scene ID. Only for new scenes. Cannot be used with newScenePosition or insertAfterSceneId.
​
string
Replace the scene with this ID. Only for new scenes. Cannot be used with newScenePosition.
​
number
Replace the scene at this position (1-based). Only for new scenes. Cannot be used with newScenePosition or replaceSceneId.
​
string
Base scene ID to copy settings from. Only for new scenes.
​
number
Base scene position to copy settings from (1-based). Only for new scenes. Cannot be used with baseSceneId.
​
boolean
Delete this scene. Only for existing scenes.
​
boolean
Copy this scene. Only for existing scenes.
​
array
Array of subtitle configurations (max 500). Only for existing scenes. See templateOverride.subtitles Array.
​
array
Array of layer configurations (max 500). Only for existing scenes. See templateOverride.layers Array.
Template Override Rules:
  • templateOverride is only available when templateId is provided
  • Use sceneId OR scenePosition to identify existing scenes, not both
  • Properties like newScenePosition, insertAfterSceneId, insertBeforeSceneId, replaceSceneId, baseSceneId are only for new scenes
  • Properties like deleteScene, copyScene, subtitles, layers are only for existing scenes

​
templateOverride.subtitles Array

The following fields are nested inside each element of the scenes[].templateOverride.subtitles array. For example, scenes[].templateOverride.subtitles[].text means text is a property of each item in the subtitles array, which itself is nested inside templateOverride, inside each item of the scenes array.
​
string
required
Subtitle text (1-40000 characters).
​
number
Minimum duration in seconds.
​
string
ID of saved text style.
​
string
Name of saved text style.
​
object
Inline style configuration. See subtitleStyle Object.

​
templateOverride.layers Array

Layers allow you to customize text, image, and video elements within template scenes.
The following fields are nested inside the scenes[].templateOverride.layers structure, which is an array of arrays. The [][] notation indicates that layers is an array of arrays: the outer [] represents each subtitle group, and the inner [] represents each layer element within that group. For example, scenes[].templateOverride.layers[][].layerId means layerId is a property of each layer element inside the nested array structure.
​
string
ID of the layer to modify (max 100 characters).
​
string
Layer type. Options: text, image, video
​
string
Text content (max 40000 characters). For text type only.
​
string
Media URL. For image or video type only.
​
string
Text style ID. For text type only.
​
string
Text style name. For text type only.
​
object
Inline text style. See subtitleStyle Object. For text type only.
​
boolean
Delete this layer.

​
Response

When the storyboard request is successfully submitted, a job is created and a job ID is returned. Use this job ID to poll the Get Storyboard Preview Job by ID endpoint for the completed storyboard preview.
​
boolean
Indicates whether the request was successful
​
object
Contains the storyboard job information
​
string
Unique identifier for the storyboard preview job. Use this to track the job status and retrieve results via the Get Storyboard Preview Job by ID endpoint.

​
Next Steps

Once you have the jobId, poll the Get Storyboard Preview Job by ID endpoint to check the job status and retrieve the completed storyboard preview. Use a polling interval of 10–30 seconds. When the job completes, you will receive:
  • renderParams: The rendering data for the video. To customize the video, update this data and use the Render Video API to render with your modifications. To update the preview with changes, save the updated data using the Update Storyboard Elements API.
  • storyboard: The processed input storyboard. If you want to change anything in the original storyboard request, use this processed response to make a new request with updates; it will process faster since the storyboard is already broken down into scenes, voices, and other components.
  • previewUrl: The preview URL for the video storyboard. Use this to view the preview in a browser or embed it in an iframe for app integrations. See the Embed Preview Player guide for details.

​
Code Examples

Replace YOUR_API_KEY with your actual API key

​
Basic Text to Video Preview

​
Preview with Smart Layout

​
Preview with AI Story Generation

​
Preview with AI Storyboard (Designed Scenes)

​
Preview with AI Storyboard from a Brief

​
Preview with AI-Generated Background Image

​
Preview with AI-Generated Background Video Clip

​
Error Handling

Solution: Ensure videoName and scenes are provided.
Solution: Each scene can only have one content source.
Solution: With aiStoryboard enabled, use story, brief, or blogUrl scenes and remove the field named in the message (or remove aiStoryboard to create a standard storyboard). See aiStoryboard Object for the full list.
Solution: Remove maxSubtitleLines when using smart layouts.
Solution: Check your API key is valid and correctly formatted in the Authorization header.
Solution: Implement exponential backoff and space out requests.

AI-Generated Background Images

Generate AI images as scene backgrounds

AI-Generated Background Video Clips

Generate AI video clips as scene backgrounds

AI Voice-Over

Add professional AI narration

Smart Layouts

Apply professional visual layouts

AI Brief to Video

Generate scripts with AI

Background Music

Add music to your videos

Brand Settings

Apply consistent branding

Subtitle Styles

Customize caption formatting

​
Next Steps

After creating your storyboard preview:

Check Preview Status

Monitor preview generation progress and retrieve results

Render Final Video

Convert approved preview into final video file

Update Project

Modify scenes or settings before rendering

Get Project Details

Retrieve full project information

​
Supporting APIs

Get Voiceover Tracks

List available AI voices for your preview

Get Text Styles

View saved subtitle styles

Get Video Brands

List available brands

Search Media

Find stock visuals for your scenes