> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved Subtitle Styles

> Apply saved subtitle styles to maintain consistent caption formatting across videos

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

<CardGroup cols={2}>
  <Card title="Saved Styles" icon="closed-captioning">
    Use pre-configured subtitle styles by name or ID
  </Card>

  <Card title="Video-Level Styles" icon="video">
    Apply default styles to all scenes
  </Card>

  <Card title="Scene-Level Override" icon="layer-group">
    Customize specific scenes with different styles
  </Card>

  <Card title="Flexible Selection" icon="circle-question">
    Choose between style name or ID
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Subtitle style created in your Pictory account
* Subtitle style name or ID from your Pictory settings

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## 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

<Note>
  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.
</Note>

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## 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   |

<Warning>
  **Cannot Use Both Together**

  You must choose either `subtitleStyleId` OR `subtitleStyleName` - never both at the same time:

  ❌ **WRONG:**

  ```json theme={null}
  {
    "subtitleStyleId": "8f3deae9-fe38-4c53-8be0-616bef1da916",
    "subtitleStyleName": "Navy blue"
  }
  ```

  ✅ **CORRECT (choose one):**

  ```json theme={null}
  { "subtitleStyleId": "8f3deae9-fe38-4c53-8be0-616bef1da916" }
  ```

  OR

  ```json theme={null}
  { "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
</Warning>

## 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

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:

<CodeGroup>
  ```javascript Node.js theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

See [Get Text Styles](/api-reference/branding/get-text-styles) for complete API documentation.

## Common Use Cases

### Consistent Branding Across Videos

```javascript theme={null}
{
  videoName: "company_announcement",
  subtitleStyleName: "Corporate Blue"
}
```

**Result:** All videos use the same professional subtitle styling.

### Different Styles for Different Scenes

```javascript theme={null}
{
  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

```javascript theme={null}
{
  subtitleStyleId: "8f3deae9-fe38-4c53-8be0-616bef1da916"
}
```

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

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

Explore more subtitle customization options:

<CardGroup cols={2}>
  <Card title="Custom Subtitle Style" icon="font" href="/guides/branding-customization/custom-subtitle-style">
    Create inline styles without saving presets
  </Card>

  <Card title="Highlight Keywords" icon="highlighter" href="/guides/branding-customization/highlight-keywords">
    Emphasize important words automatically
  </Card>

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Use complete brand presets including styles
  </Card>

  <Card title="Custom Captions" icon="closed-captioning" href="/guides/text-to-video/text-to-video-captions">
    Add custom caption text separate from story
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

* [Get Text Styles](/api-reference/branding/get-text-styles) - List all available subtitle styles
* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full API specification
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and progress