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

# Get Video Brands

> Retrieve all video brand configurations defined in the Pictory application

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

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/brands/video
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

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

<ResponseField name="Array" type="array of objects">
  List of available video brands

  <Expandable title="brand object">
    <ResponseField name="id" type="uuid" required>
      Unique identifier for the video brand
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Descriptive name of the video brand (e.g., "Default Brand", "Corporate Blue", "Modern Minimalist")
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "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"
    }
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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 video brands available: {len(brands)}\n")

  # Display all brands
  for brand in brands:
      print(f"- {brand['name']} (ID: {brand['id']})")
  ```

  ```javascript JavaScript / Node.js theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/brands/video',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const brands = await response.json();

  console.log(`Total video brands available: ${brands.length}\n`);

  // Display all brands
  brands.forEach(brand => {
    console.log(`- ${brand.name} (ID: ${brand.id})`);
  });
  ```

  ```php PHP theme={null}
  <?php
  // Replace 'YOUR_API_KEY' with your actual API key

  function getVideoBrands($apiKey) {
      $url = 'https://api.pictory.ai/pictoryapis/v1/brands/video';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey,
          'accept: application/json'
      ]);

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 200) {
          throw new Exception('Request failed with status ' . $httpCode);
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $brands = getVideoBrands('YOUR_API_KEY');

      echo "Total video brands available: " . count($brands) . "\n\n";

      // Display all brands
      foreach ($brands as $brand) {
          echo "- {$brand['name']} (ID: {$brand['id']})\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  // Replace "YOUR_API_KEY" with your actual API key

  package main

  import (
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  type VideoBrand struct {
      ID   string `json:"id"`
      Name string `json:"name"`
  }

  func getVideoBrands(apiKey string) ([]VideoBrand, error) {
      url := "https://api.pictory.ai/pictoryapis/v1/brands/video"

      req, err := http.NewRequest("GET", url, nil)
      if err != nil {
          return nil, err
      }

      req.Header.Set("Authorization", apiKey)
      req.Header.Set("accept", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      body, err := io.ReadAll(resp.Body)
      if err != nil {
          return nil, err
      }

      if resp.StatusCode != http.StatusOK {
          return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
      }

      var brands []VideoBrand
      if err := json.Unmarshal(body, &brands); err != nil {
          return nil, err
      }

      return brands, nil
  }

  // Usage
  func main() {
      brands, err := getVideoBrands("YOUR_API_KEY")
      if err != nil {
          panic(err)
      }

      fmt.Printf("Total video brands available: %d\n\n", len(brands))

      // Display all brands
      for _, brand := range brands {
          fmt.Printf("- %s (ID: %s)\n", brand.Name, brand.ID)
      }
  }
  ```
</CodeGroup>

***

## Common Use Cases

### 1. List All Available Video Brands

Retrieve and display all video brands:

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

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

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

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

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

<Tip>
  **Caching Recommended**: Video brands rarely change. Cache the results locally to improve performance and reduce API calls.
</Tip>

<Note>
  **Brand IDs**: Use the UUID `id` field when applying brands to video projects. Brand names are for display purposes only.
</Note>

<Note>
  **Consistent Branding**: The same video brands are available across all your video projects, ensuring brand consistency.
</Note>

***

## Best Practices

1. **Cache Brands**: Fetch brands once and cache them locally. Video brands change infrequently.

2. **Use Brand IDs**: Always reference brands by their UUID `id`, not by name. Names may change, but IDs remain constant.

3. **Default Brand**: Most accounts have a "Default Brand" that can be used as a fallback option.

4. **Validate Brand IDs**: Before applying a brand to a project, verify the ID exists in the current list of available brands.

5. **Sort Alphabetically**: Present brands in alphabetical order for easy browsing in user interfaces.

6. **Handle Missing Brands Gracefully**: If a referenced brand ID does not exist, fall back to the default brand.

7. **Brand Previews**: If possible, display visual previews of brand styles to help users make selections.

8. **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:

```python theme={null}
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"
)
```

***

## Related Endpoints

* [Get Text Styles](get-text-styles) - Retrieve text styling options
* [Get Projects](get-projects) - List all video projects
* [Update Project](update-project) - Modify project settings including brand