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

language

string

Language of the text content. Options: zh, nl, en, fr, de, it, ja, ko, pt, ru, es, hi

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)

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.

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.

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.

voiceOver Object

Voice-over configuration for AI narration.

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

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

aiVoices[].speaker

string

required

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

aiVoices[].speed

number

Speech speed from 50 to 200. Default: 100

aiVoices[].amplificationLevel

number

Volume level from -1 to 1. Default: 0

aiVoices[].premiumVoiceSettings

object

ElevenLabs premium voice settings. See premiumVoiceSettings Object.

premiumVoiceSettings Object

premiumVoiceSettings.modelId

string

ElevenLabs model. Options: eleven_multilingual_v2, eleven_flash_v2_5, eleven_turbo_v2_5, eleven_turbo_v2, eleven_flash_v2, eleven_multilingual_v1, eleven_monolingual_v1

premiumVoiceSettings.stability

string

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

premiumVoiceSettings.useSpeakerBoost

boolean

Enable speaker boost enhancement.

premiumVoiceSettings.similarityBoost

string

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

premiumVoiceSettings.style

string

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

externalVoice Object

externalVoice.voiceUrl

string

required

URL to external voice audio file.

externalVoice.syncVoice

boolean

Auto-synchronize voice with video subtitles.

externalVoice.amplificationLevel

number

Audio amplification level from -1 to 1. Default: 0

backgroundMusic Object

Background music configuration for the video.

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

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.

logo Object

Logo overlay configuration.

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

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

subtitleStyle.fontUrl

string

URL to custom font file (max 3000 characters). 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)”) or hex format (e.g., “#FFFFFF”)

subtitleStyle.backgroundColor

string

Background color in RGBA or hex format.

subtitleStyle.shadowColor

string

Shadow color.

subtitleStyle.shadowWidth

string

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

subtitleStyle.keywordColor

string

Color for highlighted keywords in RGBA or hex format.

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

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). See animations Array.

animations Array

animations[].name

string

required

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

animations[].type

string

required

Animation type. Options: entry, exit

animations[].speed

string

required

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

animations[].customSpeedValue

number

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

animations[].direction

string

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

animations[].writingStyle

string

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

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

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
      }
    }
  ]
}

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

destinations[].privacy

object

Privacy settings. See Vimeo Privacy Object.

Vimeo Privacy Object

privacy.view

string

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

privacy.embed

string

Embed access. Options: private, public, whitelist

privacy.comments

string

Comment access. Options: anybody, contacts, nobody

privacy.add

boolean

Allow adding to albums/channels.

privacy.download

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, storyCoPilot, blogUrl, pptUrl, audioUrl, or videoUrl.

scenes[].story

string

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

scenes[].storyCoPilot

object

AI story generation configuration. See storyCoPilot Object.

scenes[].blogUrl

string

URL to blog/article content (max 3000 characters).

scenes[].pptUrl

string

URL to PowerPoint presentation file (max 3000 characters).

scenes[].audioUrl

string

URL to audio file for audio-to-video conversion (max 3000 characters). Requires audioLanguage.

scenes[].videoUrl

string

URL to video file for video repurposing (max 3000 characters). 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

number

Maximum subtitle lines to display at once. Only for text-to-video and article-to-video. Cannot be used with smart layouts.

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. Options: 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

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. Options: zh, nl, en, fr, de, it, ja, ko, pt, ru, es, hi

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[].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"
  }
}

storyCoPilot.prompt

string

required

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

storyCoPilot.videoType

string

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

storyCoPilot.duration

integer

Target duration in seconds (1-600).

storyCoPilot.platform

string

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

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 }]
  }
}

voiceOver.enabled

boolean

required

Enable or disable voice-over for this scene.

voiceOver.aiVoices

array

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

voiceOver.externalVoice

object

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

scenes[].backgroundMusic Object

Background music configuration specific to a scene.

backgroundMusic.enabled

boolean

required

Enable or disable background music for this scene.

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.

background.visualUrl

string

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

background.color

string

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

background.aiVisual

object

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

background.type

string

Media type. Options: video, image

background.searchFilter

object

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

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.

background.settings

object

Background playback settings. See background.settings Object.

aiVisual Object

aiVisual.prompt

string

Text prompt for AI generation (max 250 characters).

aiVisual.model

string

required

AI model for image generation. Options: seedream3.0, flux-schnell, nanobanana, titan

aiVisual.mediaStyle

string

Style for generated image. Options: photorealistic, artistic, cartoon, minimalist, vintage, futuristic

searchFilter.category

string

Category filter for media search. See Visual Filter Categories.

searchFilter.query

string

Search query text (max 3000 characters).

searchFilter.keywords

array

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

searchFilter.libraries

array

Media libraries to search. Options: story_blocks, getty

background.settings Object

settings.mute

boolean

Mute audio from background media.

settings.loop

boolean

Loop the background media.

settings.zoomAndPan

boolean

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

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:

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" }
  ]
}

backgroundCorpus[].visualUrl

string

URL to background image.

backgroundCorpus[].type

string

Must be image.

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 }
      ]
    }
  ]
}

transcript[].speakerId

integer

Speaker identifier.

transcript[].words

array

required

Array of word objects.

words[].word

string

required

The word text.

words[].start_time

number

required

Start time in seconds (min 0).

words[].end_time

number

required

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

words[].is_pause

boolean

Whether this is a pause.

words[].is_filler

boolean

Whether this is a filler word.

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
  }
}

mediaRepurposeSettings.highlightLength

number

Length of highlight in seconds (5-180).

mediaRepurposeSettings.removeFillerWords

boolean

Remove filler words from the content.

mediaRepurposeSettings.removeSilences

boolean

Remove silences from the content.

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" }
      ]
    ]
  }
}

templateOverride.sceneId

string

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

templateOverride.scenePosition

number

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

templateOverride.newScenePosition

number

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

templateOverride.insertAfterSceneId

string

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

templateOverride.insertBeforeSceneId

string

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

templateOverride.replaceSceneId

string

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

templateOverride.replaceScenePosition

number

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

templateOverride.baseSceneId

string

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

templateOverride.baseScenePosition

number

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

templateOverride.deleteScene

boolean

Delete this scene. Only for existing scenes.

templateOverride.copyScene

boolean

Copy this scene. Only for existing scenes.

templateOverride.subtitles

array

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

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"
    }
  ]
}

subtitles[].text

string

required

Subtitle text (1-40000 characters).

subtitles[].minimumDuration

number

Minimum duration in seconds.

subtitles[].styleId

string

ID of saved text style.

subtitles[].styleName

string

Name of saved text style.

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" }
    ]
  ]
}

layers[][].layerId

string

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

layers[][].type

string

Layer type. Options: text, image, video

layers[][].text

string

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

layers[][].url

string

Media URL (max 3000 characters). For image or video type only.

layers[][].styleId

string

Text style ID. For text type only.

layers[][].styleName

string

Text style name. For text type only.

layers[][].style

object

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

layers[][].deleteLayer

boolean

Delete this layer.

Response

The API returns a job ID that you can use to track the preview generation progress. Once complete, you can retrieve the storyboard preview details including scene breakdowns, thumbnails, and project metadata.

What the Preview Contains

When the preview job completes, you’ll have access to:

Scene Breakdown - How your content was split into individual scenes
Visual Selections - AI-selected backgrounds and images for each scene
Timing Information - Estimated duration for each scene and total video length
Subtitle Text - Text content for each scene’s subtitles
Project Metadata - All configured settings (voice, music, branding, etc.)
Thumbnail Previews - Visual thumbnails representing each scene

{
  "success": true,
  "data": {
    "jobId": "74c0cc68-e1ed-42f3-a527-8bfc0b46bdb9"
  }
}

After Preview Generation

Once the preview is generated, you can:

Review the storyboard - Use Get Job to retrieve preview details
Make adjustments - Use Update Project to modify scenes or settings
Render final video - Use Render from Preview to produce the final video file

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 Visuals

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_visuals_video',
    voiceOver: {
      enabled: true,
      aiVoices: [{ speaker: 'Brian', speed: 100 }]
    },
    scenes: [{
      story: 'Experience the beauty of nature through AI-generated imagery.',
      createSceneOnEndOfSentence: true,
      background: {
        aiVisual: {
          model: 'seedream3.0',
          mediaStyle: 'photorealistic'
        },
        type: 'image',
        settings: {
          zoomAndPan: true
        }
      }
    }]
  })
});

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

Smart Layouts

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

​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

​background Object

​aiVisual Object

​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

​What the Preview Contains

​After Preview Generation

​Code Examples

​Basic Text to Video Preview

​Preview with Smart Layout

​Preview with AI Story Generation

​Preview with AI-Generated Visuals

​Full Featured Preview Example

​Error Handling

​Related Guides

AI Voice-Over

Smart Layouts

Story CoPilot

Background Music

Brand Settings

Subtitle Styles

​Next Steps

Check Preview Status

Render Final Video

Update Project

Get Project Details

​Supporting APIs

Get Voiceover Tracks

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

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

background Object

aiVisual Object

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

What the Preview Contains

After Preview Generation

Code Examples

Basic Text to Video Preview

Preview with Smart Layout

Preview with AI Story Generation

Preview with AI-Generated Visuals

Full Featured Preview Example

Error Handling

Related Guides

Next Steps

Supporting APIs