Skip to main content
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 (get one here)
  • Node.js or Python installed on your machine
  • Understanding of your content’s visual needs
  • Familiarity with search query writing
npm install axios

How Visual Search Filters Work

When you apply custom visual search filters:
  1. Filter Definition - You specify category and/or query for each scene
  2. Category Filtering - System narrows search to specific visual categories
  3. Query Processing - Custom search query is analyzed for keywords
  4. Visual Search - Stock library is searched with combined filters
  5. Relevance Ranking - Results are ranked by relevance to filters
  6. Visual Selection - Best-matching visuals are selected for the scene
  7. 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();

Understanding the Parameters

Search Filter Configuration

ParameterTypeRequiredDescription
background.searchFilter.categorystringNoSpecific visual category to narrow search results. See available categories below.
background.searchFilter.querystringNoCustom 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

CategoryDescriptionExample Use Cases
Nature/LandscapesMountains, valleys, scenic viewsTravel videos, outdoor content, nature documentaries
Nature/Plants_and_TreesFlora, forests, vegetationEnvironmental content, gardening, botanical topics
Nature/Sunrises_and_SunsetsDawn and dusk scenesInspirational content, time-lapse, scenic b-roll
Nature/WeatherRain, snow, storms, cloudsWeather reports, climate content, atmospheric scenes

Animal Categories

CategoryDescriptionExample Use Cases
Animals/Farm_AnimalsCows, horses, chickens, sheepAgriculture, farming, rural life content
Animals/Marine_LifeFish, coral, ocean creaturesOcean documentaries, marine biology, underwater content
Animals/PetsDogs, cats, domestic animalsPet care, veterinary content, lifestyle videos
Animals/WildlifeWild animals in natural habitatsWildlife documentaries, conservation, nature shows

Business Categories

CategoryDescriptionExample Use Cases
Business_and_Professions/Business_ConceptsAbstract business visualsCorporate presentations, business strategy, concepts
Business_and_Professions/Office_WorkOffice environments, meetingsCorporate training, workplace content, productivity
Business_and_Professions/ProfessionsVarious professional workersCareer content, professional services, industry videos

Technology Categories

CategoryDescriptionExample Use Cases
Technology/DevicesComputers, phones, gadgetsTech reviews, product demos, device tutorials
Technology/InnovationCutting-edge tech, digital conceptsInnovation content, future tech, digital transformation

Places and Landmarks Categories

CategoryDescriptionExample Use Cases
Places_and_Landmarks/Rural_AreasCountryside, villages, farmlandRural tourism, agricultural content, pastoral scenes
Places_and_Landmarks/Tourist_AttractionsFamous landmarks, monumentsTravel guides, tourism videos, destination content
Places_and_Landmarks/Urban_AreasCities, streets, urban lifeCity guides, urban development, metropolitan content

People Categories

CategoryDescriptionExample Use Cases
People/ActivitiesPeople engaged in various activitiesLifestyle content, tutorials, activity demonstrations
People/GroupsTeams, crowds, gatheringsSocial content, community videos, team collaboration
People/PortraitsIndividual portraits, close-upsPersonal stories, interviews, testimonials

Writing Effective Search Queries

Query Best Practices

Instead of GenericUse 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

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”
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”
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”
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”
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

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

Problem: Selected visuals don’t 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
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
Problem: Setting category doesn’t 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
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
Problem: Very detailed query returns visuals that don’t 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
Problem: Certain terms don’t 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"
}
// Use both from start, iterate both
{
  category: "Technology/Innovation",
  query: "artificial intelligence digital interface"
}

Next Steps

Enhance your visual search with these complementary features:

API Reference

For complete technical details, see: