---
title: "Create Storyboard Preview"
method: POST
path: "/pictoryapis/v2/video/storyboard"
tags: ["Videos"]
---

# Create Storyboard Preview

`POST /pictoryapis/v2/video/storyboard`

## Request

- Base URL: `https://api.pictory.ai`
- URL: `https://api.pictory.ai/pictoryapis/v2/video/storyboard`
- Auth: API key in header `Authorization`

Generates a preview of your video project so you can review storyboard structure, scene breakdown, and visual selections before committing to the final render.
Returns a `jobId` which should be polled against the Get Storyboard Preview Job endpoint.
Use this when you want to validate content before incurring full rendering cost.

## Request body

- StoryboardRequest: Top-level storyboard request body shared by Create Storyboard Preview and Render Storyboard Video. `scenes` is required unless `templateId` is supplied. `brandId` and `brandName` are mutually exclusive (provide at most one). The same exclusivity applies to `smartLayoutId`/`smartLayoutName` and `subtitleStyleId`/`subtitleStyleName`. Set `aiStoryboard.enabled` to true to have the AI design every scene (text-to-video sources only).
  - `videoName` string, required: Name for the video project. Allowed characters: alphanumeric, spaces, underscores, hyphens. Optional when `aiStoryboard` is enabled with a `brief` scene: if omitted, the AI-generated title is used.
  - `videoWidth` integer: Video width in pixels. Must be supplied together with `videoHeight`.
  - `videoHeight` integer: Video height in pixels. Must be supplied together with `videoWidth`.
  - `aspectRatio` '1:1' | '16:9' | '9:16' | '4:5': Video aspect ratio.
  - `language` 'zh' | 'nl' | 'en' | 'fr' | 'de' | 'hi' | 'it' | 'ja' | 'ko' | 'mr' | 'pt' | 'ru' | 'es' | 'ta': Language of the text content.
  - `saveProject` boolean: Whether to save the project for later editing.
  - `webhook` string, uri: URL to POST the job result to when finished.
  - `webhookInput` object: Custom data echoed back in the webhook payload.
  - `templateId` string: Template ID. Obtain from Get Templates API.
  - `variables` object: Key/value pairs for template variables. Only valid with `templateId`.
  - `brandId` string: Brand ID to apply. Mutually exclusive with `brandName`.
  - `brandName` string: Brand name to apply. Mutually exclusive with `brandId`.
  - `smartLayoutId` string: Smart layout ID. Mutually exclusive with `smartLayoutName`.
  - `smartLayoutName` string: Smart layout name. Mutually exclusive with `smartLayoutId`.
  - `aiStoryboard` AiStoryboard: AI Storyboard. When `enabled` is true, every scene receives a layout, on-screen text elements, and a color palette chosen by AI: with `story`/`blogUrl` scenes the AI designs around your narration (script mode); with a single `brief` scene it writes the script and designs the storyboard (brief mode). Text-to-video only: `templateId`, `variables`, `smartLayoutId`, `smartLayoutName`, `aspectRatio` `4:5`, and the scene fields `pptUrl`, `audioUrl`, `videoUrl`, `transcript`, `mediaRepurposeSettings`, `audioLanguage`, `useSpeakerNotes`, `isSSMLStory`, `backgroundBrolls`, `backgroundCorpus`, `templateOverride` are rejected. Story scenes without a split option are split one scene per sentence; a scene that cannot be split and exceeds 1500 characters is rejected; at most 250 designed scenes.
    - `enabled` boolean, required: Set to true to have the AI design the storyboard.
  - `storyboardVersion` 'v3': Experimental. Set to `v3` to use the latest Pictory storyboard. Omit for classic storyboard.
  - `subtitleStyleId` string: Saved text style ID for subtitles. Mutually exclusive with `subtitleStyleName`.
  - `subtitleStyleName` string: Saved text style name for subtitles. Mutually exclusive with `subtitleStyleId`.
  - `subtitleStyle` SubtitleStyle: Inline subtitle style. Can be applied at the video level or per scene.
    - `fontUrl` string, uri
    - `fontFamily` string: Font family name. Required when `fontUrl` is provided.
    - `fontSize` integer
    - `color` string: RGBA color.
    - `backgroundColor` string
    - `shadowColor` string
    - `shadowWidth` string
    - `keywordColor` string
    - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
    - `alignment` 'left' | 'center' | 'right'
    - `decorations` string[]
    - `case` 'uppercase' | 'lowercase' | 'capitalize' | 'smallcapitalize'
    - `paragraphWidth` string
    - `animations` TextAnimation[]: Max 2 animations: one entry, one exit.
      - `name` 'none' | 'fade' | 'drift' | 'wipe' | 'text reveal' | 'elastic' | 'typewriter' | 'blur' | 'bulletin', required
      - `type` 'entry' | 'exit', required
      - `speed` 'slow' | 'medium' | 'fast' | 'custom', required
      - `customSpeedValue` number: Required when speed is 'custom'.
      - `direction` 'up' | 'down' | 'left' | 'right'
      - `writingStyle` 'character' | 'word' | 'line' | 'paragraph'
      - `futureWords` 'hidden' | 'subtle' | 'prominent': Only available with `fade` and `blur` entry animations.
  - `awsConnectionId` string: AWS connection ID for private S3 assets.
  - `vimeoConnectionId` string: Vimeo connection ID for direct Vimeo uploads.
  - `destinations` Destination[]: Destinations to upload the generated video to.
    - union: Destination configuration. Currently `vimeo` and `s3` types are supported.
      - object
        - `type` 'vimeo', required
        - `folder_uri` string
        - `content_rating` string[]
        - `privacy` VimeoPrivacy
          - `view` 'anybody' | 'contacts' | 'disable' | 'nobody' | 'password' | 'unlisted' | 'users'
          - `embed` 'private' | 'public' | 'whitelist'
          - `comments` 'anybody' | 'contacts' | 'nobody'
          - `add` boolean
          - `download` boolean
      - object
        - `type` 's3', required
        - `bucket` string, required
        - `region` string, required
        - `key` string, required
  - `voiceOver` VoiceOver: Voice-over configuration. Use `aiVoices` OR `externalVoice` (mutually exclusive).
    - `enabled` boolean, required
    - `aiVoices` AiVoice[]
      - `speaker` string, required: Voice speaker name (e.g. 'Brian', 'Emma'). Obtain available voices from the Get Voiceover Tracks API.
      - `speed` number
      - `amplificationLevel` number
      - `premiumVoiceSettings` PremiumVoiceSettings: ElevenLabs premium voice settings.
        - `modelId` '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'
        - `stability` string: Voice stability as percentage e.g. '50%'.
        - `similarityBoost` string: Similarity boost as percentage e.g. '75%'.
        - `style` string: Voice style as percentage e.g. '50%'.
        - `useSpeakerBoost` boolean
    - `externalVoice` ExternalVoice
      - `voiceUrl` string, uri, required
      - `syncVoice` boolean: Auto-sync the external voice with video subtitles.
      - `amplificationLevel` number
  - `backgroundMusic` BackgroundMusic: Background music configuration. `autoMusic` and `musicUrl` are mutually exclusive.
    - `enabled` boolean, required
    - `autoMusic` boolean
    - `musicUrl` string, uri: Any publicly accessible URL to an audio file, not only a Pictory-provided track. An `audioUrl` from Search Music Tracks is also valid, passed exactly as returned. Cannot be used with `autoMusic`.
    - `volume` number
    - `clips` object[]
      - `start` number, required: Start time in seconds
      - `end` number, required: End time in seconds
  - `logo` Logo
    - `url` string, uri, required
    - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
    - `width` string: Logo width as a percentage e.g. '15%'.
  - `avatar` Avatar: Avatar configuration for presenter-style videos. Avatars require voice-over to be enabled.
    - `avatarId` string, required: Account-scoped avatar identifier. MUST be discovered at runtime via `GET /v1/avatars` — do not hard-code values. Available avatars vary per account.
    - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
    - `width` string: Avatar width as integer percentage 0-100%.
    - `borderRadius` '0' | '50' | '100': Corner rounding: 0 (square), 50 (rounded), 100 (circular).
    - `borderColor` string: Border color in RGBA format.
    - `borderThickness` number
    - `backgroundColor` string: Background color in RGBA format.
    - `hide` boolean: Hide the avatar globally. Can be overridden per scene.
  - `scenes` Scene[], required: Array of scenes. Required unless `templateId` is supplied.
    - `story` string: Plain text content for the scene.
    - `brief` Brief: Describe the video and the AI writes the script. With `aiStoryboard` enabled, the AI also decides the scenes and designs each of them; the `brief` must then be the only scene, `prompt` is limited to 3900 characters, `duration` to 8–500 seconds, and the scene split options are not allowed.
      - `prompt` string, required: Topic or description for AI to generate content. At most 3900 characters with `aiStoryboard`.
      - `videoGoal` 'Explainer' | 'Marketing' | 'Internal Communication' | 'Tutorial' | 'Product': Goal of the video.
      - `duration` integer: Target duration in seconds. 8–500 with `aiStoryboard`; omit to let the AI choose.
      - `platform` 'YouTube' | 'TikTok' | 'Instagram' | 'Facebook' | 'LinkedIn' | 'Twitter': Target platform for script generation. Not used by the AI Storyboard.
      - `tone` 'professional' | 'casual' | 'friendly' | 'informative' | 'persuasive' | 'exciting' | 'educational' | 'humorous' | 'serious' | 'conversational'
    - `blogUrl` string, uri
    - `pptUrl` string, uri
    - `audioUrl` string, uri: Requires `audioLanguage` and `transcript`.
    - `videoUrl` string, uri: Requires `audioLanguage` and `transcript`.
    - `createSceneOnNewLine` boolean
    - `createSceneOnEndOfSentence` boolean
    - `maxSubtitleLines` integer: Caption lines shown simultaneously. Cannot be used with smart layouts.
    - `highlightKeywords` boolean
    - `hideSubtitles` boolean
    - `minimumDuration` number: Minimum scene duration in seconds.
    - `endPauseDuration` number: Pause at end of scene in seconds.
    - `sceneTransition` 'none' | 'wipeup' | 'wipedown' | 'wipeleft' | 'wiperight' | 'smoothleft' | 'smoothright' | 'radial' | 'circlecrop' | 'hblur' | 'fade'
    - `audioLanguage` '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-IN': Required when `audioUrl` or `videoUrl` is provided.
    - `useSpeakerNotes` boolean: Only valid with `pptUrl`.
    - `pptSlideAnimation` object: Animate PowerPoint slides into short video backgrounds. Each still slide is sent to an image-to-video model using the slide itself as the first frame, so the clip opens on the original slide. The clip loops for the length of the scene, so the slide returns at the start of every cycle. Slides that already contain video or PowerPoint build animations are left unchanged. Only valid with `pptUrl`.
      - `enabled` boolean: Set to true to animate slides.
      - `model` 'pixverse6' | 'veo3.1': Video model used to animate the slides. Defaults to pixverse6 when omitted, which does not consume AI credits. The veo3.1 model consumes AI credits and reproduces small slide text more reliably. Clips are capped at 10 seconds.
      - `slides` integer[]: Slide positions to animate, starting at 1. Omit or pass an empty array to animate every eligible slide.
    - `isSSMLStory` boolean: Story contains SSML markup. Only valid with `story`.
    - `caption` string: Separate caption text. Requires `story`.
    - `captionLanguage` 'zh' | 'nl' | 'en' | 'fr' | 'de' | 'hi' | 'it' | 'ja' | 'ko' | 'mr' | 'pt' | 'ru' | 'es' | 'ta': Only valid with `caption`.
    - `subtitleStyleId` string
    - `subtitleStyleName` string
    - `subtitleStyle` SubtitleStyle: Inline subtitle style. Can be applied at the video level or per scene.
      - `fontUrl` string, uri
      - `fontFamily` string: Font family name. Required when `fontUrl` is provided.
      - `fontSize` integer
      - `color` string: RGBA color.
      - `backgroundColor` string
      - `shadowColor` string
      - `shadowWidth` string
      - `keywordColor` string
      - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
      - `alignment` 'left' | 'center' | 'right'
      - `decorations` string[]
      - `case` 'uppercase' | 'lowercase' | 'capitalize' | 'smallcapitalize'
      - `paragraphWidth` string
      - `animations` TextAnimation[]: Max 2 animations: one entry, one exit.
        - `name` 'none' | 'fade' | 'drift' | 'wipe' | 'text reveal' | 'elastic' | 'typewriter' | 'blur' | 'bulletin', required
        - `type` 'entry' | 'exit', required
        - `speed` 'slow' | 'medium' | 'fast' | 'custom', required
        - `customSpeedValue` number: Required when speed is 'custom'.
        - `direction` 'up' | 'down' | 'left' | 'right'
        - `writingStyle` 'character' | 'word' | 'line' | 'paragraph'
        - `futureWords` 'hidden' | 'subtle' | 'prominent': Only available with `fade` and `blur` entry animations.
    - `voiceOver` VoiceOver: Voice-over configuration. Use `aiVoices` OR `externalVoice` (mutually exclusive).
      - `enabled` boolean, required
      - `aiVoices` AiVoice[]
        - `speaker` string, required: Voice speaker name (e.g. 'Brian', 'Emma'). Obtain available voices from the Get Voiceover Tracks API.
        - `speed` number
        - `amplificationLevel` number
        - `premiumVoiceSettings` PremiumVoiceSettings: ElevenLabs premium voice settings.
          - `modelId` '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'
          - `stability` string: Voice stability as percentage e.g. '50%'.
          - `similarityBoost` string: Similarity boost as percentage e.g. '75%'.
          - `style` string: Voice style as percentage e.g. '50%'.
          - `useSpeakerBoost` boolean
      - `externalVoice` ExternalVoice
        - `voiceUrl` string, uri, required
        - `syncVoice` boolean: Auto-sync the external voice with video subtitles.
        - `amplificationLevel` number
    - `backgroundMusic` union: Gives one scene its own music, sets how loud it is, or turns music off for that scene. All the scene music is joined into one soundtrack.
      - object
        - `enabled` boolean: Set to `false` for no music in this scene. Required when `musicUrl` is not set. It is `true` when `musicUrl` is set.
        - `musicUrl` string, uri, required: The music for this scene: a public link to an audio file, or an `audioUrl` from Search Music Tracks copied exactly as returned.
        - `volume` number: How loud this scene's music is, from 0 to 1. Use it only with `musicUrl`. If left out, the scene uses the video's music volume.
      - object
        - `enabled` boolean, required: Set to `false` for no music in this scene. Required when `musicUrl` is not set. It is `true` when `musicUrl` is set.
        - `musicUrl` string, uri: The music for this scene: a public link to an audio file, or an `audioUrl` from Search Music Tracks copied exactly as returned.
        - `volume` number: How loud this scene's music is, from 0 to 1. Use it only with `musicUrl`. If left out, the scene uses the video's music volume.
    - `avatar` SceneAvatarOverride: Scene-level avatar override. `avatarId` cannot be changed at the scene level.
      - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
      - `top` string: Distance from top as integer percentage. Cannot be used with `position`.
      - `left` string: Distance from left as integer percentage. Cannot be used with `position`.
      - `width` string
      - `borderRadius` '0' | '50' | '100'
      - `borderColor` string
      - `borderThickness` number
      - `backgroundColor` string
      - `hide` boolean
    - `background` Background: Scene background. Must contain exactly one of `visualUrl`, `color`, or `aiVisual`.
      - `visualUrl` string, uri
      - `color` string: Solid background color in RGBA, or hex format.
      - `colorOverlay` ColorOverlay: Semi-transparent color tint rendered on top of the background or media element. Transparency is controlled only by `opacity`; an RGBA color's alpha channel is ignored.
        - `color` string, required: Tint color in RGB, RGBA, or hex format.
        - `opacity` number: Tint strength from 0 (invisible) to 1 (solid).
      - `aiVisual` AiVisual
        - `prompt` string
        - `model` 'flux-schnell' | 'seedream3.0' | 'nanobanana' | 'nanobanana-pro' | 'nanobanana2' | 'nanobanana-lite2' | 'pixverse5.5' | 'pixverse5.6' | 'pixverse6' | 'omni-flash' | 'veo3.1', required: AI model. Image models: flux-schnell, seedream3.0, nanobanana, nanobanana-pro, nanobanana2, nanobanana-lite2. Video models: pixverse5.5, pixverse5.6, pixverse6, omni-flash, veo3.1.
        - `mediaStyle` 'photorealistic' | 'artistic' | 'cartoon' | 'minimalist' | 'vintage' | 'futuristic': Image type only.
        - `videoDuration` string: Video clip duration. Video type only. Valid values depend on the model: pixverse6 takes 5s, 8s, 10s or 15s; pixverse5.6 and pixverse5.5 take 5s, 8s or 10s; veo3.1 takes 4s, 6s or 8s; omni-flash takes 10s.
        - `visualContinuity` boolean: Enable visual continuity between consecutive AI-generated scenes.
        - `firstFrameImageUrl` string, uri: Video type only. Mutually exclusive with `referenceImageUrls`.
        - `referenceImageUrl` string, uri: Image type only.
        - `referenceImageUrls` string[]: Reference images that guide the generated visual. The most you can send depends on the model. Video type: up to 4 on pixverse6, pixverse5.6 and pixverse5.5, up to 3 on veo3.1, and 1 on omni-flash. Cannot be sent with `firstFrameImageUrl`. Image type: up to 4 on seedream3.0, nanobanana, nanobanana-pro, nanobanana2 and nanobanana-lite2. flux-schnell does not accept reference images. Cannot be sent with `referenceImageUrl`.
      - `type` 'video' | 'image': Required when `aiVisual` is provided.
      - `searchFilter` SearchFilter
        - `category` string
        - `query` string
        - `keywords` string[]
        - `libraries` string[]
      - `clips` object[]
        - `start` number, required
        - `end` number, required
      - `settings` object
        - `mute` boolean
        - `loop` boolean
        - `zoomAndPan` boolean: Mutually exclusive with `kenBurnsEffect`.
        - `kenBurnsEffect` boolean: Images only. Mutually exclusive with `zoomAndPan`.
    - `backgroundBrolls` BackgroundBroll[]
      - `visualUrl` string, uri
      - `color` string: Solid background color in RGBA, or hex format.
      - `colorOverlay` ColorOverlay: Semi-transparent color tint rendered on top of the background or media element. Transparency is controlled only by `opacity`; an RGBA color's alpha channel is ignored.
        - `color` string, required: Tint color in RGB, RGBA, or hex format.
        - `opacity` number: Tint strength from 0 (invisible) to 1 (solid).
      - `aiVisual` AiVisual
        - `prompt` string
        - `model` 'flux-schnell' | 'seedream3.0' | 'nanobanana' | 'nanobanana-pro' | 'nanobanana2' | 'nanobanana-lite2' | 'pixverse5.5' | 'pixverse5.6' | 'pixverse6' | 'omni-flash' | 'veo3.1', required: AI model. Image models: flux-schnell, seedream3.0, nanobanana, nanobanana-pro, nanobanana2, nanobanana-lite2. Video models: pixverse5.5, pixverse5.6, pixverse6, omni-flash, veo3.1.
        - `mediaStyle` 'photorealistic' | 'artistic' | 'cartoon' | 'minimalist' | 'vintage' | 'futuristic': Image type only.
        - `videoDuration` string: Video clip duration. Video type only. Valid values depend on the model: pixverse6 takes 5s, 8s, 10s or 15s; pixverse5.6 and pixverse5.5 take 5s, 8s or 10s; veo3.1 takes 4s, 6s or 8s; omni-flash takes 10s.
        - `visualContinuity` boolean: Enable visual continuity between consecutive AI-generated scenes.
        - `firstFrameImageUrl` string, uri: Video type only. Mutually exclusive with `referenceImageUrls`.
        - `referenceImageUrl` string, uri: Image type only.
        - `referenceImageUrls` string[]: Reference images that guide the generated visual. The most you can send depends on the model. Video type: up to 4 on pixverse6, pixverse5.6 and pixverse5.5, up to 3 on veo3.1, and 1 on omni-flash. Cannot be sent with `firstFrameImageUrl`. Image type: up to 4 on seedream3.0, nanobanana, nanobanana-pro, nanobanana2 and nanobanana-lite2. flux-schnell does not accept reference images. Cannot be sent with `referenceImageUrl`.
      - `type` 'video' | 'image': Required when `aiVisual` is provided.
      - `searchFilter` SearchFilter
        - `category` string
        - `query` string
        - `keywords` string[]
        - `libraries` string[]
      - `clips` object[]
        - `start` number, required
        - `end` number, required
      - `settings` object
        - `mute` boolean
        - `loop` boolean
        - `zoomAndPan` boolean: Mutually exclusive with `kenBurnsEffect`.
        - `kenBurnsEffect` boolean: Images only. Mutually exclusive with `zoomAndPan`.
      - `brollClip` object
        - `start` number, required
        - `end` number, required
    - `backgroundCorpus` BackgroundCorpusItem[]
      - `visualUrl` string, uri
      - `type` 'image'
      - `prefer` boolean
    - `transcript` TranscriptSentence[]: Transcript of input video/audio. Required for `audioUrl`/`videoUrl`.
      - `speakerId` integer
      - `words` TranscriptWord[], required
        - `word` string, required
        - `start_time` number, required
        - `end_time` number, required: Must be >= start_time.
        - `is_pause` boolean
        - `is_filler` boolean
        - `speakerId` integer
    - `mediaRepurposeSettings` MediaRepurposeSettings: Only valid with `audioUrl` or `videoUrl`.
      - `highlightLength` number
      - `removeFillerWords` boolean
      - `removeSilences` boolean
      - `silenceThresholdSeconds` number
    - `templateOverride` TemplateOverride: Configuration for manipulating template scenes. Only available when `templateId` is provided.
      - `sceneId` string
      - `scenePosition` integer
      - `newScenePosition` integer
      - `insertAfterSceneId` string
      - `insertBeforeSceneId` string
      - `replaceSceneId` string
      - `replaceScenePosition` integer
      - `baseSceneId` string
      - `baseScenePosition` integer
      - `deleteScene` boolean
      - `copyScene` boolean
      - `subtitles` object[]
        - `text` string, required
        - `minimumDuration` number
        - `styleId` string
        - `styleName` string
        - `style` SubtitleStyle: Inline subtitle style. Can be applied at the video level or per scene.
          - `fontUrl` string, uri
          - `fontFamily` string: Font family name. Required when `fontUrl` is provided.
          - `fontSize` integer
          - `color` string: RGBA color.
          - `backgroundColor` string
          - `shadowColor` string
          - `shadowWidth` string
          - `keywordColor` string
          - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
          - `alignment` 'left' | 'center' | 'right'
          - `decorations` string[]
          - `case` 'uppercase' | 'lowercase' | 'capitalize' | 'smallcapitalize'
          - `paragraphWidth` string
          - `animations` TextAnimation[]: Max 2 animations: one entry, one exit.
            - `name` 'none' | 'fade' | 'drift' | 'wipe' | 'text reveal' | 'elastic' | 'typewriter' | 'blur' | 'bulletin', required
            - `type` 'entry' | 'exit', required
            - `speed` 'slow' | 'medium' | 'fast' | 'custom', required
            - `customSpeedValue` number: Required when speed is 'custom'.
            - `direction` 'up' | 'down' | 'left' | 'right'
            - `writingStyle` 'character' | 'word' | 'line' | 'paragraph'
            - `futureWords` 'hidden' | 'subtle' | 'prominent': Only available with `fade` and `blur` entry animations.
      - `layers` array[]
        - object[]
          - `layerId` string
          - `type` 'text' | 'image' | 'video'
          - `text` string
          - `url` string
          - `styleId` string
          - `styleName` string
          - `style` SubtitleStyle: Inline subtitle style. Can be applied at the video level or per scene.
            - `fontUrl` string, uri
            - `fontFamily` string: Font family name. Required when `fontUrl` is provided.
            - `fontSize` integer
            - `color` string: RGBA color.
            - `backgroundColor` string
            - `shadowColor` string
            - `shadowWidth` string
            - `keywordColor` string
            - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
            - `alignment` 'left' | 'center' | 'right'
            - `decorations` string[]
            - `case` 'uppercase' | 'lowercase' | 'capitalize' | 'smallcapitalize'
            - `paragraphWidth` string
            - `animations` TextAnimation[]: Max 2 animations: one entry, one exit.
              - …
          - `visualLibraryId` string
          - `deleteLayer` boolean
    - `elements` SceneElement[]: Overlay elements (shapes, text, videos, images) placed on top of the scene background.
      - `type` 'shape' | 'text' | 'video' | 'image', required
      - `name` string: Shape only (required): shape name, e.g. rectangle, circle, badge-3.
      - `fill` string: Shape only: fill color.
      - `stroke` string: Shape only: outline color.
      - `strokeWidth` number: Shape only: outline thickness in pixels.
      - `borderRadius` number: Shape only: corner radius (rectangle only).
      - `text` string: Text only (required): the text to display.
      - `textVariant` 'heading' | 'subheading' | 'body': Text only: decorative preset. Defaults to body.
      - `style` SubtitleStyle: Text only: style overrides.
        - `fontUrl` string, uri
        - `fontFamily` string: Font family name. Required when `fontUrl` is provided.
        - `fontSize` integer
        - `color` string: RGBA color.
        - `backgroundColor` string
        - `shadowColor` string
        - `shadowWidth` string
        - `keywordColor` string
        - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Preset 3x3 grid position.
        - `alignment` 'left' | 'center' | 'right'
        - `decorations` string[]
        - `case` 'uppercase' | 'lowercase' | 'capitalize' | 'smallcapitalize'
        - `paragraphWidth` string
        - `animations` TextAnimation[]: Max 2 animations: one entry, one exit.
          - `name` 'none' | 'fade' | 'drift' | 'wipe' | 'text reveal' | 'elastic' | 'typewriter' | 'blur' | 'bulletin', required
          - `type` 'entry' | 'exit', required
          - `speed` 'slow' | 'medium' | 'fast' | 'custom', required
          - `customSpeedValue` number: Required when speed is 'custom'.
          - `direction` 'up' | 'down' | 'left' | 'right'
          - `writingStyle` 'character' | 'word' | 'line' | 'paragraph'
          - `futureWords` 'hidden' | 'subtle' | 'prominent': Only available with `fade` and `blur` entry animations.
      - `visualUrl` string, uri: Media only: URL of the video or image file to overlay.
      - `searchFilter` object: Media only: stock library search. If no match is found, the element is skipped.
        - `query` string, required: What to search for, in plain language.
      - `aiVisual` AiVisual: Media only: generate the element with AI. Consumes AI Credits according to the selected model's rate.
        - `prompt` string
        - `model` 'flux-schnell' | 'seedream3.0' | 'nanobanana' | 'nanobanana-pro' | 'nanobanana2' | 'nanobanana-lite2' | 'pixverse5.5' | 'pixverse5.6' | 'pixverse6' | 'omni-flash' | 'veo3.1', required: AI model. Image models: flux-schnell, seedream3.0, nanobanana, nanobanana-pro, nanobanana2, nanobanana-lite2. Video models: pixverse5.5, pixverse5.6, pixverse6, omni-flash, veo3.1.
        - `mediaStyle` 'photorealistic' | 'artistic' | 'cartoon' | 'minimalist' | 'vintage' | 'futuristic': Image type only.
        - `videoDuration` string: Video clip duration. Video type only. Valid values depend on the model: pixverse6 takes 5s, 8s, 10s or 15s; pixverse5.6 and pixverse5.5 take 5s, 8s or 10s; veo3.1 takes 4s, 6s or 8s; omni-flash takes 10s.
        - `visualContinuity` boolean: Enable visual continuity between consecutive AI-generated scenes.
        - `firstFrameImageUrl` string, uri: Video type only. Mutually exclusive with `referenceImageUrls`.
        - `referenceImageUrl` string, uri: Image type only.
        - `referenceImageUrls` string[]: Reference images that guide the generated visual. The most you can send depends on the model. Video type: up to 4 on pixverse6, pixverse5.6 and pixverse5.5, up to 3 on veo3.1, and 1 on omni-flash. Cannot be sent with `firstFrameImageUrl`. Image type: up to 4 on seedream3.0, nanobanana, nanobanana-pro, nanobanana2 and nanobanana-lite2. flux-schnell does not accept reference images. Cannot be sent with `referenceImageUrl`.
      - `settings` object: Video elements only: playback settings.
        - `loop` boolean
        - `mute` boolean
      - `colorOverlay` ColorOverlay: Media only: color tint applied to this element.
        - `color` string, required: Tint color in RGB, RGBA, or hex format.
        - `opacity` number: Tint strength from 0 (invisible) to 1 (solid).
      - `position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right': Anchor preset. Mutually exclusive with `top`/`left`.
      - `top` string: Vertical offset percentage, e.g. "10%". Mutually exclusive with `position`.
      - `left` string: Horizontal offset percentage, e.g. "10%". Mutually exclusive with `position`.
      - `width` string: Element width as a percentage of the canvas, e.g. "30%". Media elements without a width are sized automatically to stay fully on screen.
  - `payloadUrl` string: Optional URL to fetch a payload (backend-supported field).
  - `projectMetadata` object: Arbitrary metadata stored with the saved project.

## Response `200`

Job successfully created

- JobCreatedResponse
  - `success` boolean: Indicates whether the request was successful
  - `data` object
    - `jobId` string, uuid: Unique identifier for the created job. Use this with the Get Video Render Job by ID endpoint.

## Other responses

- `400`: Invalid request body
- `401`: Unauthorized
- `500`: Internal server error

## Changes

- **2026-11-19** `9270a2874dc2`: 4 breaking, 15 info
  - removed the enum value `veo3.1_fast` of the request property `scenes/items/background/aiVisual/model`
  - removed the enum value `veo3.1_fast` of the request property `scenes/items/backgroundBrolls/items/allOf[#/components/schemas/Background]/aiVisual/model`
  - removed the enum value `veo3.1_fast` of the request property `scenes/items/elements/items/aiVisual/model`
  - removed the enum value `veo3.1_fast` of the request property `scenes/items/pptSlideAnimation/model`
  - …15 more
- **2026-10-12** `e820d5b9e59f`: 1 breaking, 4 info
  - the `scenes/items/backgroundMusic` request property dependentRequired was added: when `volume` is present, `musicUrl` are required
  - added the new optional request property `scenes/items/backgroundMusic/musicUrl`
  - added the new optional request property `scenes/items/backgroundMusic/volume`
  - added `subschema #1, subschema #2` to the `scenes/items/backgroundMusic` request property `anyOf` list
  - …1 more
- **2026-09-10** `561305b95e02`: 1 warning, 1 info
  - removed the request property `scenes/items/animatePPT`
  - added the new optional request property `scenes/items/pptSlideAnimation`
- **2026-09-03** `e7266f1de626`: 1 warning, 2 info
  - removed the request property `scenes/items/storyCoPilot`
  - added the new optional request property `aiStoryboard`
  - added the new optional request property `scenes/items/brief`

[Operation history](https://skmtc.dev/pictory/apis/pictory-api/changes/pictoryapis/v2/video/storyboard/post.md)

---

[API](https://skmtc.dev/pictory/apis/pictory-api.md) - [All operations](https://skmtc.dev/pictory/apis/pictory-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pictory/apis/pictory-api/revisions/9270a2874dc2?raw)
