Skip to main content
This guide shows you how to create videos with completely custom subtitle styles defined directly in your API request. Instead of using saved presets, you can specify all styling properties inline for maximum flexibility.

What You’ll Learn

Inline Styles

Define custom styles directly in API requests

Full Control

Customize fonts, colors, positions, and effects

No Presets Needed

Style without saving configurations

Animation Options

Add entry and exit animations

Before You Begin

Make sure you have:
  • A Pictory API key (get one here)
  • Node.js or Python installed on your machine
  • Basic understanding of colors (RGBA format)
  • Familiarity with subtitle positioning
npm install axios

How Custom Subtitle Styling Works

When you define subtitle styles inline:
  1. Style Definition - You specify all subtitle properties in your request
  2. Property Application - Font, colors, position, and effects are configured
  3. Animation Setup - Entry and exit animations are applied (optional)
  4. No Saving Required - Style exists only for this video (not saved to account)
  5. Video Rendering - Subtitles render with your exact specifications
Inline subtitle styles give you complete control without creating saved presets. This is perfect for one-time custom styling or testing different subtitle configurations.

Complete Example

import axios from "axios";

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

const SAMPLE_TEXT = "AI is poised to significantly impact educators and course creators on social media.";

async function createVideoWithCustomSubtitleStyle() {
  try {
    console.log("Creating video with custom subtitle style...");

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

        // Custom inline subtitle style
        subtitleStyle: {
          // Font settings
          fontFamily: "Poppins",
          fontSize: 48,

          // Colors (RGBA format)
          color: "rgba(255, 255, 255, 1)",              // White text
          backgroundColor: "rgba(0, 0, 0, 0.7)",        // Semi-transparent black background
          keywordColor: "rgba(255, 215, 0, 1)",         // Gold for keywords
          shadowColor: "rgba(0, 0, 0, 0.8)",            // Dark shadow
          shadowWidth: "2%",

          // Position and layout
          position: "bottom-center",
          alignment: "center",
          paragraphWidth: "80%",

          // Text styling
          decorations: ["bold"],
          case: "capitalize",

          // Animations
          animations: [
            {
              name: "fade",
              type: "entry",
              speed: "medium",
            },
            {
              name: "fade",
              type: "exit",
              speed: "fast",
            },
          ],
        },

        scenes: [
          {
            story: SAMPLE_TEXT,
            createSceneOnNewLine: false,
            createSceneOnEndOfSentence: false,
          },
        ],
      },
      {
        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 custom subtitle style 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;
  }
}

createVideoWithCustomSubtitleStyle();

Subtitle Style Parameters

Font Properties

PropertyTypeDescriptionExample
fontFamilystringFont name”Poppins”, “Arial”, “Roboto”
fontUrlstringCustom font URL (optional)https://example.com/font.woff2
fontSizenumberFont size in pixels48, 36, 60

Color Properties

All colors use RGBA format: rgba(R, G, B, A) where R/G/B are 0-255 and A is 0-1
PropertyDescriptionExample
colorMain text colorrgba(255, 255, 255, 1) (white)
backgroundColorBackground behind textrgba(0, 0, 0, 0.7) (semi-transparent black)
keywordColorColor for highlighted keywordsrgba(255, 215, 0, 1) (gold)
shadowColorText shadow colorrgba(0, 0, 0, 0.8) (dark gray)

Position and Layout

PropertyTypeOptions/Description
positionstringtop-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right
alignmentstringleft, center, right
paragraphWidthstringPercentage of screen width (e.g., “80%”, “100%“)
shadowWidthstringShadow size as percentage (e.g., “2%”, “5%“)

Text Styling

PropertyTypeOptions
decorationsarray["bold"], ["underline"], ["italics"], ["linethrough"] (can combine multiple)
casestringuppercase, lowercase, capitalize, smallcapitalize

Animation Options

You can add up to 2 animations per subtitle style (one entry, one exit).

Available Animations

Animation NameTypeDescription
noneEntry/ExitNo animation
fadeEntry/ExitGradual fade in or out
driftEntry/ExitDrift motion with fade
wipeEntry/ExitWipe across screen
text revealEntryText reveals character by character
elasticEntryElastic bounce effect
typewriterEntryTypewriter effect
blurEntry/ExitBlur transition
bulletinEntryBulletin board style

Animation Configuration

PropertyOptionsDescription
namestringAnimation name from table above
typestringentry (appearing) or exit (disappearing)
speedstringslow, medium, fast, custom
directionstringup, down, left, right (for directional animations)

RGBA Color Format

rgba(R, G, B, A)
ComponentRangeDescription
R (Red)0-255Red intensity
G (Green)0-255Green intensity
B (Blue)0-255Blue intensity
A (Alpha)0-1Transparency (0 = transparent, 1 = opaque)

Common Colors

ColorRGBA Value
Whitergba(255, 255, 255, 1)
Blackrgba(0, 0, 0, 1)
Semi-transparent blackrgba(0, 0, 0, 0.7)
Goldrgba(255, 215, 0, 1)
Redrgba(255, 0, 0, 1)
Bluergba(0, 120, 255, 1)
Greenrgba(34, 197, 94, 1)
Use online RGBA color pickers to easily create color values for your custom styles.

Common Use Cases

Professional Business Subtitles

{
  subtitleStyle: {
    fontFamily: "Roboto",
    fontSize: 42,
    color: "rgba(255, 255, 255, 1)",
    backgroundColor: "rgba(0, 0, 0, 0.8)",
    position: "bottom-center",
    decorations: ["bold"]
  }
}
Result: Clean, professional subtitles with strong readability.

Social Media Style

{
  subtitleStyle: {
    fontFamily: "Poppins",
    fontSize: 56,
    color: "rgba(255, 255, 255, 1)",
    keywordColor: "rgba(255, 215, 0, 1)",
    backgroundColor: "rgba(0, 0, 0, 0)",
    shadowColor: "rgba(0, 0, 0, 1)",
    shadowWidth: "3%",
    position: "center-center",
    case: "uppercase",
    decorations: ["bold"]
  }
}
Result: Eye-catching subtitles perfect for TikTok, Instagram Reels.

Educational Content

{
  subtitleStyle: {
    fontFamily: "Arial",
    fontSize: 40,
    color: "rgba(0, 0, 0, 1)",
    backgroundColor: "rgba(255, 255, 255, 0.9)",
    position: "bottom-center",
    alignment: "center",
    paragraphWidth: "90%",
    decorations: []
  }
}
Result: High-contrast, easy-to-read subtitles for learning materials.

Animated Dynamic Subtitles

{
  subtitleStyle: {
    fontFamily: "Montserrat",
    fontSize: 48,
    color: "rgba(255, 255, 255, 1)",
    backgroundColor: "rgba(0, 0, 0, 0.6)",
    position: "bottom-center",
    animations: [
      { name: "typewriter", type: "entry", speed: "fast" },
      { name: "fade", type: "exit", speed: "medium" }
    ]
  }
}
Result: Engaging subtitles with typewriter entry and fade exit.

Best Practices

Select fonts and sizes for optimal readability:
  • Font Size: 36-56 pixels for most videos (1920x1080)
  • Font Families: Use web-safe fonts like Poppins, Roboto, Arial, Montserrat
  • Font Weight: Bold is generally more readable on video
  • Custom Fonts: Test custom fonts thoroughly before production
  • Consistency: Use same font family across all scenes for cohesion
Ensure subtitles are easily visible:
  • Light Text on Dark: White text on semi-transparent black (most common)
  • Dark Text on Light: Black text on white background (high brightness videos)
  • Shadow for Depth: Add shadows to text without backgrounds
  • Keyword Colors: Use contrasting colors for keyword highlights
  • Test Backgrounds: Verify readability on various scene backgrounds
Place subtitles where they’re visible but not intrusive:
  • Bottom-Center: Standard position, doesn’t cover main content
  • Avoid Top: Unless content is primarily at bottom
  • Width: 70-90% paragraph width prevents text from reaching edges
  • Alignment: Center alignment works best for most content
  • Scene-Specific: Consider different positions for different scene types
Use animations to enhance, not distract:
  • Entry Animation: Fade or drift work well for most content
  • Exit Animation: Faster exit (fade) than entry feels natural
  • Speed: Medium or fast speeds prevent slow pacing
  • Avoid Overuse: Too many animations can be distracting
  • Match Content: Playful animations for casual, simple for professional
Always preview your custom styles:
  • Create Test Video: Use short sample text first
  • Multiple Scenes: Test with different background colors
  • Device Testing: View on mobile and desktop
  • Readability Check: Ensure text is clear at different video sizes
  • Adjust Iteratively: Refine style based on test results

Troubleshooting

Problem: Text is not clearly visible in the video.Solution:
  • Increase background opacity (higher alpha value in backgroundColor)
  • Use higher contrast between text color and background
  • Add or increase shadow (shadowColor and shadowWidth)
  • Increase font size (try 48-56 pixels)
  • Use bold decoration for thicker, more visible text
Problem: Subtitle colors appear different than intended.Solution:
  • Verify RGBA format is correct (rgba(R, G, B, A))
  • Check RGB values are 0-255, alpha is 0-1
  • Ensure proper comma separation in RGBA values
  • Test colors with online RGBA picker before using
  • Remember alpha channel affects transparency
  • Check for typos in color values
Problem: Specified font isn’t being used.Solution:
  • Use standard web fonts (Poppins, Roboto, Arial, Montserrat)
  • Check font name spelling exactly
  • If using custom font URL, verify URL is accessible
  • Ensure fontUrl points directly to font file (.woff2, .woff, .ttf)
  • Test with standard font first, then add custom
Problem: Entry or exit animations don’t appear.Solution:
  • Verify animation name is from available options
  • Check type is either “entry” or “exit”
  • Ensure speed is “slow”, “medium”, “fast”, or “custom”
  • Maximum 2 animations allowed (one entry, one exit)
  • Check animations array syntax is correct
  • Try simple “fade” animation first to test
Problem: Subtitles appear in wrong location on screen.Solution:
  • Verify position value matches available options
  • Position names are case-sensitive and hyphenated
  • Check for typos: “bottom-center” not “bottom center”
  • Ensure paragraphWidth doesn’t push text off-screen
  • Test with “bottom-center” first as baseline
  • Review final video to verify placement

Next Steps

Explore more subtitle and branding options:

API Reference

For complete technical details, see: