Skip to main content
GET
https://api.pictory.ai
/
pictoryapis
/
v1
/
styles
Get Text Styles
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/styles \
  --header 'Authorization: <authorization>'
[
  {
    "id": "8f3deae9-fe38-4c53-8be0-616bef1da916",
    "name": "Navy blue"
  },
  {
    "id": "8b715161-182a-4ef4-8130-b04873f464f6",
    "name": "Indigo ink"
  },
  {
    "id": "6d9cc665-8087-4587-ab6d-f9d7d01f82c4",
    "name": "Default"
  },
  {
    "id": "4111e523-eb9c-41a2-b17b-c312694ce4eb",
    "name": "Sleek"
  },
  {
    "id": "fc2737ae-d88b-4914-8b8d-5152d94dc3f6",
    "name": "Black Traditional Caption"
  },
  {
    "id": "c8d30e79-a7cc-4ae4-8cf9-2c6286abb407",
    "name": "Dark Blue Caption"
  },
  {
    "id": "bcbcef60-9f8f-4357-ac32-ecf5144f2f12",
    "name": "Headliner"
  },
  {
    "id": "ac666d90-f402-42b3-8b69-738afa09741c",
    "name": "Flash"
  }
]

Overview

Fetch all text styles defined in the Pictory App. Text styles are predefined formatting presets that control the appearance of text in your videos, including font, size, color, weight, alignment, and other visual properties. These styles can be applied to captions, titles, headings, and body text in your video projects. Use this endpoint to retrieve available styles for video editing, branding customization, or to allow users to select from predefined text formatting options.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/styles

Request Parameters

Headers

Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

Response

Returns an array of text style objects, each containing a unique identifier and descriptive name.
Array
array of objects
List of available text styles

Response Examples

[
  {
    "id": "8f3deae9-fe38-4c53-8be0-616bef1da916",
    "name": "Navy blue"
  },
  {
    "id": "8b715161-182a-4ef4-8130-b04873f464f6",
    "name": "Indigo ink"
  },
  {
    "id": "6d9cc665-8087-4587-ab6d-f9d7d01f82c4",
    "name": "Default"
  },
  {
    "id": "4111e523-eb9c-41a2-b17b-c312694ce4eb",
    "name": "Sleek"
  },
  {
    "id": "fc2737ae-d88b-4914-8b8d-5152d94dc3f6",
    "name": "Black Traditional Caption"
  },
  {
    "id": "c8d30e79-a7cc-4ae4-8cf9-2c6286abb407",
    "name": "Dark Blue Caption"
  },
  {
    "id": "bcbcef60-9f8f-4357-ac32-ecf5144f2f12",
    "name": "Headliner"
  },
  {
    "id": "ac666d90-f402-42b3-8b69-738afa09741c",
    "name": "Flash"
  }
]

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/styles' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

Common Use Cases

1. List All Available Styles

Retrieve and display all text styles:
import requests

url = "https://api.pictory.ai/pictoryapis/v1/styles"
headers = {
    "Authorization": "YOUR_API_KEY",
    "accept": "application/json"
}

response = requests.get(url, headers=headers)
styles = response.json()

print(f"Total styles: {len(styles)}\n")

# Group by category (based on name patterns)
captions = [s for s in styles if 'caption' in s['name'].lower()]
headings = [s for s in styles if 'heading' in s['name'].lower() or 'title' in s['name'].lower()]
others = [s for s in styles if s not in captions and s not in headings]

print(f"Caption styles: {len(captions)}")
print(f"Heading/Title styles: {len(headings)}")
print(f"Other styles: {len(others)}")

2. Search Styles by Name

Find styles matching specific criteria:
import requests

def search_styles(api_key, search_term):
    """
    Search for text styles by name.

    Args:
        api_key: Your API key
        search_term: Text to search for in style names
    """
    url = "https://api.pictory.ai/pictoryapis/v1/styles"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

    response = requests.get(url, headers=headers)
    styles = response.json()

    # Case-insensitive search
    search_term_lower = search_term.lower()
    matches = [
        style for style in styles
        if search_term_lower in style['name'].lower()
    ]

    return matches

# Usage - Find all "black" styles
black_styles = search_styles("YOUR_API_KEY", "black")

print(f"Found {len(black_styles)} styles containing 'black':")
for style in black_styles:
    print(f"- {style['name']}")

# Find caption styles
caption_styles = search_styles("YOUR_API_KEY", "caption")
print(f"\nFound {len(caption_styles)} caption styles")

3. Create Style Selector for UI

Build a dropdown/selector component:
import requests

def get_styles_for_selector(api_key, category=None):
    """
    Get text styles formatted for a UI selector.

    Args:
        api_key: Your API key
        category: Optional filter ('caption', 'heading', 'title', etc.)
    """
    url = "https://api.pictory.ai/pictoryapis/v1/styles"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

    response = requests.get(url, headers=headers)
    styles = response.json()

    # Filter by category if specified
    if category:
        styles = [
            s for s in styles
            if category.lower() in s['name'].lower()
        ]

    # Format for UI selector
    selector_options = [
        {
            "value": style['id'],
            "label": style['name']
        }
        for style in sorted(styles, key=lambda x: x['name'])
    ]

    return selector_options

# Usage
all_options = get_styles_for_selector("YOUR_API_KEY")
caption_options = get_styles_for_selector("YOUR_API_KEY", category="caption")

print(f"All styles: {len(all_options)}")
print(f"Caption styles: {len(caption_options)}")

# Example output for first 5
print("\nFirst 5 options:")
for option in all_options[:5]:
    print(f"  {option['label']} -> {option['value']}")

4. Cache Styles Locally

Cache styles to reduce API calls:
import requests
import json
from datetime import datetime, timedelta

class StyleCache:
    def __init__(self, api_key, cache_duration_hours=24):
        self.api_key = api_key
        self.cache_duration = timedelta(hours=cache_duration_hours)
        self.cache_file = "text_styles_cache.json"
        self.styles = None
        self.last_updated = None

    def get_styles(self, force_refresh=False):
        """Get styles from cache or API."""
        # Check if cache is valid
        if not force_refresh and self._is_cache_valid():
            print("Using cached styles")
            return self.styles

        # Fetch from API
        print("Fetching styles from API")
        url = "https://api.pictory.ai/pictoryapis/v1/styles"
        headers = {
            "Authorization": self.api_key,
            "accept": "application/json"
        }

        response = requests.get(url, headers=headers)
        self.styles = response.json()
        self.last_updated = datetime.now()

        # Save to cache file
        self._save_cache()

        return self.styles

    def _is_cache_valid(self):
        """Check if cache exists and is still valid."""
        try:
            with open(self.cache_file, 'r') as f:
                cache_data = json.load(f)

            last_updated = datetime.fromisoformat(cache_data['last_updated'])
            if datetime.now() - last_updated < self.cache_duration:
                self.styles = cache_data['styles']
                self.last_updated = last_updated
                return True
        except (FileNotFoundError, json.JSONDecodeError, KeyError):
            pass

        return False

    def _save_cache(self):
        """Save styles to cache file."""
        cache_data = {
            'styles': self.styles,
            'last_updated': self.last_updated.isoformat()
        }

        with open(self.cache_file, 'w') as f:
            json.dump(cache_data, f)

# Usage
cache = StyleCache("YOUR_API_KEY", cache_duration_hours=24)

# First call - fetches from API
styles = cache.get_styles()
print(f"Loaded {len(styles)} styles")

# Second call - uses cache
styles = cache.get_styles()
print(f"Loaded {len(styles)} styles")

# Force refresh
styles = cache.get_styles(force_refresh=True)
print(f"Loaded {len(styles)} styles (refreshed)")

5. Group Styles by Category

Organize styles into logical categories:
import requests
from collections import defaultdict

def categorize_styles(api_key):
    """
    Categorize text styles based on their names.

    Args:
        api_key: Your API key

    Returns:
        Dictionary with categorized styles
    """
    url = "https://api.pictory.ai/pictoryapis/v1/styles"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

    response = requests.get(url, headers=headers)
    styles = response.json()

    categories = {
        'Captions': [],
        'Headings/Titles': [],
        'Colors': [],
        'Standard': [],
        'Special Effects': [],
        'Other': []
    }

    for style in styles:
        name_lower = style['name'].lower()

        if 'caption' in name_lower:
            categories['Captions'].append(style)
        elif 'heading' in name_lower or 'title' in name_lower:
            categories['Headings/Titles'].append(style)
        elif any(color in name_lower for color in ['black', 'blue', 'yellow', 'red', 'purple', 'orange', 'green', 'pink']):
            categories['Colors'].append(style)
        elif 'standard' in name_lower or 'default' in name_lower:
            categories['Standard'].append(style)
        elif any(effect in name_lower for effect in ['bold', 'flash', 'retro', 'handwritten', 'cartoon']):
            categories['Special Effects'].append(style)
        else:
            categories['Other'].append(style)

    return categories

# Usage
categories = categorize_styles("YOUR_API_KEY")

for category, styles in categories.items():
    print(f"\n{category} ({len(styles)} styles):")
    for style in styles[:5]:  # Show first 5 of each category
        print(f"  - {style['name']}")
    if len(styles) > 5:
        print(f"  ... and {len(styles) - 5} more")

Style Categories

Based on the returned styles, common categories include:
CategoryExamplesUse Case
CaptionsBlack Traditional Caption, Dark Blue Caption, Standard White CaptionSubtitles and closed captions
HeadingsBold One-word Heading, Orange Handwritten Heading, HeadlinerVideo titles and section headers
ColorsNavy blue, Sunflower yellow, Lemon Yellow, Indigo inkColor-themed text
StandardDefault, Standard, Body text, Sub heading, HeadingGeneral-purpose text
BrandedSleek, Classic mini, Clean, Bold edge, Polished proConsistent branding
Special EffectsFlash, Retro, Handwritten, Typewriter, CartoonCreative and stylized text
News/MediaRed Breaking News Caption, Large Yellow News HeadingNews and announcements

Usage Notes

Caching Recommended: Text styles rarely change. Cache the results locally to improve performance and reduce API calls.
Style IDs: Use the UUID id field when applying styles to video elements. Style names are for display purposes only.
Consistent Across Projects: The same text styles are available across all your video projects, ensuring brand consistency.

Best Practices

  1. Cache Styles: Fetch styles once and cache them locally. Text styles change infrequently.
  2. Use Style IDs: Always reference styles by their UUID id, not by name. Names may change, but IDs remain constant.
  3. Provide Search/Filter: In user interfaces, provide search or filter functionality to help users find specific styles quickly from the large list.
  4. Group by Category: Organize styles into logical categories (captions, headings, colors) for better user experience.
  5. Show Previews: If possible, display visual previews of text styles to help users make selections.
  6. Handle Missing Styles Gracefully: If a referenced style ID doesn’t exist, fall back to a default style.
  7. Sort Alphabetically: Present styles in alphabetical order for easy browsing.
  8. Validate Style IDs: Before applying a style, verify the ID exists in the current list of available styles.