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

# Custom Visual Search Filters

> Control visual selection with category and query filters for precise, targeted stock footage matching

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

<CardGroup cols={2}>
  <Card title="Search Filters" icon="filter">
    Control visual selection with precision
  </Card>

  <Card title="Category Filtering" icon="folder-tree">
    Narrow visuals by specific categories
  </Card>

  <Card title="Custom Queries" icon="magnifying-glass">
    Write effective search queries
  </Card>

  <Card title="Combined Filtering" icon="layer-group">
    Use category and query together
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Understanding of your content's visual needs
* Familiarity with search query writing

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

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

<Note>
  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.
</Note>

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

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

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

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

<AccordionGroup>
  <Accordion title="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"
  </Accordion>

  <Accordion title="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"
  </Accordion>

  <Accordion title="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"
  </Accordion>

  <Accordion title="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"
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Travel and Tourism Video

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Filter Strategies

### Strategy 1: Category-First Approach

```javascript theme={null}
// 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

```javascript theme={null}
// 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)

```javascript theme={null}
// Use both from start, iterate both
{
  category: "Technology/Innovation",
  query: "artificial intelligence digital interface"
}
```

## Next Steps

Enhance your visual search with these complementary features:

<CardGroup cols={2}>
  <Card title="Background Video Settings" icon="video" href="/guides/advanced-features/background-video-settings">
    Control video background behavior
  </Card>

  <Card title="Custom Backgrounds" icon="image" href="/guides/advanced-features/intro-outro">
    Use custom images and videos
  </Card>

  <Card title="Scene Transitions" icon="right-left" href="/guides/advanced-features/transitions">
    Add smooth transitions between visuals
  </Card>

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Apply consistent branding to visuals
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full API specification including searchFilter configuration
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and get video URLs