Saved Subtitle Styles

This guide shows you how to apply saved subtitle styles to your videos for consistent caption formatting. You can use subtitle styles saved in your Pictory account at both video and scene levels.

What You’ll Learn

Saved Styles

Use pre-configured subtitle styles by name or ID

Video-Level Styles

Apply default styles to all scenes

Scene-Level Override

Customize specific scenes with different styles

Flexible Selection

Choose between style name or ID

Before You Begin

Make sure you have:

A Pictory API key
Node.js or Python installed on your machine
Subtitle style created in your Pictory account
Subtitle style name or ID from your Pictory settings

npm install axios

pip install requests

How Subtitle Styles Work

When you apply subtitle styles to your video:

Style Selection - You specify the style by name or ID
Video-Level Application - Style is set as default for all scenes
Scene-Level Override - Individual scenes can use different styles
Automatic Formatting - All subtitle properties are applied consistently
Video Rendering - Captions appear with your chosen formatting

Subtitle styles must be created in your Pictory account before using them via the API. Scene-level styles override video-level styles for that specific scene.

Complete Example

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY";

const STORY_TEXT_1 = "AI is poised to significantly impact educators and course creators on social media.";
const STORY_TEXT_2 = "By automating tasks like content generation, visual design, and video editing, AI will save time and enhance consistency.";

async function createVideoWithSubtitleStyles() {
  try {
    console.log("Creating video with subtitle styles...");

    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_subtitle_style",

        // Video-level subtitle style (default for all scenes)
        subtitleStyleName: "{YOUR_STYLE_NAME}",  // Use style name OR ID, not both

        scenes: [
          {
            story: STORY_TEXT_1,
            createSceneOnNewLine: false,
            createSceneOnEndOfSentence: false,
            // This scene uses the video-level subtitle style
          },
          {
            story: STORY_TEXT_2,
            createSceneOnNewLine: false,
            createSceneOnEndOfSentence: false,
            // Scene-level override with different style
            subtitleStyleName: "{DIFFERENT_STYLE_NAME}",
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

    const jobId = response.data.data.jobId;
    console.log("✓ Video creation started!");
    console.log("Job ID:", jobId);

    // Monitor progress
    console.log("\nMonitoring video creation...");
    let jobCompleted = false;
    let jobResult = null;

    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        {
          headers: { Authorization: API_KEY },
        }
      );

      const status = statusResponse.data.data.status;
      console.log("Status:", status);

      if (status === "completed") {
        jobCompleted = true;
        jobResult = statusResponse.data;
        console.log("\n✓ Video with subtitle styles is ready!");
        console.log("Video URL:", jobResult.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
      }

      await new Promise(resolve => setTimeout(resolve, 5000));
    }

    return jobResult;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
    throw error;
  }
}

createVideoWithSubtitleStyles();

import requests
import time
import json

API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
API_KEY = 'YOUR_API_KEY'

STORY_TEXT_1 = "AI is poised to significantly impact educators and course creators on social media."
STORY_TEXT_2 = "By automating tasks like content generation, visual design, and video editing, AI will save time and enhance consistency."

def create_video_with_subtitle_styles():
    try:
        print("Creating video with subtitle styles...")

        response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'text_to_video_subtitle_style',

                # Video-level subtitle style (default for all scenes)
                'subtitleStyleName': '{YOUR_STYLE_NAME}',  # Use style name OR ID, not both

                'scenes': [
                    {
                        'story': STORY_TEXT_1,
                        'createSceneOnNewLine': False,
                        'createSceneOnEndOfSentence': False
                        # This scene uses the video-level subtitle style
                    },
                    {
                        'story': STORY_TEXT_2,
                        'createSceneOnNewLine': False,
                        'createSceneOnEndOfSentence': False,
                        # Scene-level override with different style
                        'subtitleStyleName': '{DIFFERENT_STYLE_NAME}'
                    }
                ]
            },
            headers={
                'Content-Type': 'application/json',
                'Authorization': API_KEY
            }
        )
        response.raise_for_status()

        job_id = response.json()['data']['jobId']
        print("✓ Video creation started!")
        print(f"Job ID: {job_id}")

        # Monitor progress
        print("\nMonitoring video creation...")
        job_completed = False
        job_result = None

        while not job_completed:
            status_response = requests.get(
                f'{API_BASE_URL}/v1/jobs/{job_id}',
                headers={'Authorization': API_KEY}
            )
            status_response.raise_for_status()

            status = status_response.json()['data']['status']
            print(f"Status: {status}")

            if status == 'completed':
                job_completed = True
                job_result = status_response.json()
                print("\n✓ Video with subtitle styles is ready!")
                print(f"Video URL: {job_result['data']['videoURL']}")
            elif status == 'failed':
                raise Exception(f"Video creation failed: {status_response.json()}")

            time.sleep(5)

        return job_result

    except requests.exceptions.RequestException as error:
        print(f"Error: {error}")
        if hasattr(error, 'response') and error.response is not None:
            print(f"Response: {error.response.text}")
        raise

if __name__ == '__main__':
    create_video_with_subtitle_styles()

Understanding the Parameters

Video-Level Parameters

Parameter	Type	Required	Description
`subtitleStyleName`	string	No	Name of saved subtitle style (use this OR subtitleStyleId, not both)
`subtitleStyleId`	string	No	ID of saved subtitle style (use this OR subtitleStyleName, not both)

Scene-Level Parameters

Parameter	Type	Required	Description
`scenes[].subtitleStyleName`	string	No	Override video-level style for this scene using style name
`scenes[].subtitleStyleId`	string	No	Override video-level style for this scene using style ID

Cannot Use Both TogetherYou must choose either subtitleStyleId OR subtitleStyleName - never both at the same time:❌ WRONG:

{
  "subtitleStyleId": "8f3deae9-fe38-4c53-8be0-616bef1da916",
  "subtitleStyleName": "Navy blue"
}

✅ CORRECT (choose one):

{ "subtitleStyleId": "8f3deae9-fe38-4c53-8be0-616bef1da916" }

{ "subtitleStyleName": "Navy blue" }

Additional Rules:

This mutual exclusivity applies at both video level and scene level
Scene-level styles completely override video-level styles
The style must exist in your Pictory account
Style names and IDs are account-specific

Style Name vs Style ID

Choose the right method for your use case:

Use Case	Recommendation	Why
Human-readable code	Use `subtitleStyleName`	Easier to read and maintain
Programmatic references	Use `subtitleStyleId`	Guaranteed stability if style is renamed
Style names might change	Use `subtitleStyleId`	IDs remain constant even if name changes
Easier debugging	Use `subtitleStyleName`	Clear what style you are using from the name
API automation	Use `subtitleStyleId`	More reliable for automated systems

What Subtitle Styles Include

Subtitle styles configure all caption formatting elements:

Element	What It Controls
Font	Font family, size, and weight
Colors	Text color, background color, keyword highlight color
Position	Vertical and horizontal placement on screen
Alignment	Left, center, or right text alignment
Decorations	Bold, italic, underline, strikethrough
Effects	Shadow, outline, and glow settings
Animations	Entry and exit animation effects
Layout	Paragraph width and spacing

Finding Your Subtitle Styles

Option 1: Using the Pictory Web Interface

Log in to your Pictory account
Navigate to Subtitle Styles or Settings
View your saved subtitle styles
Note the style name or ID for API use

Option 2: Using the API

Retrieve all your saved subtitle styles programmatically:

const stylesResponse = await axios.get(
  `${API_BASE_URL}/v1/styles`,
  { headers: { Authorization: API_KEY } }
);

console.log('Your subtitle styles:');
stylesResponse.data.forEach(style => {
  console.log(`- Name: ${style.name}`);
  console.log(`  ID: ${style.id}`);
});

// Use either the 'name' or 'id' field

styles_response = requests.get(
    f'{API_BASE_URL}/v1/styles',
    headers={'Authorization': API_KEY}
)

print('Your subtitle styles:')
for style in styles_response.json():
    print(f"- Name: {style['name']}")
    print(f"  ID: {style['id']}")

# Use either the 'name' or 'id' field

See Get Text Styles for complete API documentation.

Common Use Cases

Consistent Branding Across Videos

{
  videoName: "company_announcement",
  subtitleStyleName: "Corporate Blue"
}

Result: All videos use the same professional subtitle styling.

Different Styles for Different Scenes

{
  subtitleStyleName: "Standard Style",  // Default for most scenes
  scenes: [
    {
      story: "Introduction text",
      // Uses default "Standard Style"
    },
    {
      story: "Important announcement",
      subtitleStyleName: "Bold Emphasis"  // Override for this scene
    },
    {
      story: "Conclusion text",
      // Back to default "Standard Style"
    }
  ]
}

Result: Most scenes use standard styling, one scene uses bold emphasis for importance.

Style by ID for Stability

{
  subtitleStyleId: "8f3deae9-fe38-4c53-8be0-616bef1da916"
}

Result: Style applied by ID remains correct even if style is renamed.

Best Practices

Create Reusable Style Presets

Build a library of subtitle styles for different use cases:

Corporate: Professional styles for business content
Social Media: Casual, eye-catching styles for social platforms
Educational: Clear, readable styles for learning content
Marketing: Bold, attention-grabbing styles for promotions
Accessibility: High-contrast styles for better readability

This allows quick style selection based on video type.

Use Descriptive Style Names

Name your subtitle styles clearly:

Good: “Bold White on Black”, “Casual Yellow Highlight”
Avoid: “Style1”, “New”, “Test”

Clear names make it easier to select the right style and maintain your code.

Test Styles Before Production

Before using a subtitle style via API:

Create a test video in the Pictory web interface
Verify the style looks as expected
Check readability on different backgrounds
Test on various video types
Make adjustments in Pictory settings if needed

Choose Name or ID Consistently

Decide on a strategy and stick with it:

Style Names: If you rarely rename styles and want readable code
Style IDs: If styles might be renamed or for automated systems
Document Choice: Note in your codebase which method you are using
Team Alignment: Ensure whole team uses same approach

Use Scene-Level Overrides Sparingly

Apply scene-specific styles strategically:

Emphasis: Use different style for important messages
Sections: Different styles for intro, main content, outro
Consistency: Do not change styles too frequently
Purpose: Each style change should have clear intent
Testing: Preview videos to ensure style changes feel natural

Troubleshooting

Error: Style not found

Problem: API returns error that subtitle style does not exist.Solution:

Verify style name is spelled exactly as saved in Pictory
Check for case sensitivity (e.g., “Bold” vs “bold”)
Use Get Text Styles API to see all available styles
Ensure the style exists in your account
Try using style ID instead of name

Video uses wrong subtitle style

Problem: Captions appear with different formatting than expected.Solution:

Double-check the style name or ID in your request
Ensure you are not using both name and ID (use only one)
Verify the style hasn’t been modified in Pictory
Check for scene-level overrides that might be applying
Review completed video to confirm issue

Scene-level style not applying

Problem: Scene uses video-level style instead of scene-level override.Solution:

Ensure scene-level style parameter is inside the scene object
Check JSON syntax is correct (commas, brackets, quotes)
Verify scene-level style name or ID is valid
Make sure you are not mixing name and ID parameters
Test with a simple example first

Cannot decide between name and ID

Problem: Unsure whether to use subtitleStyleName or subtitleStyleId.Solution:

Use Name if: You want readable code and rarely rename styles
Use ID if: Styles might be renamed or you need guaranteed stability
Use ID if: Building automated systems with programmatic references
Use Name if: Working on small projects with few styles
Either works - choose based on your specific needs

Style looks different than in Pictory UI

Problem: Subtitle styling via API does not match Pictory interface.Solution:

Confirm you are using the correct style name or ID
Check that the style hasn’t been modified since testing
Ensure no other parameters are overriding style settings
Use Get Text Styles API to verify style configuration
Test the same style in Pictory UI to compare

Next Steps

Explore more subtitle customization options:

Custom Subtitle Style

Create inline styles without saving presets

Highlight Keywords

Emphasize important words automatically

Brand Settings

Use complete brand presets including styles

Custom Captions

Add custom caption text separate from story

API Reference

For complete technical details, see:

Get Text Styles - List all available subtitle styles
Render Storyboard Video - Full API specification
Get Job Status - Monitor job status and progress

​What You’ll Learn

Saved Styles

Video-Level Styles

Scene-Level Override

Flexible Selection

​Before You Begin

​How Subtitle Styles Work

​Complete Example

​Understanding the Parameters

​Video-Level Parameters

​Scene-Level Parameters

​Style Name vs Style ID

​What Subtitle Styles Include

​Finding Your Subtitle Styles

​Option 1: Using the Pictory Web Interface

​Option 2: Using the API

​Common Use Cases

​Consistent Branding Across Videos

​Different Styles for Different Scenes

​Style by ID for Stability

​Best Practices

​Troubleshooting

​Next Steps

Custom Subtitle Style

Highlight Keywords

Brand Settings

Custom Captions

​API Reference

What You’ll Learn

Before You Begin

How Subtitle Styles Work

Complete Example

Understanding the Parameters

Video-Level Parameters

Scene-Level Parameters

Style Name vs Style ID

What Subtitle Styles Include

Finding Your Subtitle Styles

Option 1: Using the Pictory Web Interface

Option 2: Using the API

Common Use Cases

Consistent Branding Across Videos

Different Styles for Different Scenes

Style by ID for Stability

Best Practices

Troubleshooting

Next Steps

API Reference