Skip to main content
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 (get one here)
  • 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

How Subtitle Styles Work

When you apply subtitle styles to your video:
  1. Style Selection - You specify the style by name or ID
  2. Video-Level Application - Style is set as default for all scenes
  3. Scene-Level Override - Individual scenes can use different styles
  4. Automatic Formatting - All subtitle properties are applied consistently
  5. 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();

Understanding the Parameters

Video-Level Parameters

ParameterTypeRequiredDescription
subtitleStyleNamestringNoName of saved subtitle style (use this OR subtitleStyleId, not both)
subtitleStyleIdstringNoID of saved subtitle style (use this OR subtitleStyleName, not both)

Scene-Level Parameters

ParameterTypeRequiredDescription
scenes[].subtitleStyleNamestringNoOverride video-level style for this scene using style name
scenes[].subtitleStyleIdstringNoOverride 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" }
OR
{ "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 CaseRecommendationWhy
Human-readable codeUse subtitleStyleNameEasier to read and maintain
Programmatic referencesUse subtitleStyleIdGuaranteed stability if style is renamed
Style names might changeUse subtitleStyleIdIDs remain constant even if name changes
Easier debuggingUse subtitleStyleNameClear what style you’re using from the name
API automationUse subtitleStyleIdMore reliable for automated systems

What Subtitle Styles Include

Subtitle styles configure all caption formatting elements:
ElementWhat It Controls
FontFont family, size, and weight
ColorsText color, background color, keyword highlight color
PositionVertical and horizontal placement on screen
AlignmentLeft, center, or right text alignment
DecorationsBold, italic, underline, strikethrough
EffectsShadow, outline, and glow settings
AnimationsEntry and exit animation effects
LayoutParagraph width and spacing

Finding Your Subtitle Styles

Option 1: Using the Pictory Web Interface

  1. Log in to your Pictory account
  2. Navigate to Subtitle Styles or Settings
  3. View your saved subtitle styles
  4. 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
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

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.
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.
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
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’re using
  • Team Alignment: Ensure whole team uses same approach
Apply scene-specific styles strategically:
  • Emphasis: Use different style for important messages
  • Sections: Different styles for intro, main content, outro
  • Consistency: Don’t change styles too frequently
  • Purpose: Each style change should have clear intent
  • Testing: Preview videos to ensure style changes feel natural

Troubleshooting

Problem: API returns error that subtitle style doesn’t 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
Problem: Captions appear with different formatting than expected.Solution:
  • Double-check the style name or ID in your request
  • Ensure you’re 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
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’re not mixing name and ID parameters
  • Test with a simple example first
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
Problem: Subtitle styling via API doesn’t match Pictory interface.Solution:
  • Confirm you’re 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:

API Reference

For complete technical details, see: