Skip to main content
POST
/
pictoryapis
/
v2
/
video
/
storyboard
Create Storyboard Preview
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/video/storyboard \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "videoName": "<string>",
  "videoWidth": 123,
  "videoHeight": 123,
  "aspectRatio": "<string>",
  "language": "<string>",
  "saveProject": true,
  "webhook": "<string>",
  "webhookInput": {},
  "templateId": "<string>",
  "variables": {},
  "brandId": "<string>",
  "brandName": "<string>",
  "smartLayoutName": "<string>",
  "smartLayoutId": "<string>",
  "storyboardVersion": "<string>",
  "subtitleStyleId": "<string>",
  "subtitleStyleName": "<string>",
  "subtitleStyle": {},
  "awsConnectionId": "<string>",
  "vimeoConnectionId": "<string>",
  "destinations": [
    {}
  ],
  "voiceOver": {},
  "backgroundMusic": {},
  "logo": {},
  "scenes": [
    {}
  ],
  "avatar": {},
  "voiceOver.enabled": true,
  "voiceOver.aiVoices": [
    {}
  ],
  "voiceOver.externalVoice": {},
  "voiceOver.aiVoices[].speaker": "<string>",
  "voiceOver.aiVoices[].speed": 123,
  "voiceOver.aiVoices[].amplificationLevel": 123,
  "voiceOver.aiVoices[].premiumVoiceSettings": {},
  "voiceOver.aiVoices[].premiumVoiceSettings.modelId": "<string>",
  "voiceOver.aiVoices[].premiumVoiceSettings.stability": "<string>",
  "voiceOver.aiVoices[].premiumVoiceSettings.useSpeakerBoost": true,
  "voiceOver.aiVoices[].premiumVoiceSettings.similarityBoost": "<string>",
  "voiceOver.aiVoices[].premiumVoiceSettings.style": "<string>",
  "voiceOver.externalVoice.voiceUrl": "<string>",
  "voiceOver.externalVoice.syncVoice": true,
  "voiceOver.externalVoice.amplificationLevel": 123,
  "avatar.avatarId": "<string>",
  "avatar.position": "<string>",
  "avatar.width": "<string>",
  "avatar.borderRadius": "<string>",
  "avatar.borderColor": "<string>",
  "avatar.borderThickness": 123,
  "avatar.backgroundColor": "<string>",
  "avatar.hide": true,
  "backgroundMusic.enabled": true,
  "backgroundMusic.autoMusic": true,
  "backgroundMusic.musicUrl": "<string>",
  "backgroundMusic.volume": 123,
  "backgroundMusic.clips": [
    {}
  ],
  "logo.url": "<string>",
  "logo.position": "<string>",
  "logo.width": "<string>",
  "subtitleStyle.fontUrl": "<string>",
  "subtitleStyle.fontFamily": "<string>",
  "subtitleStyle.fontSize": 123,
  "subtitleStyle.color": "<string>",
  "subtitleStyle.backgroundColor": "<string>",
  "subtitleStyle.shadowColor": "<string>",
  "subtitleStyle.shadowWidth": "<string>",
  "subtitleStyle.keywordColor": "<string>",
  "subtitleStyle.position": "<string>",
  "subtitleStyle.alignment": "<string>",
  "subtitleStyle.decorations": [
    {}
  ],
  "subtitleStyle.case": "<string>",
  "subtitleStyle.paragraphWidth": "<string>",
  "subtitleStyle.animations": [
    {}
  ],
  "subtitleStyle.animations[].name": "<string>",
  "subtitleStyle.animations[].type": "<string>",
  "subtitleStyle.animations[].speed": "<string>",
  "subtitleStyle.animations[].customSpeedValue": 123,
  "subtitleStyle.animations[].direction": "<string>",
  "subtitleStyle.animations[].writingStyle": "<string>",
  "subtitleStyle.animations[].futureWords": "<string>",
  "destinations[].type": "<string>",
  "destinations[].folder_uri": "<string>",
  "destinations[].content_rating": [
    {}
  ],
  "destinations[].privacy": {},
  "destinations[].privacy.view": "<string>",
  "destinations[].privacy.embed": "<string>",
  "destinations[].privacy.comments": "<string>",
  "destinations[].privacy.add": true,
  "destinations[].privacy.download": true,
  "scenes[].story": "<string>",
  "scenes[].storyCoPilot": {},
  "scenes[].blogUrl": "<string>",
  "scenes[].pptUrl": "<string>",
  "scenes[].audioUrl": "<string>",
  "scenes[].videoUrl": "<string>",
  "scenes[].createSceneOnNewLine": true,
  "scenes[].createSceneOnEndOfSentence": true,
  "scenes[].maxSubtitleLines": 123,
  "scenes[].highlightKeywords": true,
  "scenes[].hideSubtitles": true,
  "scenes[].minimumDuration": 123,
  "scenes[].endPauseDuration": 123,
  "scenes[].sceneTransition": "<string>",
  "scenes[].audioLanguage": "<string>",
  "scenes[].useSpeakerNotes": true,
  "scenes[].isSSMLStory": true,
  "scenes[].caption": "<string>",
  "scenes[].captionLanguage": "<string>",
  "scenes[].subtitleStyleId": "<string>",
  "scenes[].subtitleStyleName": "<string>",
  "scenes[].subtitleStyle": {},
  "scenes[].voiceOver": {},
  "scenes[].backgroundMusic": {},
  "scenes[].avatar": {},
  "scenes[].background": {},
  "scenes[].backgroundBrolls": [
    {}
  ],
  "scenes[].backgroundCorpus": [
    {}
  ],
  "scenes[].transcript": [
    {}
  ],
  "scenes[].mediaRepurposeSettings": {},
  "scenes[].templateOverride": {},
  "scenes[].storyCoPilot.prompt": "<string>",
  "scenes[].storyCoPilot.videoType": "<string>",
  "scenes[].storyCoPilot.duration": 123,
  "scenes[].storyCoPilot.platform": "<string>",
  "scenes[].storyCoPilot.tone": "<string>",
  "scenes[].voiceOver.enabled": true,
  "scenes[].voiceOver.aiVoices": [
    {}
  ],
  "scenes[].voiceOver.externalVoice": {},
  "scenes[].backgroundMusic.enabled": true,
  "scenes[].avatar.position": "<string>",
  "scenes[].avatar.top": "<string>",
  "scenes[].avatar.left": "<string>",
  "scenes[].avatar.width": "<string>",
  "scenes[].avatar.borderRadius": "<string>",
  "scenes[].avatar.borderColor": "<string>",
  "scenes[].avatar.borderThickness": 123,
  "scenes[].avatar.backgroundColor": "<string>",
  "scenes[].avatar.hide": true,
  "scenes[].background.visualUrl": "<string>",
  "scenes[].background.color": "<string>",
  "scenes[].background.aiVisual": {},
  "scenes[].background.type": "<string>",
  "scenes[].background.searchFilter": {},
  "scenes[].background.clips": [
    {}
  ],
  "scenes[].background.settings": {},
  "scenes[].background.aiVisual.prompt": "<string>",
  "scenes[].background.aiVisual.model": "<string>",
  "scenes[].background.aiVisual.mediaStyle": "<string>",
  "scenes[].background.aiVisual.videoDuration": "<string>",
  "scenes[].background.aiVisual.visualContinuity": true,
  "scenes[].background.aiVisual.firstFrameImageUrl": "<string>",
  "scenes[].background.aiVisual.referenceImageUrl": "<string>",
  "scenes[].background.aiVisual.referenceImageUrls": [
    "<string>"
  ],
  "scenes[].background.searchFilter.category": "<string>",
  "scenes[].background.searchFilter.query": "<string>",
  "scenes[].background.searchFilter.keywords": [
    {}
  ],
  "scenes[].background.searchFilter.libraries": [
    {}
  ],
  "scenes[].background.settings.mute": true,
  "scenes[].background.settings.loop": true,
  "scenes[].background.settings.zoomAndPan": true,
  "scenes[].background.settings.kenBurnsEffect": true,
  "scenes[].backgroundBrolls[].brollClip": {},
  "scenes[].backgroundCorpus[].visualUrl": "<string>",
  "scenes[].backgroundCorpus[].type": "<string>",
  "scenes[].backgroundCorpus[].prefer": true,
  "scenes[].transcript[].speakerId": 123,
  "scenes[].transcript[].words": [
    {}
  ],
  "scenes[].transcript[].words[].word": "<string>",
  "scenes[].transcript[].words[].start_time": 123,
  "scenes[].transcript[].words[].end_time": 123,
  "scenes[].transcript[].words[].is_pause": true,
  "scenes[].transcript[].words[].is_filler": true,
  "scenes[].transcript[].words[].speakerId": 123,
  "scenes[].mediaRepurposeSettings.highlightLength": 123,
  "scenes[].mediaRepurposeSettings.removeFillerWords": true,
  "scenes[].mediaRepurposeSettings.removeSilences": true,
  "scenes[].mediaRepurposeSettings.silenceThresholdSeconds": 123,
  "scenes[].templateOverride.sceneId": "<string>",
  "scenes[].templateOverride.scenePosition": 123,
  "scenes[].templateOverride.newScenePosition": 123,
  "scenes[].templateOverride.insertAfterSceneId": "<string>",
  "scenes[].templateOverride.insertBeforeSceneId": "<string>",
  "scenes[].templateOverride.replaceSceneId": "<string>",
  "scenes[].templateOverride.replaceScenePosition": 123,
  "scenes[].templateOverride.baseSceneId": "<string>",
  "scenes[].templateOverride.baseScenePosition": 123,
  "scenes[].templateOverride.deleteScene": true,
  "scenes[].templateOverride.copyScene": true,
  "scenes[].templateOverride.subtitles": [
    {}
  ],
  "scenes[].templateOverride.layers": [
    {}
  ],
  "scenes[].templateOverride.subtitles[].text": "<string>",
  "scenes[].templateOverride.subtitles[].minimumDuration": 123,
  "scenes[].templateOverride.subtitles[].styleId": "<string>",
  "scenes[].templateOverride.subtitles[].styleName": "<string>",
  "scenes[].templateOverride.subtitles[].style": {},
  "scenes[].templateOverride.layers[][].layerId": "<string>",
  "scenes[].templateOverride.layers[][].type": "<string>",
  "scenes[].templateOverride.layers[][].text": "<string>",
  "scenes[].templateOverride.layers[][].url": "<string>",
  "scenes[].templateOverride.layers[][].styleId": "<string>",
  "scenes[].templateOverride.layers[][].styleName": "<string>",
  "scenes[].templateOverride.layers[][].style": {},
  "scenes[].templateOverride.layers[][].deleteLayer": true
}
'
{
    "success": true,
    "data": {
        "jobId": "a1d36612-326d-4b81-aece-411f8aed4c70"
    }
}

Documentation Index

Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

WorkflowAPIWhen to Use
Create PreviewThis APIGenerate preview to review scenes before rendering
Render from PreviewRender from PreviewRender preview as-is without modifications
Render with ModificationsRender VideoModify preview elements before rendering
Render Saved ProjectRender ProjectRender existing project created in App or via API
Direct RenderRender Storyboard VideoSkip preview, render directly from input

​
Preview vs. Final Render

AspectStoryboard PreviewFinal Render
PurposeReview and validate contentProduce final video file
OutputScene thumbnails, metadata, project structureFull HD video file
SpeedFastSlower
CostLower resource usageFull rendering resources
EditableYes, make changes before renderVideo is final
Use CaseContent approval, iterationFinal 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 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.
{
  "background": {
    "type": "image",
    "aiVisual": {
      "prompt": "A serene mountain landscape at sunset",
      "model": "seedream3.0",
      "mediaStyle": "photorealistic"
    }
  }
}
​
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

FieldApplicable TypeDescription
firstFrameImageUrl"video" onlyImage used as the starting frame of the generated video
referenceImageUrl"image" onlySingle reference image for AI image generation
referenceImageUrls"video" only1–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

ModelAI Credits (per image)Best For
flux-schnell0.6Reliable for basic layouts
seedream3.02Reliable for text and numbers
nanobanana4Excels at details
nanobanana-pro14Superior cinematic quality

​
Video Models — AI Credit Cost

Credits are charged per second of video generated.
ModelAI Credits (per second)Best For
pixverse5.51.6Reliable for basic motion
veo3.1_fast10Efficient cinematic quality
veo3.120Superior cinematic quality
For detailed guides on configuring AI-generated visuals, see:

​
searchFilter Object

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

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'
        }
      }
    }]
  })
});

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

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "videoName is required"
  }
}
Solution: Ensure videoName and scenes are provided.
{
  "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.
{
  "success": false,
  "error": {
    "message": "maxSubtitleLines is not allowed when smartLayoutId or smartLayoutName is provided"
  }
}
Solution: Remove maxSubtitleLines when using smart layouts.
{
  "message": "Unauthorized"
}
Solution: Check your API key is valid and correctly formatted in the Authorization header.
Solution: Implement exponential backoff and space out requests.

AI-Generated Background Images

Generate AI images as scene backgrounds

AI-Generated Background Video Clips

Generate AI video clips as scene backgrounds

AI Voice-Over

Add professional AI narration

Smart Layouts

Apply professional visual layouts

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