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
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
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 |
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’re 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:Common Use Cases
Consistent Branding Across Videos
Different Styles for Different Scenes
Style by ID for Stability
Best Practices
Create Reusable Style Presets
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
Use Descriptive Style Names
Use Descriptive Style Names
Name your subtitle styles clearly:
- Good: “Bold White on Black”, “Casual Yellow Highlight”
- Avoid: “Style1”, “New”, “Test”
Test Styles Before Production
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
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’re using
- Team Alignment: Ensure whole team uses same approach
Use Scene-Level Overrides Sparingly
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: Don’t 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
Error: Style not found
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
Video uses wrong subtitle style
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’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
Scene-level style not applying
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’re not mixing name and ID parameters
- Test with a simple example first
Cannot decide between name and ID
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
Style looks different than in Pictory UI
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: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
