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.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.
What You’ll Learn
Search Filters
Category Filtering
Custom Queries
Combined Filtering
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
How Visual Search Filters Work
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
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
Understanding the Parameters
Search Filter Configuration
| 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. |
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
Be Descriptive and Specific
- 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
Match Query to Content Tone
- 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
Combine Multiple Elements
- 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
Use Industry-Specific Terms
- 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
Avoid Overly Complex Queries
- 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
Corporate Training Video
Environmental Documentary
Technology Product Launch
Best Practices
Combine Category and Query for Precision
Combine Category and Query for Precision
- 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
Use Subcategories for Better Results
- Instead of: Just searching all “Animals”
- Use: Specific
Animals/Marine_LifeorAnimals/Wildlife - Benefit: More targeted results within category
- Example:
Business_and_Professions/Office_Workvs generic business - Precision: Subcategories eliminate unrelated visuals
- Quality: Higher relevance in search results
Test and Iterate Your Queries
Test and Iterate Your Queries
- 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
Match Visuals to Scene Content
- 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
Consider Cultural and Regional Relevance
- 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
Visuals Do Not Match Expectations
- 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
No results or generic results returned
- 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
Category not working as expected
- 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
Same visuals appearing across different scenes
- 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
Query too specific returns poor matches
- 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
Query language or terminology issues
- 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
Strategy 2: Query-First Approach
Strategy 3: Balanced Approach (Recommended)
Next Steps
Enhance your visual search with these complementary features:Background Video Settings
Custom Backgrounds
Scene Transitions
Brand Settings
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
