Get Video Brands

Overview

Fetch all video brand configurations defined in the Pictory App. Video brands are customizable presets that define your video’s visual identity, including color schemes, fonts, logos, animations, and other branding elements. These brands ensure consistent styling across all your video projects. Use this endpoint to retrieve available brand configurations for video editing, maintaining brand consistency, or allowing users to select from predefined branding options for their video projects.

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/brands/video

Request Parameters

Headers

Authorization

string

required

API key for authentication (starts with pictai_)

Authorization: YOUR_API_KEY

Response

Returns an array of video brand objects, each containing a unique identifier and descriptive name.

Array

array of objects

List of available video brands

Show brand object

uuid

required

Unique identifier for the video brand

name

string

required

Descriptive name of the video brand (e.g., “Default Brand”, “Corporate Blue”, “Modern Minimalist”)

Response Examples

[
  {
    "id": "eb67b4ba-0eef-41fa-a772-d9675cc3645c",
    "name": "Default Brand"
  },
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Corporate Blue"
  },
  {
    "id": "f8e7d6c5-b4a3-9281-7065-43210fedcba9",
    "name": "Modern Minimalist"
  },
  {
    "id": "12345678-90ab-cdef-1234-567890abcdef",
    "name": "Bold & Vibrant"
  }
]

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/brands/video' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

Common Use Cases

1. List All Available Video Brands

Retrieve and display all video brands:

import requests

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

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

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

# Display with details
for i, brand in enumerate(brands, 1):
    print(f"{i}. {brand['name']}")
    print(f"   ID: {brand['id']}")
    print()

2. Create Brand Selector for UI

Build a dropdown/selector component:

import requests

def get_brands_for_selector(api_key):
    """
    Get video brands formatted for a UI selector.

    Args:
        api_key: Your API key

    Returns:
        List of selector options
    """
    url = "https://api.pictory.ai/pictoryapis/v1/brands/video"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

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

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

    return selector_options

# Usage
options = get_brands_for_selector("YOUR_API_KEY")

print(f"Brand options: {len(options)}\n")

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

3. Search Brands by Name

Find brands matching specific criteria:

import requests

def search_brands(api_key, search_term):
    """
    Search for video brands by name.

    Args:
        api_key: Your API key
        search_term: Text to search for in brand names

    Returns:
        List of matching brand objects
    """
    url = "https://api.pictory.ai/pictoryapis/v1/brands/video"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

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

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

    return matches

# Usage - Find all "default" brands
default_brands = search_brands("YOUR_API_KEY", "default")

print(f"Found {len(default_brands)} brands containing 'default':")
for brand in default_brands:
    print(f"- {brand['name']}")

4. Cache Brands Locally

Cache brands to reduce API calls:

import requests
import json
from datetime import datetime, timedelta

class BrandCache:
    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 = "video_brands_cache.json"
        self.brands = None
        self.last_updated = None

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

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

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

        # Save to cache file
        self._save_cache()

        return self.brands

    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.brands = cache_data['brands']
                self.last_updated = last_updated
                return True
        except (FileNotFoundError, json.JSONDecodeError, KeyError):
            pass

        return False

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

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

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

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

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

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

5. Validate Brand ID Before Use

Check if a brand ID exists:

import requests

def validate_brand_id(api_key, brand_id):
    """
    Validate if a brand ID exists in available brands.

    Args:
        api_key: Your API key
        brand_id: The brand ID to validate

    Returns:
        Tuple of (is_valid, brand_name or None)
    """
    url = "https://api.pictory.ai/pictoryapis/v1/brands/video"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

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

    # Search for brand by ID
    for brand in brands:
        if brand['id'] == brand_id:
            return True, brand['name']

    return False, None

# Usage
brand_id = "eb67b4ba-0eef-41fa-a772-d9675cc3645c"
is_valid, brand_name = validate_brand_id("YOUR_API_KEY", brand_id)

if is_valid:
    print(f"✓ Brand ID is valid: {brand_name}")
else:
    print("✗ Brand ID not found")

Brand Configuration

Video brands typically include the following elements:

Element	Description	Purpose
Color Palette	Primary, secondary, and accent colors	Consistent color scheme across videos
Typography	Font families, sizes, and weights	Text styling and readability
Logo	Company or personal logo	Brand identity and recognition
Intro/Outro	Opening and closing sequences	Professional video bookends
Lower Thirds	Text overlays for names and titles	Professional presentation
Transitions	Animation styles between scenes	Smooth visual flow
Music Theme	Default background music style	Audio branding
Watermark	Brand watermark positioning	Content ownership

Usage Notes

Caching Recommended: Video brands rarely change. Cache the results locally to improve performance and reduce API calls.

Brand IDs: Use the UUID id field when applying brands to video projects. Brand names are for display purposes only.

Consistent Branding: The same video brands are available across all your video projects, ensuring brand consistency.

Best Practices

Cache Brands: Fetch brands once and cache them locally. Video brands change infrequently.
Use Brand IDs: Always reference brands by their UUID id, not by name. Names may change, but IDs remain constant.
Default Brand: Most accounts have a “Default Brand” that can be used as a fallback option.
Validate Brand IDs: Before applying a brand to a project, verify the ID exists in the current list of available brands.
Sort Alphabetically: Present brands in alphabetical order for easy browsing in user interfaces.
Handle Missing Brands Gracefully: If a referenced brand ID doesn’t exist, fall back to the default brand.
Brand Previews: If possible, display visual previews of brand styles to help users make selections.
User Permissions: Ensure users have appropriate permissions to access and use specific brands.

Integration with Projects

Apply a video brand to a project during creation or updates:

import requests

def apply_brand_to_project(api_key, project_id, brand_id):
    """
    Apply a video brand to an existing project.

    Args:
        api_key: Your API key
        project_id: The project to update
        brand_id: The brand ID to apply
    """
    # First, validate the brand exists
    brands_url = "https://api.pictory.ai/pictoryapis/v1/brands/video"
    headers = {
        "Authorization": api_key,
        "accept": "application/json"
    }

    brands_response = requests.get(brands_url, headers=headers)
    brands = brands_response.json()

    # Check if brand exists
    brand_exists = any(b['id'] == brand_id for b in brands)

    if not brand_exists:
        raise ValueError(f"Brand ID {brand_id} not found")

    # Apply brand to project (example - actual endpoint may vary)
    print(f"Applying brand {brand_id} to project {project_id}")
    # Implementation depends on project update endpoint

# Usage
apply_brand_to_project(
    "YOUR_API_KEY",
    "project-123",
    "eb67b4ba-0eef-41fa-a772-d9675cc3645c"
)

Get Text Styles - Retrieve text styling options
Get Projects - List all video projects
Update Project - Modify project settings including brand

Getting started

Videos

Pictory Jobs

Smart Layouts

VoiceOvers

Music Search

Media Management

Branding - Video

Pictory Projects

Video Templates

Video Summary and Transcription

Vimeo Integration

AWS Integration

Overview

API Endpoint

Request Parameters

Headers

Response

Response Examples

Code Examples

Common Use Cases

1. List All Available Video Brands

2. Create Brand Selector for UI

3. Search Brands by Name

4. Cache Brands Locally

5. Validate Brand ID Before Use

Brand Configuration

Usage Notes

Best Practices

Integration with Projects

Getting started

Videos

Pictory Jobs

Smart Layouts

VoiceOvers

Music Search

Media Management

Branding - Video

Pictory Projects

Video Templates

Video Summary and Transcription

Vimeo Integration

AWS Integration

​Overview

​API Endpoint

​Request Parameters

​Headers

​Response

​Response Examples

​Code Examples

​Common Use Cases

​1. List All Available Video Brands

​2. Create Brand Selector for UI

​3. Search Brands by Name

​4. Cache Brands Locally

​5. Validate Brand ID Before Use

​Brand Configuration

​Usage Notes

​Best Practices

​Integration with Projects

​Related Endpoints

Overview

API Endpoint

Request Parameters

Headers

Response

Response Examples

Code Examples

Common Use Cases

1. List All Available Video Brands

2. Create Brand Selector for UI

3. Search Brands by Name

4. Cache Brands Locally

5. Validate Brand ID Before Use

Brand Configuration

Usage Notes

Best Practices

Integration with Projects

Related Endpoints