Skip to main content
GET
https://api.pictory.ai
/
pictoryapis
/
v1
/
templates
List Templates
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/templates \
  --header 'Authorization: <authorization>'
{
  "items": [
    {
      "templateId": "202507141030549677ylq8k8gu44vy1y",
      "name": "Corporate Presentation Template",
      "language": "en",
      "published": true,
      "deprecated": false
    },
    {
      "templateId": "202508151145238899abc123def456gh",
      "name": "Social Media Promo",
      "language": "en",
      "published": true,
      "deprecated": false
    }
  ]
}

Overview

Retrieve a list of all video templates created and associated with your account. Templates are reusable video project configurations that can be used to quickly create new videos with consistent branding, structure, and variable placeholders.
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/templates

Request Parameters

Headers

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

Response

items
array of objects
Array of template objects

Response Examples

{
  "items": [
    {
      "templateId": "202507141030549677ylq8k8gu44vy1y",
      "name": "Corporate Presentation Template",
      "language": "en",
      "published": true,
      "deprecated": false
    },
    {
      "templateId": "202508151145238899abc123def456gh",
      "name": "Social Media Promo",
      "language": "en",
      "published": true,
      "deprecated": false
    }
  ]
}

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

Usage Notes

Templates are returned in the order they were created. Use the templateId to reference specific templates when creating new projects.
Published Status: Only templates with published: true are available for creating new videos. Draft or unpublished templates will have published: false.
Deprecated Templates: Templates marked with deprecated: true should not be used for new projects, though they may still be accessible for backward compatibility.

Common Use Cases

1. List All Available Templates

Retrieve and display all templates:
import requests

def get_all_templates(api_key):
    """
    Retrieve all templates associated with the account
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

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

    if response.status_code == 200:
        data = response.json()
        templates = data.get('items', [])

        print(f"Found {len(templates)} templates:")
        for template in templates:
            status = "Published" if template['published'] else "Draft"
            deprecated = " (Deprecated)" if template.get('deprecated') else ""
            print(f"  - {template['name']} ({status}){deprecated}")
            print(f"    ID: {template['templateId']}")

        return templates
    else:
        print(f"Error: {response.status_code}")
        return []

# Example usage
templates = get_all_templates("YOUR_API_KEY")

2. Filter Published Templates

Get only published, non-deprecated templates:
async function getPublishedTemplates(apiKey) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/templates',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const data = await response.json();

  // Filter for published, non-deprecated templates
  const publishedTemplates = data.items.filter(
    template => template.published && !template.deprecated
  );

  console.log(`Found ${publishedTemplates.length} published templates:`);
  publishedTemplates.forEach(template => {
    console.log(`  - ${template.name} (${template.templateId})`);
  });

  return publishedTemplates;
}

// Example usage
const templates = await getPublishedTemplates('YOUR_API_KEY');

3. Group Templates by Language

Organize templates by language:
from collections import defaultdict
import requests

def group_templates_by_language(api_key):
    """
    Group templates by language code
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()
    templates = data.get('items', [])

    # Group by language
    by_language = defaultdict(list)
    for template in templates:
        language = template.get('language', 'unknown')
        by_language[language].append(template)

    # Print grouped results
    for language, template_list in by_language.items():
        print(f"\n{language.upper()} Templates ({len(template_list)}):")
        for template in template_list:
            print(f"  - {template['name']}")

    return by_language

# Example usage
grouped = group_templates_by_language("YOUR_API_KEY")

4. Find Template by Name

Search for a specific template by name:
async function findTemplateByName(apiKey, searchName) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/templates',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const data = await response.json();

  // Case-insensitive search
  const found = data.items.filter(
    template => template.name.toLowerCase().includes(searchName.toLowerCase())
  );

  if (found.length > 0) {
    console.log(`Found ${found.length} matching template(s):`);
    found.forEach(template => {
      console.log(`  - ${template.name} (ID: ${template.templateId})`);
    });
    return found;
  } else {
    console.log(`No templates found matching: ${searchName}`);
    return [];
  }
}

// Example usage
const results = await findTemplateByName('YOUR_API_KEY', 'Corporate');

5. Export Template List

Export template list to a file:
import requests
import json
from datetime import datetime

def export_template_list(api_key, output_file="templates.json"):
    """
    Export all templates to a JSON file
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

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

    if response.status_code == 200:
        data = response.json()

        # Create export data with metadata
        export_data = {
            "exportDate": datetime.now().isoformat(),
            "totalTemplates": len(data.get('items', [])),
            "templates": data.get('items', [])
        }

        # Write to file
        with open(output_file, 'w') as f:
            json.dump(export_data, f, indent=2)

        print(f"Exported {export_data['totalTemplates']} templates to {output_file}")
        return export_data
    else:
        print(f"Error: {response.status_code}")
        return None

# Example usage
export_template_list("YOUR_API_KEY", "my_templates.json")

6. Template Status Summary

Generate a summary report of template statuses:
import requests

def get_template_summary(api_key):
    """
    Generate a summary of template statuses
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()
    templates = data.get('items', [])

    # Calculate statistics
    total = len(templates)
    published = sum(1 for t in templates if t.get('published'))
    deprecated = sum(1 for t in templates if t.get('deprecated'))
    active = sum(1 for t in templates if t.get('published') and not t.get('deprecated'))

    # Print summary
    print("Template Summary:")
    print(f"  Total Templates: {total}")
    print(f"  Published: {published}")
    print(f"  Deprecated: {deprecated}")
    print(f"  Active (Published & Not Deprecated): {active}")
    print(f"  Draft: {total - published}")

    # Languages breakdown
    languages = {}
    for template in templates:
        lang = template.get('language', 'unknown')
        languages[lang] = languages.get(lang, 0) + 1

    print("\nTemplates by Language:")
    for lang, count in sorted(languages.items()):
        print(f"  {lang}: {count}")

    return {
        'total': total,
        'published': published,
        'deprecated': deprecated,
        'active': active,
        'languages': languages
    }

# Example usage
summary = get_template_summary("YOUR_API_KEY")

Best Practices

Template Selection

  1. Filter Active Templates: Always filter for published: true and deprecated: false when presenting templates to users
  2. Cache Template Lists: Cache the template list to reduce API calls, refreshing periodically or when needed
  3. Handle Language: Filter templates by language when building multilingual applications
  4. Sort by Name: Sort templates alphabetically for better user experience

Performance Tips

  • Cache template list responses for 5-10 minutes to reduce API calls
  • Only fetch template list when needed (e.g., on page load or user action)
  • Use client-side filtering and sorting after fetching the list once
  • Monitor for deprecated templates and notify users to update their workflows