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

Workflow	API	When to Use
Create Preview	This API	Generate preview to review scenes before rendering
Render from Preview	Render from Preview	Render preview as-is without modifications
Render with Modifications	Render Video	Modify preview elements before rendering
Render Saved Project	Render Project	Render existing project created in App or via API
Direct Render	Render Storyboard Video	Skip preview, render directly from input

Preview vs. Final Render

Aspect	Storyboard Preview	Final Render
Purpose	Review and validate content	Produce final video file
Output	Scene thumbnails, metadata, project structure	Full HD video file
Speed	Fast	Slower
Cost	Lower resource usage	Full rendering resources
Editable	Yes, make changes before render	Video is final
Use Case	Content approval, iteration	Final delivery

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

API Endpoint

POST https://api.pictory.ai/pictoryapis/v2/video/storyboard

Request Headers

Authorization

string

required

API key for authentication

Authorization: YOUR_API_KEY

Content-Type

string

required

Must be application/json

Request Body Parameters

videoName

string

required

Name for your video project (alphanumeric, spaces, underscores, and hyphens only, max 150 characters)

videoWidth

integer

Width of the generated video in pixels. Must be provided together with videoHeight.

videoHeight

integer

Height of the generated video in pixels. Must be provided together with videoWidth.

aspectRatio

string

Video aspect ratio. Options: 1:1, 16:9, 9:16, 4:5

language

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

saveProject

boolean

Whether to save the project in your Pictory account for later editing. Default: false

webhook

string

URL where the completed storyboard preview output will be sent via POST request when finished (max 500 characters)

webhookInput

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.

{
  "webhookInput": {
    "internalId": "abc-123",
    "source": "campaign-builder"
  }
}

templateId

string

ID of a template to use. Get from Get Templates API.

variables

object

Key-value object for template variables. Only applicable when templateId is provided.

{
  "variables": {
    "headline": "Welcome to Our Product",
    "subheadline": "Discover Amazing Features",
    "ctaText": "Learn More"
  }
}

brandId

string

ID of the brand to apply. Get from Get Video Brands API. Cannot be used with brandName.

brandName

string

Name of the brand to apply. Cannot be used with brandId.

smartLayoutName

string

Name of the smart layout to apply. Get available layouts from Get Smart Layouts API. Cannot be used with smartLayoutId.

smartLayoutId

string

ID of the smart layout to apply. Get from Get Smart Layouts API. Cannot be used with smartLayoutName.

storyboardVersion

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

subtitleStyleId

string

ID of a saved text style for subtitles. Get from Get Text Styles API. Cannot be used with subtitleStyleName.

subtitleStyleName

string

Name of a saved text style for subtitles. Cannot be used with subtitleStyleId.

subtitleStyle

object

Inline subtitle style configuration. See subtitleStyle Object.

awsConnectionId

string

AWS connection ID for accessing private S3 assets. Get from Get AWS Connections API.

vimeoConnectionId

string

Vimeo connection ID for uploading videos directly to Vimeo. Get from Get Vimeo Connections API.

destinations

array

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

voiceOver

object

Voice-over configuration for AI narration. See voiceOver Object.

backgroundMusic

object

Background music configuration for the video. See backgroundMusic Object.

logo

object

Logo overlay configuration. See logo Object.

scenes

array

required

Array of scene objects containing the content to convert into video. Required unless using templateId. See scenes Array.

avatar

object

AI avatar configuration for presenter-style videos. See avatar Object.

voiceOver Object

Voice-over configuration for AI narration.

{
  "voiceOver": {
    "enabled": true,
    "aiVoices": [
      {
        "speaker": "Brian",
        "speed": 100,
        "amplificationLevel": 0
      }
    ]
  }
}

The following fields are nested inside the top-level voiceOver object. For example, voiceOver.enabled means enabled is a property of the voiceOver object.

voiceOver.enabled

boolean

required

Enable or disable voice-over.

voiceOver.aiVoices

array

Array of AI voice configurations (max 10). See aiVoices Array.

voiceOver.externalVoice

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.

voiceOver.aiVoices[].speaker

string

required

Voice speaker name (e.g., “Brian”, “Emma”). Get available voices from Get Voiceover Tracks API.

voiceOver.aiVoices[].speed

number

Speech speed from 50 to 200. Default: 100

voiceOver.aiVoices[].amplificationLevel

number

Volume level from -1 to 1. Default: 0

voiceOver.aiVoices[].premiumVoiceSettings

object

ElevenLabs premium voice settings. See premiumVoiceSettings Object.

premiumVoiceSettings Object

{
  "premiumVoiceSettings": {
    "modelId": "eleven_multilingual_v2",
    "stability": "50%",
    "similarityBoost": "75%",
    "style": "50%",
    "useSpeakerBoost": true
  }
}

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.

voiceOver.aiVoices[].premiumVoiceSettings.modelId

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

voiceOver.aiVoices[].premiumVoiceSettings.stability

string

Voice stability as percentage (e.g., “50%”)

voiceOver.aiVoices[].premiumVoiceSettings.useSpeakerBoost

boolean

Enable speaker boost enhancement.

voiceOver.aiVoices[].premiumVoiceSettings.similarityBoost

string

Similarity boost as percentage (e.g., “75%”)

voiceOver.aiVoices[].premiumVoiceSettings.style

string

Voice style as percentage (e.g., “50%“)

externalVoice Object

{
  "externalVoice": {
    "voiceUrl": "https://example.com/voiceover.mp3",
    "syncVoice": true,
    "amplificationLevel": 0
  }
}

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.

voiceOver.externalVoice.voiceUrl

string

required

URL to external voice audio file.

voiceOver.externalVoice.syncVoice

boolean

Auto-synchronize voice with video subtitles.

voiceOver.externalVoice.amplificationLevel

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.

avatar.avatarId

string

required

Unique identifier for the avatar look (e.g., “Annie_expressive12_public”). Get from Get Avatars API.

avatar.position

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

avatar.width

string

Avatar width as percentage (e.g., “20%”, “25%”, “30%”). Must be an integer percentage from 0% to 100%.Default: "20%"

avatar.borderRadius

string

Corner rounding. Options: 0 (square), 50 (rounded), 100 (circular)

avatar.borderColor

string

Border color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,1)”, “rgba(132,44,254,1)”)

avatar.borderThickness

number

Border width in pixels. Minimum: 0

avatar.backgroundColor

string

Background color in RGBA format (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,0.5)”)

avatar.hide

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.

{
  "backgroundMusic": {
    "enabled": true,
    "autoMusic": true,
    "volume": 0.5
  }
}

The following fields are nested inside the top-level backgroundMusic object. For example, backgroundMusic.enabled means enabled is a property of the backgroundMusic object.

backgroundMusic.enabled

boolean

required

Enable or disable background music.

backgroundMusic.autoMusic

boolean

Auto-select background music. Cannot be used with musicUrl.

backgroundMusic.musicUrl

string

URL to custom background music file. Cannot be used with autoMusic.

backgroundMusic.volume

number

Volume level from 0 to 1. Default: 0.5

backgroundMusic.clips

array

Time clips to use from the music (max 10). Each clip has start and end numbers in seconds.

{
  "clips": [
    { "start": 0, "end": 30 },
    { "start": 60, "end": 90 }
  ]
}

logo Object

Logo overlay configuration.

{
  "logo": {
    "url": "https://example.com/logo.png",
    "position": "top-right",
    "width": "15%"
  }
}

The following fields are nested inside the top-level logo object. For example, logo.url means url is a property of the logo object.

logo.url

string

required

URL to logo image file.

logo.position

string

Logo position. Options: top-left, top-right, top-center, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right

logo.width

string

Logo width as percentage (e.g., “15%“)

subtitleStyle Object

Inline subtitle style configuration. Can be used at video level or scene level.

{
  "subtitleStyle": {
    "fontFamily": "Montserrat",
    "fontSize": 48,
    "color": "rgba(255,255,255,1)",
    "position": "bottom-center",
    "alignment": "center"
  }
}

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.

subtitleStyle.fontUrl

string

URL to custom font file. When provided, fontFamily is required.

subtitleStyle.fontFamily

string

Font family name. Required when fontUrl is provided. See Supported Font Families.

subtitleStyle.fontSize

integer

Font size in pixels. Minimum: 1

subtitleStyle.color

string

Text color in RGBA format (e.g., “rgba(255,255,255,1)”)

subtitleStyle.backgroundColor

string

Background color in RGBA format (e.g., “rgba(0,0,0,0.5)”).

subtitleStyle.shadowColor

string

Shadow color.

subtitleStyle.shadowWidth

string

Shadow width as percentage (e.g., “10%”)

subtitleStyle.keywordColor

string

Color for highlighted keywords in RGBA format (e.g., “rgba(255,255,0,1)”).

subtitleStyle.position

string

Text position. Options: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right

subtitleStyle.alignment

string

Text alignment. Options: left, center, right

subtitleStyle.decorations

array

Text decorations. Options: bold, underline, italics, linethrough

{
  "decorations": ["bold", "italics"]
}

subtitleStyle.case

string

Text case. Options: uppercase, lowercase, capitalize, smallcapitalize

subtitleStyle.paragraphWidth

string

Paragraph width as percentage (e.g., “80%”)

subtitleStyle.animations

array

Text animations (max 2: one entry, one exit). See animations Array.

{
  "animations": [
    {
      "name": "fade",
      "type": "entry",
      "speed": "fast",
      "futureWords": "hidden"
    },
    {
      "name": "fade",
      "type": "exit",
      "speed": "fast"
    }
  ]
}

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.

subtitleStyle.animations[].name

string

required

Animation name. Options: none, fade, drift, wipe, text reveal, elastic, typewriter, blur, bulletin

subtitleStyle.animations[].type

string

required

Animation type. Options: entry, exit

subtitleStyle.animations[].speed

string

required

Animation speed. Options: slow, medium, fast, custom

subtitleStyle.animations[].customSpeedValue

number

Custom speed value (min 0.5). Required when speed is custom.

subtitleStyle.animations[].direction

string

Animation direction. Options: up, down, left, right

subtitleStyle.animations[].writingStyle

string

Writing style for text animations. Options: character, word, line, paragraph

subtitleStyle.animations[].futureWords

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

{
  "destinations": [
    {
      "type": "vimeo",
      "folder_uri": "/users/12345/projects/67890",
      "content_rating": ["safe"],
      "privacy": {
        "view": "unlisted",
        "embed": "public",
        "download": false
      }
    }
  ]
}

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.

destinations[].type

string

required

Must be vimeo

destinations[].folder_uri

string

Vimeo folder URI.

destinations[].content_rating

array

Content rating. Options: violence, drugs, language, nudity, advertisement, safe, unrated

{
  "content_rating": ["safe"]
}

destinations[].privacy

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.

destinations[].privacy.view

string

View access. Options: anybody, contacts, disable, nobody, password, unlisted, users

destinations[].privacy.embed

string

Embed access. Options: private, public, whitelist

destinations[].privacy.comments

string

Comment access. Options: anybody, contacts, nobody

destinations[].privacy.add

boolean

Allow adding to albums/channels.

destinations[].privacy.download

boolean

Allow downloads.

scenes Array

Each scene in the scenes array can contain various content sources and settings.

{
  "scenes": [
    {
      "story": "Welcome to our product showcase. Discover amazing features.",
      "createSceneOnEndOfSentence": true,
      "highlightKeywords": true,
      "sceneTransition": "fade",
      "background": {
        "visualUrl": "https://example.com/background.mp4",
        "type": "video",
        "settings": {
          "mute": true,
          "loop": true
        }
      }
    }
  ]
}

Each scene can only have ONE content source. Choose one of: story, storyCoPilot, blogUrl, pptUrl, audioUrl, or videoUrl.

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.

scenes[].story

string

Text content for creating video from text (max 15000 characters).

scenes[].storyCoPilot

object

AI story generation configuration. See storyCoPilot Object.

scenes[].blogUrl

string

URL to blog/article content.

scenes[].pptUrl

string

URL to PowerPoint presentation file.

scenes[].audioUrl

string

URL to audio file for audio-to-video conversion. Requires audioLanguage.

scenes[].videoUrl

string

URL to video file for video repurposing. Requires audioLanguage.

scenes[].createSceneOnNewLine

boolean

Create new scene on each new line. Default: false

scenes[].createSceneOnEndOfSentence

boolean

Create new scene at end of each sentence. Default: false

scenes[].maxSubtitleLines

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.

scenes[].highlightKeywords

boolean

Highlight keywords in subtitles.

scenes[].hideSubtitles

boolean

Hide subtitles for this scene.

scenes[].minimumDuration

number

Minimum duration for the scene in seconds.

scenes[].endPauseDuration

number

Pause duration at the end of the scene in seconds.

scenes[].sceneTransition

string

Transition effect. Options: none, wipeup, wipedown, wipeleft, wiperight, smoothleft, smoothright, radial, circlecrop, hblur, fade

scenes[].audioLanguage

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)

scenes[].useSpeakerNotes

boolean

Use speaker notes from PowerPoint. Only valid with pptUrl.

scenes[].isSSMLStory

boolean

Whether story text contains SSML markup. Only valid with story. Default: false

scenes[].caption

string

Separate caption text for the scene (max 3000 characters). Requires story.

scenes[].captionLanguage

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

scenes[].subtitleStyleId

string

ID of a saved text style for this scene’s subtitles. Cannot be used with subtitleStyleName.

scenes[].subtitleStyleName

string

Name of a saved text style for this scene’s subtitles. Cannot be used with subtitleStyleId.

scenes[].subtitleStyle

object

Inline subtitle style for this scene. Overrides video-level subtitle style. See subtitleStyle Object.

scenes[].voiceOver

object

Voice-over configuration specific to this scene. Overrides video-level settings. See scenes[].voiceOver Object.

scenes[].backgroundMusic

object

Background music configuration specific to this scene. See scenes[].backgroundMusic Object.

scenes[].avatar

object

Avatar customization specific to this scene. Overrides global avatar settings. See scenes[].avatar Object.

scenes[].background

object

Background media configuration for this scene. See background Object.

scenes[].backgroundBrolls

array

Array of B-roll background configurations. See backgroundBrolls Array.

scenes[].backgroundCorpus

array

Array of background images to use as a corpus (max 100). See backgroundCorpus Array.

scenes[].transcript

array

Transcription of input video or audio. Required when repurposing audioUrl or videoUrl. See transcript Array.

scenes[].mediaRepurposeSettings

object

Settings for repurposing media content. Only valid with audioUrl or videoUrl. See mediaRepurposeSettings Object.

scenes[].templateOverride

object

Configuration for manipulating template scenes. Only available when templateId is provided. See templateOverride Object.

storyCoPilot Object

AI story generation configuration for creating video scripts automatically.

{
  "storyCoPilot": {
    "prompt": "How AI is transforming video creation",
    "videoType": "Explainer",
    "duration": 60,
    "platform": "YouTube",
    "tone": "informative"
  }
}

The following fields are nested inside the storyCoPilot object, which is a property of each scenes[] element. For example, scenes[].storyCoPilot.prompt means prompt is a property of storyCoPilot, which itself is nested inside each item of the scenes array.

scenes[].storyCoPilot.prompt

string

required

Topic or description for AI to generate content (1-5000 characters).

scenes[].storyCoPilot.videoType

string

Type of video to generate. Options: Explainer, Marketing, Internal Communication, Tutorial, Product. Default: Explainer

scenes[].storyCoPilot.duration

integer

Target duration in seconds (1-600).

scenes[].storyCoPilot.platform

string

Target platform. Options: YouTube, TikTok, Instagram, Facebook, LinkedIn, Twitter

scenes[].storyCoPilot.tone

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.

{
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Emma", "speed": 100 }]
  }
}

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.

scenes[].voiceOver.enabled

boolean

required

Enable or disable voice-over for this scene.

scenes[].voiceOver.aiVoices

array

Array of AI voice configurations (max 10). Same structure as aiVoices Array.

scenes[].voiceOver.externalVoice

object

External voice configuration with voiceUrl, clips array, and amplificationLevel.

scenes[].backgroundMusic Object

Background music configuration specific to a scene.

{
  "backgroundMusic": {
    "enabled": true
  }
}

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.

scenes[].backgroundMusic.enabled

boolean

required

Enable or disable background music for this scene.

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.

{
  "avatar": {
    "position": "top-left",
    "width": "25%",
    "hide": false
  }
}

scenes[].avatar.position

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

scenes[].avatar.top

string

Distance from top edge as percentage (e.g., “10%”, “25%”, “50%”). Integer percentages only (0%-100%). Cannot be used with position.

scenes[].avatar.left

string

Distance from left edge as percentage (e.g., “5%”, “50%”, “80%”). Integer percentages only (0%-100%). Cannot be used with position.

scenes[].avatar.width

string

Avatar width as percentage for this scene (e.g., “20%”, “25%”, “30%”). Must be an integer percentage from 0% to 100%.

scenes[].avatar.borderRadius

string

Corner rounding for this scene. Options: 0 (square), 50 (rounded), 100 (circular)

scenes[].avatar.borderColor

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)”)

scenes[].avatar.borderThickness

number

Border width in pixels for this scene. Minimum: 0

scenes[].avatar.backgroundColor

string

Background color in RGBA format for this scene (e.g., “rgba(255,255,255,1)”, “rgba(0,0,0,0.5)”)

scenes[].avatar.hide

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": {
    "visualUrl": "https://example.com/video.mp4",
    "type": "video",
    "settings": {
      "mute": true,
      "loop": true
    }
  }
}

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.

scenes[].background.visualUrl

string

URL to background video or image. Cannot be used with color or aiVisual.

scenes[].background.color

string

Solid background color in RGBA format (e.g., “rgba(0,0,0,1)”). Cannot be used with visualUrl or aiVisual.

scenes[].background.aiVisual

object

AI-generated visual configuration. Cannot be used with visualUrl or color. See aiVisual Object.

scenes[].background.type

string

Media type. Options: video, image. Required when aiVisual is provided — determines whether an AI image or AI video clip is generated.

scenes[].background.searchFilter

object

Search filter for auto-selecting visuals. See searchFilter Object.

scenes[].background.clips

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.

{
  "clips": [
    { "start": 0, "end": 10 },
    { "start": 20, "end": 35 }
  ]
}

scenes[].background.settings

object

Background playback settings. See background.settings Object.

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.

AI Image Example
AI Video Clip Example
Video with First Frame
Image with Reference
Visual Continuity

{
  "background": {
    "type": "image",
    "aiVisual": {
      "prompt": "A serene mountain landscape at sunset",
      "model": "seedream3.0",
      "mediaStyle": "photorealistic"
    }
  }
}

{
  "background": {
    "type": "video",
    "aiVisual": {
      "prompt": "Aerial drone shot slowly flying over a tropical coastline",
      "model": "pixverse5.5",
      "videoDuration": "8s"
    }
  }
}

{
  "background": {
    "type": "video",
    "aiVisual": {
      "prompt": "A car driving through a desert highway at golden hour",
      "model": "pixverse5.5",
      "videoDuration": "8s",
      "firstFrameImageUrl": "https://example.com/car-on-highway.jpg"
    }
  }
}

{
  "background": {
    "type": "image",
    "aiVisual": {
      "prompt": "A modern office workspace with natural lighting",
      "model": "seedream3.0",
      "mediaStyle": "photorealistic",
      "referenceImageUrl": "https://example.com/office-reference.jpg"
    }
  }
}

{
  "scenes": [
    {
      "story": "AI is poised to significantly impact educators and course creators on social media. By automating tasks like content generation, visual design, and video editing, AI will save time and enhance consistency. This allows creators to focus on higher-level strategies and ensures a cohesive brand presence.",
      "createSceneOnNewLine": true,
      "createSceneOnEndOfSentence": true
      "background": {
        "type": "video",
        "aiVisual": {
          "model": "pixverse5.5",
          "visualContinuity": true
        }
      }
    }
  ]
}

scenes[].background.aiVisual.prompt

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.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"

scenes[].background.aiVisual.model

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-proVideo models (when type is "video"): pixverse5.5, veo3.1_fast, veo3.1

scenes[].background.aiVisual.mediaStyle

string

Visual style for generated images. Only applicable when type is "image". Options: photorealistic, artistic, cartoon, minimalist, vintage, futuristic

scenes[].background.aiVisual.videoDuration

string

Duration of the generated video clip. Only applicable when type is "video". Valid values depend on the model:

pixverse5.5: "5s", "8s", "10s" (default: "5s")
veo3.1_fast: "4s", "6s", "8s" (default: "4s")
veo3.1: "4s", "6s", "8s" (default: "4s")

If omitted or invalid, the model’s shortest duration is used.

scenes[].background.aiVisual.visualContinuity

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.

scenes[].background.aiVisual.firstFrameImageUrl

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.

scenes[].background.aiVisual.referenceImageUrl

string

URL of a reference image to guide the style and composition of the generated image. Only applicable when type is "image". For video generation, use firstFrameImageUrl or referenceImageUrls instead.

scenes[].background.aiVisual.referenceImageUrls

string[]

An array of 1–2 reference image URLs to guide the style and composition of the generated video clip. Only applicable when type is "video". Cannot be used together with firstFrameImageUrl. For image generation, use referenceImageUrl instead.

When using referenceImageUrls (without firstFrameImageUrl) with the veo3.1 or veo3.1_fast models, the video duration is automatically set to "8s".

Reference Image Fields — Quick Reference

Field	Applicable Type	Description
`firstFrameImageUrl`	`"video"` only	Image used as the starting frame of the generated video
`referenceImageUrl`	`"image"` only	Single reference image for AI image generation
`referenceImageUrls`	`"video"` only	1–2 reference images for AI video generation

Mutual exclusivity rules:

firstFrameImageUrl and referenceImageUrls cannot be provided together. Use one or the other.
referenceImageUrl is only for image generation. For video generation, use firstFrameImageUrl or referenceImageUrls.
firstFrameImageUrl and referenceImageUrls are only for video generation. For image generation, use referenceImageUrl.

Image Models — AI Credit Cost

Model	AI Credits (per image)	Best For
`flux-schnell`	0.6	Reliable for basic layouts
`seedream3.0`	2	Reliable for text and numbers
`nanobanana`	4	Excels at details
`nanobanana-pro`	14	Superior cinematic quality

Video Models — AI Credit Cost

Credits are charged per second of video generated.

Model	AI Credits (per second)	Best For
`pixverse5.5`	1.6	Reliable for basic motion
`veo3.1_fast`	10	Efficient cinematic quality
`veo3.1`	20	Superior cinematic quality

For detailed guides on configuring AI-generated visuals, see:

{
  "searchFilter": {
    "category": "Nature/Landscapes",
    "query": "mountain sunset",
    "keywords": ["nature", "mountains", "sunset"],
    "libraries": ["story_blocks", "getty"]
  }
}

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.

scenes[].background.searchFilter.category

string

Category filter for media search. See Visual Filter Categories.

scenes[].background.searchFilter.query

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”).

scenes[].background.searchFilter.keywords

array

Keywords for search (max 10, each 2-100 characters).

{
  "keywords": ["business", "technology", "innovation"]
}

scenes[].background.searchFilter.libraries

array

Media libraries to search. Options: story_blocks, getty

{
  "libraries": ["story_blocks", "getty"]
}

background.settings Object

{
  "settings": {
    "mute": true,
    "loop": true,
    "zoomAndPan": false
  }
}

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.

scenes[].background.settings.mute

boolean

Mute audio from background media.

scenes[].background.settings.loop

boolean

Loop the background media.

scenes[].background.settings.zoomAndPan

boolean

Apply zoom and pan effects. Cannot be used with kenBurnsEffect.

scenes[].background.settings.kenBurnsEffect

boolean

Apply Ken Burns effect (images only). Cannot be used with zoomAndPan.

Visual Filter Categories

Available 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.

{
  "backgroundBrolls": [
    {
      "visualUrl": "https://example.com/broll.mp4",
      "type": "video",
      "brollClip": { "start": 0, "end": 5 },
      "settings": { "mute": true }
    }
  ]
}

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.

scenes[].backgroundBrolls[].brollClip

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).

{
  "backgroundCorpus": [
    { "visualUrl": "https://example.com/image1.jpg", "type": "image", "prefer": true },
    { "visualUrl": "https://example.com/image2.jpg", "type": "image" }
  ]
}

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.

scenes[].backgroundCorpus[].visualUrl

string

URL to background image.

scenes[].backgroundCorpus[].type

string

Must be image.

scenes[].backgroundCorpus[].prefer

boolean

Mark as preferred image for selection.

transcript Array

Transcription of input video or audio content.

{
  "transcript": [
    {
      "speakerId": 1,
      "words": [
        { "word": "Hello", "start_time": 0.0, "end_time": 0.5, "is_pause": false, "is_filler": false }
      ]
    }
  ]
}

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.

scenes[].transcript[].speakerId

integer

Speaker identifier.

scenes[].transcript[].words

array

required

Array of word objects.

scenes[].transcript[].words[].word

string

required

The word text.

scenes[].transcript[].words[].start_time

number

required

Start time in seconds (min 0).

scenes[].transcript[].words[].end_time

number

required

End time in seconds (must be >= start_time).

scenes[].transcript[].words[].is_pause

boolean

Whether this is a pause.

scenes[].transcript[].words[].is_filler

boolean

Whether this is a filler word.

scenes[].transcript[].words[].speakerId

integer

Speaker identifier for this word.

mediaRepurposeSettings Object

Settings for repurposing audio or video content.

{
  "mediaRepurposeSettings": {
    "highlightLength": 60,
    "removeFillerWords": true,
    "removeSilences": true,
    "silenceThresholdSeconds": 2
  }
}

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.

scenes[].mediaRepurposeSettings.highlightLength

number

Length of highlight in seconds (5-180).

scenes[].mediaRepurposeSettings.removeFillerWords

boolean

Remove filler words from the content.

scenes[].mediaRepurposeSettings.removeSilences

boolean

Remove silences from the content.

scenes[].mediaRepurposeSettings.silenceThresholdSeconds

number

Silence threshold in seconds (0-10).

templateOverride Object

Configuration for manipulating template scenes. Only available when templateId is provided.

{
  "templateOverride": {
    "sceneId": "scene-123",
    "subtitles": [
      { "text": "Updated subtitle text", "minimumDuration": 3 }
    ],
    "layers": [
      [
        { "layerId": "text-layer-1", "type": "text", "text": "Updated text content" }
      ]
    ]
  }
}

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.

scenes[].templateOverride.sceneId

string

ID of the existing scene to modify. Cannot be used with scenePosition.

scenes[].templateOverride.scenePosition

number

Position of the existing scene to modify (1-based). Cannot be used with sceneId.

scenes[].templateOverride.newScenePosition

number

New position for a newly inserted scene (1-based). Only for new scenes.

scenes[].templateOverride.insertAfterSceneId

string

Insert new scene after this scene ID. Only for new scenes. Cannot be used with newScenePosition.

scenes[].templateOverride.insertBeforeSceneId

string

Insert new scene before this scene ID. Only for new scenes. Cannot be used with newScenePosition or insertAfterSceneId.

scenes[].templateOverride.replaceSceneId

string

Replace the scene with this ID. Only for new scenes. Cannot be used with newScenePosition.

scenes[].templateOverride.replaceScenePosition

number

Replace the scene at this position (1-based). Only for new scenes. Cannot be used with newScenePosition or replaceSceneId.

scenes[].templateOverride.baseSceneId

string

Base scene ID to copy settings from. Only for new scenes.

scenes[].templateOverride.baseScenePosition

number

Base scene position to copy settings from (1-based). Only for new scenes. Cannot be used with baseSceneId.

scenes[].templateOverride.deleteScene

boolean

Delete this scene. Only for existing scenes.

scenes[].templateOverride.copyScene

boolean

Copy this scene. Only for existing scenes.

scenes[].templateOverride.subtitles

array

Array of subtitle configurations (max 500). Only for existing scenes. See templateOverride.subtitles Array.

scenes[].templateOverride.layers

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

{
  "subtitles": [
    {
      "text": "Your subtitle text here",
      "minimumDuration": 3,
      "styleId": "style-123"
    }
  ]
}

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.

scenes[].templateOverride.subtitles[].text

string

required

Subtitle text (1-40000 characters).

scenes[].templateOverride.subtitles[].minimumDuration

number

Minimum duration in seconds.

scenes[].templateOverride.subtitles[].styleId

string

ID of saved text style.

scenes[].templateOverride.subtitles[].styleName

string

Name of saved text style.

scenes[].templateOverride.subtitles[].style

object

Inline style configuration. See subtitleStyle Object.

templateOverride.layers Array

Layers allow you to customize text, image, and video elements within template scenes.

{
  "layers": [
    [
      { "layerId": "headline", "type": "text", "text": "Updated headline" },
      { "layerId": "logo", "type": "image", "url": "https://example.com/logo.png" }
    ]
  ]
}

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.

scenes[].templateOverride.layers[][].layerId

string

ID of the layer to modify (max 100 characters).

scenes[].templateOverride.layers[][].type

string

Layer type. Options: text, image, video

scenes[].templateOverride.layers[][].text

string

Text content (max 40000 characters). For text type only.

scenes[].templateOverride.layers[][].url

string

Media URL. For image or video type only.

scenes[].templateOverride.layers[][].styleId

string

Text style ID. For text type only.

scenes[].templateOverride.layers[][].styleName

string

Text style name. For text type only.

scenes[].templateOverride.layers[][].style

object

Inline text style. See subtitleStyle Object. For text type only.

scenes[].templateOverride.layers[][].deleteLayer

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.

success

boolean

Indicates whether the request was successful

data

object

Contains the storyboard job information

jobId

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.

{
    "success": true,
    "data": {
        "jobId": "a1d36612-326d-4b81-aece-411f8aed4c70"
    }
}

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

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/video/storyboard \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "videoName": "demo_text_to_video",
    "voiceOver": {
      "enabled": true,
      "aiVoices": [{"speaker": "Brian", "speed": 100}]
    },
    "scenes": [
      {
        "story": "AI is transforming how we create content. It automates tasks and saves time.",
        "createSceneOnEndOfSentence": true
      }
    ]
  }' | python -m json.tool

Preview with Smart Layout

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'smart_layout_video',
    smartLayoutName: 'modern minimalist',
    voiceOver: {
      enabled: true,
      aiVoices: [{ speaker: 'Emma', speed: 100 }]
    },
    scenes: [{
      story: 'Professional video creation has never been easier. Let AI handle the visuals.',
      createSceneOnEndOfSentence: true
    }]
  })
});

Preview with AI Story Generation

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'ai_generated_script',
    voiceOver: {
      enabled: true,
      aiVoices: [{ speaker: 'Matthew', speed: 100 }]
    },
    scenes: [{
      storyCoPilot: {
        prompt: 'Benefits of remote work for modern businesses',
        videoType: 'Explainer',
        duration: 90,
        platform: 'LinkedIn',
        tone: 'professional'
      },
      createSceneOnEndOfSentence: true
    }]
  })
});

Preview with AI-Generated Background Image

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'ai_background_image_video',
    voiceOver: {
      enabled: true,
      aiVoices: [{ speaker: 'Brian', speed: 100 }]
    },
    scenes: [{
      story: 'Experience the beauty of nature through AI-generated imagery.',
      createSceneOnEndOfSentence: true,
      background: {
        type: 'image',
        aiVisual: {
          model: 'seedream3.0',
          mediaStyle: 'photorealistic'
        },
        settings: {
          zoomAndPan: true
        }
      }
    }]
  })
});

Preview with AI-Generated Background Video Clip

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'ai_background_video_clip',
    aspectRatio: '16:9',
    voiceOver: {
      enabled: true,
      aiVoices: [{ speaker: 'Brian', speed: 100 }]
    },
    scenes: [{
      story: 'The future of technology is unfolding before our eyes.',
      createSceneOnEndOfSentence: true,
      background: {
        type: 'video',
        aiVisual: {
          prompt: 'Futuristic cityscape at night with flying vehicles and neon signs',
          model: 'pixverse5.5',
          videoDuration: '8s'
        }
      }
    }]
  })
});

Full Featured Preview Example

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'full_featured_video',
    aspectRatio: '16:9',
    language: 'en',
    saveProject: true,
    brandName: 'My Brand',

    // Background music
    backgroundMusic: {
      enabled: true,
      autoMusic: true,
      volume: 0.3
    },

    // AI Voice-over
    voiceOver: {
      enabled: true,
      aiVoices: [{
        speaker: 'Brian',
        speed: 100,
        amplificationLevel: 0
      }]
    },

    // Logo
    logo: {
      url: 'https://example.com/logo.png',
      position: 'top-right',
      width: '12%'
    },

    // Subtitle styling
    subtitleStyle: {
      fontFamily: 'Montserrat',
      fontSize: 48,
      color: 'rgba(255,255,255,1)',
      position: 'bottom-center',
      alignment: 'center'
    },

    // Scenes
    scenes: [{
      story: 'Welcome to our company. We create innovative solutions. Join us on this journey.',
      createSceneOnEndOfSentence: true,
      highlightKeywords: true,
      sceneTransition: 'fade'
    }]
  })
});

Error Handling

400 - Missing Required Fields

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "videoName is required"
  }
}

Solution: Ensure videoName and scenes are provided.

400 - Invalid Scene Configuration

{
  "success": false,
  "error": {
    "message": "Scene must have exactly one of: story, storyCoPilot, blogUrl, pptUrl, audioUrl, or videoUrl"
  }
}

Solution: Each scene can only have one content source.

400 - Smart Layout Conflict

{
  "success": false,
  "error": {
    "message": "maxSubtitleLines is not allowed when smartLayoutId or smartLayoutName is provided"
  }
}

Solution: Remove maxSubtitleLines when using smart layouts.

401 - Unauthorized

{
  "message": "Unauthorized"
}

Solution: Check your API key is valid and correctly formatted in the Authorization header.

429 - Rate Limit Exceeded

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

Story CoPilot

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

Getting started

Videos

Pictory Jobs

Video Storyboard

AI Studio

Smart Layouts

Avatars

VoiceOvers

Music Search

Media Management

Branding - Video

Pictory Projects

Video Templates

Video Summary and Transcription

Vimeo Integration

AWS Integration

​Overview

​Render Workflow Options

​Preview vs. Final Render

​Use Cases

Content Review

Visual Validation

Scene Adjustment

Approval Workflow

Cost Optimization

Iterative Creation

Template Testing

Batch Preparation

​API Endpoint

​Request Headers

​Request Body Parameters

​voiceOver Object

​aiVoices Array

​premiumVoiceSettings Object

​externalVoice Object

​avatar Object

​backgroundMusic Object

​logo Object

​subtitleStyle Object

​animations Array

​Supported Font Families

​destinations Array

​Vimeo Destination

​Vimeo Privacy Object

​scenes Array

​storyCoPilot Object

​scenes[].voiceOver Object

​scenes[].backgroundMusic Object

​scenes[].avatar Object

​background Object

​aiVisual Object

​Reference Image Fields — Quick Reference

​Image Models — AI Credit Cost

​Video Models — AI Credit Cost

​searchFilter Object

​background.settings Object

​Visual Filter Categories

​backgroundBrolls Array

​backgroundCorpus Array

​transcript Array

​mediaRepurposeSettings Object

​templateOverride Object

​templateOverride.subtitles Array

​templateOverride.layers Array

​Response

​Next Steps

​Code Examples

​Basic Text to Video Preview

​Preview with Smart Layout

​Preview with AI Story Generation

​Preview with AI-Generated Background Image

​Preview with AI-Generated Background Video Clip

​Full Featured Preview Example

​Error Handling

​Related Guides

AI-Generated Background Images

AI-Generated Background Video Clips

AI Voice-Over

Smart Layouts

Story CoPilot

Overview

Render Workflow Options

Preview vs. Final Render

Use Cases

API Endpoint

Request Headers

Request Body Parameters

voiceOver Object

aiVoices Array

premiumVoiceSettings Object

externalVoice Object

avatar Object

backgroundMusic Object

logo Object

subtitleStyle Object

animations Array

Supported Font Families

destinations Array

Vimeo Destination

Vimeo Privacy Object

scenes Array

storyCoPilot Object

scenes[].voiceOver Object

scenes[].backgroundMusic Object

scenes[].avatar Object

background Object

aiVisual Object

Reference Image Fields — Quick Reference

Image Models — AI Credit Cost

Video Models — AI Credit Cost

searchFilter Object

background.settings Object

Visual Filter Categories

backgroundBrolls Array

backgroundCorpus Array

transcript Array

mediaRepurposeSettings Object

templateOverride Object

templateOverride.subtitles Array

templateOverride.layers Array

Response

Next Steps

Code Examples

Basic Text to Video Preview

Preview with Smart Layout

Preview with AI Story Generation

Preview with AI-Generated Background Image

Preview with AI-Generated Background Video Clip

Full Featured Preview Example

Error Handling

Related Guides

Next Steps

Supporting APIs