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
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
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
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
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
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
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
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
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
Corporate Training Video
Environmental Documentary
Technology Product Launch
Best Practices
Combine Category and Query for Precision
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
Use Subcategories for Better Results
Choose specific subcategories over general ones:
- 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
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
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
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 don't match expectations
Visuals don't match expectations
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
No results or generic results returned
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
Category not working as expected
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
Same visuals appearing across different scenes
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
Query too specific returns poor matches
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
Query language or terminology issues
Query language or terminology issues
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
Strategy 2: Query-First Approach
Strategy 3: Balanced Approach (Recommended)
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
