Create Storyboard from Text

Storyboard API is first step in sequence of APIs which requests Pictory to generate Video Preview from text, audio or video. This is asynchronous REST API.

Storyboard API

This API allows you to generate or edit videos based on different content inputs. For example, if you have an article/blog, you can turn it into a video by providing the webpage's URL. Various use-cases for which you can use storyboard API are listed below:

  1. Initiate New Video Request from Text/Article/Blog.
  2. Add generated transcription to the existing video.
  3. Request for Video Summary from the existing transcription.
  4. Convert Podcast to Video.

The Storyboard API also supports SSML tags for text-to-video use-case. These tags are supported by the text attribute of scenes object.

Request Header

Parameter NameParameter TypeDescription
AuthorizationString (Required)An authorization Token is required to call the Storyboard API. Authentication API. Contact [email protected] to get access to Authentication API.
X-Pictory-User-IdString (Required)You can obtain X-Pictory-User-Id by reaching out to us at [email protected]

Request Body

Parameter Name

Parameter Type

Description

videoName

Text (Required)

Name of the Output Video File. It should be a valid text string that can be used to create a proper file on the computer.

language

Choice (Optional)

More details here

webhook

Text (Optional)

Callback URL where the Storyboard Job completion response will be delivered.

brandLogo

Brand Logo Object

This object specifies the URL of the brand logo to be used and its position within the video. More details here

autoHighlightKeywords

Boolean

This flag is used to highlight keywords for the subtitle text. To disable this feature use thefalse value for this parameter in the API request.

audio

Audio Object

Audio Settings of the Video

scenes

Scenes Array

textStyles

TextStyles
Object

Default Text Style Object to be used for subtitles for each scene object. More details here

videoWidth

Text (Optional)

Width of Output Video file (video resolution width)

videoHeight

Text (Optional)

Height of Output Video file (video resolution width)

Brand Logo

This object specifies the URL of the brand logo to be used and its position within the video. It allows for consistent branding by placing the logo at a designated location in the video content.

Parameter Name

Parameter Type

Description

url

text

The public URL of the Brand Logo.

verticalAlignment

Choice
Default Value: top

Specifies the vertical alignment of the logo within the video frame
Acceptable Values are: top,center, bottom

horizontalAlignment

Choice
Default Value: right

Specifies the horizontal alignment of the logo within the video frame
Acceptable Values are: left, center, right

width

text (Optional)
Default value: 10%

Width is a percentage value. The height would be calculated based on the width percentage.

Text Styles

This object defines the default text styles applied to each Scene object. These default styles ensure a consistent look and feel across all scenes. However, the text style values can be customized and overridden at the individual scene level to accommodate specific design requirements.

Parameter Name

Parameter Type

Description

fontUrl

URL (Optional)

URL to a valid .ttf font file.

fontFamily

Choice.
Default value: Arial

Font of the Text. The supported Font list is mentioned here.

fontWeight

Choice.
Default Value: normal

Choice.
Default Value: normal

textColor

text
Default Value: #FFFFFF

Color of the Text in hex-code (eg: #FFFFFF or rgba(255,255,255,1))

fontSize

Integer
Default Value: 24

Font Size of the text.

keywordColor

text
Default Value: ## e2e2aad9

Color of the highlighted keyword in the subtitle text.

textBackgroundColor

text
Default Value:
#111111

The background color of the subtitle in hex-code (e.g: #FFFFFF or rgba(255,255,255,1))

textShadowColor

text

The shadow color of the text is in hex-code.

verticalAlignment

Choice
Default Value: bottom

Vertical Alignment of the text.
Acceptable Values: top,center, bottom

horizontalAlignment

Choice
Default Value: left

Horizontal Alignment of the text.
Acceptable Values: left, center, right

Response Body

The Storyboard API requests Pictory Server to generate a Video Preview and since this API is asynchronous, it returns job_id in response.

To be notified when a Video Preview is available, you can poll the GET /v1/job/job_id endpoint. Once the video preview job is completed, GET Job API returns a video preview URL and render_settings in response. Video Render settings returned in this response can be used to generate video in .mp4 format using /v1/video/render API.

Sample Request

curl --request POST \
     --url https://api.pictory.ai/api/v1/video/storyboard \
     --header 'Authorization: YOUR_AUTH_KEY' \
     --header 'X-Pictory-User-Id: YOUR_USER_ID' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
   "videoName": "Santa Claus",
  "videoDescription": "Santa Claus is coming to town.",
  "language": "en",

  "audio": {
    "aiVoiceOver": {
      "speaker": "Jackson",
      "speed": "100",
      "amplifyLevel": "0"
    },
    "autoBackgroundMusic": true,
    "backGroundMusicVolume": 0.5
  },
  "textStyles": {
        "fontFamily": "Arial",
        "textColor": "#FFFFFF",
        "fontSize": 32,
        "keywordColor": "#6339F8",
        "textBackgroundColor": "#000000",
        "verticalAlignment": "bottom",
        "horizontalAlignment": "center"
  },
  "brandLogo": {
    "url":"https://pictory.ai/wp-content/uploads/2022/03/logo-new-fon-2t.png", 
    "verticalAlignment": "top" , 
    "horizontalAlignment": "right"
  },
  "scenes": [
    {
      "text": "In the North Pole, beneath the shimmering stars, Santa Claus, with a merry twinkle in his eyes, gears up for his Christmas ride. His workshop buzzes as elves craft toys, while Santa, in his festive red suit, checks his list of children worldwide. Come Christmas Eve, Santa and his reindeer, guided by Rudolph's bright nose whisk through the sky with Santa's sleigh brimming with gifts. At every stop, Santa descends chimneys, leaves presents, and heartily nibbles on cookies. With the break of dawn, Santa returns home leaving behind a world infused with Christmas magic and love",
      "voiceOver": true,
      "splitTextOnNewLine": true,
      "splitTextOnPeriod": true
    }
  ]
}
Language
Click Try It! to start a request and see the response here!