Custom Visual Search Filters

This guide shows you how to use custom visual search filters to precisely control which stock visuals are selected for each scene. Use category filters and custom search queries to ensure your videos showcase exactly the right imagery for your content.

What You’ll Learn

Search Filters

Control visual selection with precision

Category Filtering

Narrow visuals by specific categories

Custom Queries

Write effective search queries

Combined Filtering

Use category and query together

Before You Begin

Make sure you have:

A Pictory API key
Node.js or Python installed on your machine
Understanding of your content’s visual needs
Familiarity with search query writing

npm install axios

pip install requests

When you apply custom visual search filters:

Filter Definition - You specify category and/or query for each scene
Category Filtering - System narrows search to specific visual categories
Query Processing - Custom search query is analyzed for keywords
Visual Search - Stock library is searched with combined filters
Relevance Ranking - Results are ranked by relevance to filters
Visual Selection - Best-matching visuals are selected for the scene
Video Assembly - Selected visuals are integrated into video scenes

Using both category and query together provides the most precise results. The category narrows the type of content, while the query refines specific characteristics within that category.

Complete Example

import axios from "axios";

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

async function createVideoWithVisualFilters() {
  try {
    console.log("Creating video with custom visual search filters...");

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

        scenes: [
          // SCENE 1: Nature scene with specific landscape
          {
            story: "The mountain ranges provide breathtaking views for hikers.",
            background: {
              searchFilter: {
                category: "Nature/Landscapes",             // Narrow to landscapes
                query: "majestic mountain peaks with hiking trails"  // Specific query
              }
            }
          },

          // SCENE 2: Marine life scene
          {
            story: "Marine life thrives in the vibrant coral reefs.",
            background: {
              searchFilter: {
                category: "Animals/Marine_Life",           // Narrow to marine animals
                query: "colorful coral reef with diverse fish species"
              }
            }
          },

          // SCENE 3: Technology scene
          {
            story: "Modern technology is transforming how we work and communicate.",
            background: {
              searchFilter: {
                category: "Technology/Innovation",         // Narrow to tech/innovation
                query: "advanced technology devices and digital interfaces"
              }
            }
          }
        ]
      },
      {
        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 visual filters 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;
  }
}

createVideoWithVisualFilters();

import requests
import time
import json

API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
API_KEY = 'YOUR_API_KEY'

def create_video_with_visual_filters():
    try:
        print("Creating video with custom visual search filters...")

        response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'video_with_visual_filters',

                'scenes': [
                    # SCENE 1: Nature scene with specific landscape
                    {
                        'story': 'The mountain ranges provide breathtaking views for hikers.',
                        'background': {
                            'searchFilter': {
                                'category': 'Nature/Landscapes',             # Narrow to landscapes
                                'query': 'majestic mountain peaks with hiking trails'  # Specific query
                            }
                        }
                    },

                    # SCENE 2: Marine life scene
                    {
                        'story': 'Marine life thrives in the vibrant coral reefs.',
                        'background': {
                            'searchFilter': {
                                'category': 'Animals/Marine_Life',           # Narrow to marine animals
                                'query': 'colorful coral reef with diverse fish species'
                            }
                        }
                    },

                    # SCENE 3: Technology scene
                    {
                        'story': 'Modern technology is transforming how we work and communicate.',
                        'background': {
                            'searchFilter': {
                                'category': 'Technology/Innovation',         # Narrow to tech/innovation
                                'query': 'advanced technology devices and digital interfaces'
                            }
                        }
                    }
                ]
            },
            headers={
                'Content-Type': 'application/json',
                'Authorization': API_KEY
            }
        )
        response.raise_for_status()

        job_id = response.json()['data']['jobId']
        print("✓ Video creation started!")
        print(f"Job ID: {job_id}")

        # Monitor progress
        print("\nMonitoring video creation...")
        job_completed = False
        job_result = None

        while not job_completed:
            status_response = requests.get(
                f'{API_BASE_URL}/v1/jobs/{job_id}',
                headers={'Authorization': API_KEY}
            )
            status_response.raise_for_status()

            status = status_response.json()['data']['status']
            print(f"Status: {status}")

            if status == 'completed':
                job_completed = True
                job_result = status_response.json()
                print("\n✓ Video with custom visual filters is ready!")
                print(f"Video URL: {job_result['data']['videoURL']}")
            elif status == 'failed':
                raise Exception(f"Video creation failed: {status_response.json()}")

            time.sleep(5)

        return job_result

    except requests.exceptions.RequestException as error:
        print(f"Error: {error}")
        if hasattr(error, 'response') and error.response is not None:
            print(f"Response: {error.response.text}")
        raise

if __name__ == '__main__':
    create_video_with_visual_filters()

Understanding the Parameters

Parameter	Type	Required	Description
`background.searchFilter.category`	string	No	Specific visual category to narrow search results. See available categories below.
`background.searchFilter.query`	string	No	Custom search query describing desired visuals. More specific queries yield better results.

Best Practice: Use both category and query together for optimal results. Category provides broad filtering, while query adds specific details for precise matching.

Available Categories

Nature Categories

Category	Description	Example Use Cases
`Nature/Landscapes`	Mountains, valleys, scenic views	Travel videos, outdoor content, nature documentaries
`Nature/Plants_and_Trees`	Flora, forests, vegetation	Environmental content, gardening, botanical topics
`Nature/Sunrises_and_Sunsets`	Dawn and dusk scenes	Inspirational content, time-lapse, scenic b-roll
`Nature/Weather`	Rain, snow, storms, clouds	Weather reports, climate content, atmospheric scenes

Animal Categories

Category	Description	Example Use Cases
`Animals/Farm_Animals`	Cows, horses, chickens, sheep	Agriculture, farming, rural life content
`Animals/Marine_Life`	Fish, coral, ocean creatures	Ocean documentaries, marine biology, underwater content
`Animals/Pets`	Dogs, cats, domestic animals	Pet care, veterinary content, lifestyle videos
`Animals/Wildlife`	Wild animals in natural habitats	Wildlife documentaries, conservation, nature shows

Business Categories

Category	Description	Example Use Cases
`Business_and_Professions/Business_Concepts`	Abstract business visuals	Corporate presentations, business strategy, concepts
`Business_and_Professions/Office_Work`	Office environments, meetings	Corporate training, workplace content, productivity
`Business_and_Professions/Professions`	Various professional workers	Career content, professional services, industry videos

Technology Categories

Category	Description	Example Use Cases
`Technology/Devices`	Computers, phones, gadgets	Tech reviews, product demos, device tutorials
`Technology/Innovation`	Cutting-edge tech, digital concepts	Innovation content, future tech, digital transformation

Places and Landmarks Categories

Category	Description	Example Use Cases
`Places_and_Landmarks/Rural_Areas`	Countryside, villages, farmland	Rural tourism, agricultural content, pastoral scenes
`Places_and_Landmarks/Tourist_Attractions`	Famous landmarks, monuments	Travel guides, tourism videos, destination content
`Places_and_Landmarks/Urban_Areas`	Cities, streets, urban life	City guides, urban development, metropolitan content

People Categories

Category	Description	Example Use Cases
`People/Activities`	People engaged in various activities	Lifestyle content, tutorials, activity demonstrations
`People/Groups`	Teams, crowds, gatherings	Social content, community videos, team collaboration
`People/Portraits`	Individual portraits, close-ups	Personal stories, interviews, testimonials

Writing Effective Search Queries

Query Best Practices

Instead of Generic	Use Specific and Descriptive
”mountain"	"majestic mountain peaks with snow-capped summits and hiking trails"
"office"	"modern office space with natural light and collaborative workspace"
"technology"	"advanced digital interfaces with touchscreens and holographic displays"
"ocean"	"crystal clear turquoise ocean water with tropical fish and coral"
"business"	"professional business team meeting in contemporary conference room"
"city"	"bustling urban cityscape with skyscrapers at golden hour”

Query Writing Tips

Be Descriptive and Specific

Use detailed descriptions for better visual matching:

Add Context: “mountain peaks at sunset” vs just “mountain”
Include Details: “colorful coral reef with tropical fish”
Specify Style: “modern minimalist office design”
Add Mood: “serene lake with morning mist”
Describe Action: “entrepreneur working on laptop in cafe”
Use Adjectives: “vibrant”, “professional”, “dynamic”, “peaceful”

Match Query to Content Tone

Align search terms with your video’s style:

Professional: “corporate boardroom”, “business professional”
Casual: “relaxed outdoor setting”, “informal gathering”
Energetic: “dynamic motion”, “fast-paced action”
Calm: “peaceful scenery”, “tranquil environment”
Modern: “contemporary design”, “cutting-edge technology”
Traditional: “classic architecture”, “timeless aesthetic”

Combine Multiple Elements

Include multiple visual elements in queries:

Location + Activity: “people hiking on mountain trail”
Subject + Environment: “coral reef in clear tropical waters”
Object + Context: “laptop on wooden desk in bright office”
Action + Setting: “team collaborating in modern workspace”
Time + Place: “sunset over ocean beach”
Style + Subject: “minimalist interior design with natural light”

Use Industry-Specific Terms

Include relevant industry terminology:

Technology: “cloud computing”, “data visualization”, “UI/UX design”
Healthcare: “medical equipment”, “clinical setting”, “patient care”
Finance: “stock market”, “financial charts”, “banking”
Education: “classroom learning”, “students studying”, “academic”
Real Estate: “luxury home interior”, “architectural design”
Food: “gourmet cuisine”, “fresh ingredients”, “culinary”

Avoid Overly Complex Queries

Keep queries focused and manageable:

Don’t: “extremely detailed ultra-realistic 4K professional cinematic shot of”
Do: “professional high-quality business meeting”
Don’t: “absolutely perfect mountain vista with every detail”
Do: “scenic mountain landscape with clear sky”
Balance: Be specific without being unrealistic
Focus: 5-10 words is often ideal

Common Use Cases

Travel and Tourism Video

{
  scenes: [
    {
      story: "Explore ancient temples and cultural heritage...",
      background: {
        searchFilter: {
          category: "Places_and_Landmarks/Tourist_Attractions",
          query: "ancient temple ruins with historical architecture"
        }
      }
    },
    {
      story: "Experience pristine beaches and tropical paradise...",
      background: {
        searchFilter: {
          category: "Nature/Landscapes",
          query: "pristine white sand beach with palm trees and clear water"
        }
      }
    }
  ]
}

Result: Travel video with precisely matched destination visuals.

Corporate Training Video

{
  scenes: [
    {
      story: "Effective communication drives team success...",
      background: {
        searchFilter: {
          category: "Business_and_Professions/Office_Work",
          query: "diverse team collaborating in modern office meeting"
        }
      }
    },
    {
      story: "Leadership skills are essential for growth...",
      background: {
        searchFilter: {
          category: "Business_and_Professions/Professions",
          query: "confident business leader presenting to team"
        }
      }
    }
  ]
}

Result: Professional training video with appropriate workplace visuals.

Environmental Documentary

{
  scenes: [
    {
      story: "Climate change affects our planet's ecosystems...",
      background: {
        searchFilter: {
          category: "Nature/Weather",
          query: "dramatic storm clouds and changing weather patterns"
        }
      }
    },
    {
      story: "Conservation efforts protect endangered species...",
      background: {
        searchFilter: {
          category: "Animals/Wildlife",
          query: "endangered wildlife in natural habitat"
        }
      }
    }
  ]
}

Result: Environmental documentary with relevant nature and wildlife footage.

Technology Product Launch

{
  scenes: [
    {
      story: "Introducing our latest innovation in smart devices...",
      background: {
        searchFilter: {
          category: "Technology/Devices",
          query: "sleek modern smartphone with advanced features"
        }
      }
    },
    {
      story: "Powered by cutting-edge AI technology...",
      background: {
        searchFilter: {
          category: "Technology/Innovation",
          query: "futuristic digital interface with AI visualization"
        }
      }
    }
  ]
}

Result: Tech product video with modern, innovative visuals.

Best Practices

Combine Category and Query for Precision

Always use both filters together when possible:

Category Alone: Too broad, may return irrelevant results
Query Alone: Searches across all categories, less targeted
Both Together: Narrows to category, then refines with query
Example: Category: Nature/Landscapes + Query: “mountain sunset”
Result: Only landscape visuals matching “mountain sunset”
Efficiency: Faster search with more relevant results

Use Subcategories for Better Results

Choose specific subcategories over general ones:

Instead of: Just searching all “Animals”
Use: Specific Animals/Marine_Life or Animals/Wildlife
Benefit: More targeted results within category
Example: Business_and_Professions/Office_Work vs generic business
Precision: Subcategories eliminate unrelated visuals
Quality: Higher relevance in search results

Test and Iterate Your Queries

Refine queries based on results:

Start Broad: Begin with general query, review results
Add Details: Refine query with more specific terms
Compare: Test different query phrasings
Document: Keep track of queries that work well
Iterate: Adjust based on actual visual output
Build Library: Create a collection of effective queries for reuse

Match Visuals to Scene Content

Ensure visual filters align with scene narrative:

Content Relevance: Query should match what scene describes
Tone Consistency: Visual mood should match narrative tone
Action Alignment: If scene describes activity, query should too
Temporal Matching: Consider time of day, season in queries
Emotional Match: Visuals should support scene emotion
Avoid Disconnect: Don’t show unrelated visuals to confuse viewers

Consider Cultural and Regional Relevance

Adapt filters for target audience:

Local Context: Use location-specific terms when relevant
Cultural Sensitivity: Choose appropriate cultural representations
Language: Consider if terms translate well globally
Regional Specifics: “downtown Manhattan” vs generic “city”
Seasonal: Match seasons to target audience’s climate
Global vs Local: Balance universal appeal with local relevance

Troubleshooting

Visuals Do Not Match Expectations

Problem: Selected visuals do not align with scene content or query.Solution:

Make query more specific with additional descriptive terms
Verify category is appropriate for desired content
Try different query phrasing (synonyms, different structure)
Add more context to query (location, time, mood)
Test with simpler query first, then add complexity
Review if category and query are complementary, not contradictory

No results or generic results returned

Problem: Search returns very generic or seemingly random visuals.Solution:

Check that category spelling is exact (case-sensitive)
Verify category exists in available categories list
Try removing category to test if query alone works
Simplify query - may be too specific/complex
Remove uncommon words that might limit results
Use broader category if too specific category has limited stock

Category not working as expected

Problem: Setting category does not seem to filter results appropriately.Solution:

Verify exact category path: Nature/Landscapes (with slash, exact caps)
Check for typos in category name
Ensure category exists in documentation
Try parent category if subcategory too narrow
Test category without query to see category-only results
Review available categories list for correct naming

Same visuals appearing across different scenes

Problem: Different scenes get very similar or identical visuals.Solution:

Make each scene’s query more unique and specific
Add scene-specific details to differentiate queries
Use different categories for different scenes
Include contrasting elements in queries
Add time/location/style differences to queries
Test if stock library has enough variety for your needs

Query too specific returns poor matches

Problem: Very detailed query returns visuals that do not match well.Solution:

Simplify query to core elements
Remove overly specific adjectives or uncommon terms
Focus on 2-3 main visual elements
Test with broader query, then incrementally add detail
Consider if stock library has content matching specific query
Balance specificity with realistic availability

Query language or terminology issues

Problem: Certain terms do not yield expected results.Solution:

Use standard English terms (American English typically)
Try synonyms or alternative phrasings
Use industry-standard terminology
Avoid slang, regional terms, or abbreviations
Test common vs technical terminology
Keep language simple and universal

Filter Strategies

Strategy 1: Category-First Approach

// Start with category, minimal query
{
  category: "Nature/Landscapes",
  query: "mountain"
}
// Then refine query based on results
{
  category: "Nature/Landscapes",
  query: "snowy mountain peaks at sunrise"
}

Strategy 2: Query-First Approach

// Start with detailed query, no category
{
  query: "modern office team collaboration"
}
// Then add category for precision
{
  category: "Business_and_Professions/Office_Work",
  query: "modern office team collaboration"
}

Strategy 3: Balanced Approach (Recommended)

// Use both from start, iterate both
{
  category: "Technology/Innovation",
  query: "artificial intelligence digital interface"
}

Next Steps

Enhance your visual search with these complementary features:

Background Video Settings

Control video background behavior

Custom Backgrounds

Use custom images and videos

Scene Transitions

Add smooth transitions between visuals

Brand Settings

Apply consistent branding to visuals

API Reference

For complete technical details, see:

Render Storyboard Video - Full API specification including searchFilter configuration
Get Job Status - Monitor job status and get video URLs

​What You’ll Learn

Search Filters

Category Filtering

Custom Queries

Combined Filtering

​Before You Begin

​How Visual Search Filters Work

​Complete Example

​Understanding the Parameters

​Search Filter Configuration

​Available Categories

​Nature Categories

​Animal Categories

​Business Categories

​Technology Categories

​Places and Landmarks Categories

​People Categories

​Writing Effective Search Queries

​Query Best Practices

​Query Writing Tips

​Common Use Cases

​Travel and Tourism Video

​Corporate Training Video

​Environmental Documentary

​Technology Product Launch

​Best Practices

​Troubleshooting

​Filter Strategies

​Strategy 1: Category-First Approach

​Strategy 2: Query-First Approach

​Strategy 3: Balanced Approach (Recommended)

​Next Steps

Background Video Settings

Custom Backgrounds

Scene Transitions

Brand Settings

​API Reference

What You’ll Learn

Before You Begin

How Visual Search Filters Work

Complete Example

Understanding the Parameters

Search Filter Configuration

Available Categories

Nature Categories

Animal Categories

Business Categories

Technology Categories

Places and Landmarks Categories

People Categories

Writing Effective Search Queries

Query Best Practices

Query Writing Tips

Common Use Cases

Travel and Tourism Video

Corporate Training Video

Environmental Documentary

Technology Product Launch

Best Practices

Troubleshooting

Filter Strategies

Strategy 1: Category-First Approach

Strategy 2: Query-First Approach

Strategy 3: Balanced Approach (Recommended)

Next Steps

API Reference