Guides
Start typing to search…

Text to Video with Custom Visual Search Filters per Scene

This example demonstrates how to create a video where each scene has custom visual search filters. By providing a category and media search query for each scene, you can precisely control which visuals are selected, ensuring the best match for your content.

Overview

This example covers:

  • Getting an access token
  • Creating multiple scenes with individual story sentences
  • Applying custom visual search filters per scene with category and query
  • Understanding how search filters influence visual selection
  • Monitoring job status and retrieving the final video

Node.js Example

Prerequisites

npm install axios

Complete Code

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const CLIENT_ID = "YOUR_CLIENT_ID";
const CLIENT_SECRET = "YOUR_CLIENT_SECRET";

async function createTextToVideoWithSearchFilters() {
  try {
    // Step 1: Get Access Token
    console.log("Step 1: Getting access token...");
    const tokenResponse = await axios.post(
      `${API_BASE_URL}/v1/oauth2/token`,
      {
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
      },
      {
        headers: {
          "Content-Type": "application/json",
        },
      }
    );

    const accessToken = tokenResponse.data.access_token;
    console.log("Access token obtained successfully");

    // Step 2: Create Video Storyboard with Custom Visual Search Filters
    console.log("Step 2: Creating video storyboard with custom visual search filters...");
    const storyboardResponse = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_custom_visual_search_filters",
        scenes: [
          {
            story: "The mountain ranges provide breathtaking views and challenging hiking trails.",
            background: {
              searchFilter: {
                category: "Nature/Landscapes",
                query: "majestic mountain peaks with hiking trails and scenic overlooks",
              },
            },
          },
          {
            story: "Marine life thrives in the vibrant coral reefs of tropical waters.",
            background: {
              searchFilter: {
                category: "Animals/Marine_Life",
                query: "colorful coral reef with diverse fish and marine animals swimming",
              },
            },
          },
          {
            story: "Modern technology is transforming the way we work and communicate.",
            background: {
              searchFilter: {
                category: "Technology/Innovation",
                query: "advanced technology devices and innovative digital interfaces",
              },
            },
          },
          {
            story: "Urban landscapes showcase impressive architectural designs and city life.",
            background: {
              searchFilter: {
                category: "Places_and_Landmarks/Urban_Areas",
                query: "modern city skyline with skyscrapers and urban architecture",
              },
            },
          },
          {
            story: "Professional athletes demonstrate exceptional skills in competitive sports.",
            background: {
              searchFilter: {
                category: "Sports_and_Recreation/Team_Sports",
                query: "professional athletes competing in team sports action shots",
              },
            },
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: accessToken,
        },
      }
    );

    const renderJobId = storyboardResponse.data.data.jobId;
    console.log("Storyboard render job created with custom visual search filters");
    console.log("Job ID:", renderJobId, "\n");

    // Step 3: Monitor Job Status
    console.log("Step 3: Monitoring job status...");
    let jobCompleted = false;
    let jobResult = null;

    while (!jobCompleted) {
      const jobStatusResponse = await axios.get(`${API_BASE_URL}/v1/jobs/${renderJobId}`, {
        headers: {
          Authorization: accessToken,
        },
      });

      const status = jobStatusResponse.data.data.status;
      console.log("Current status:", status);

      if (status === "completed") {
        jobCompleted = true;
        jobResult = jobStatusResponse.data;
        console.log("\nVideo with custom visual search filters created successfully!");
        console.log("Video URL:", jobResult.data.videoUrl);
      } else if (status === "failed") {
        throw new Error("Job failed: " + JSON.stringify(jobStatusResponse.data));
      } else {
        // Wait 5 seconds before checking again
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }

    return jobResult;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
    throw error;
  }
}

// Run the function
createTextToVideoWithSearchFilters();

Python Example

Prerequisites

pip install requests

Complete Code

import requests
import time
import json

API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

def create_text_to_video_with_search_filters():
    try:
        # Step 1: Get Access Token
        print('Step 1: Getting access token...')
        token_response = requests.post(
            f'{API_BASE_URL}/v1/oauth2/token',
            json={
                'client_id': CLIENT_ID,
                'client_secret': CLIENT_SECRET
            },
            headers={
                'Content-Type': 'application/json'
            }
        )
        token_response.raise_for_status()

        access_token = token_response.json()['access_token']
        print('Access token obtained successfully')
        print(f"Token expires in: {token_response.json()['expires_in']} seconds\n")

        # Step 2: Create Video Storyboard with Custom Visual Search Filters
        print('Step 2: Creating video storyboard with custom visual search filters...')
        storyboard_response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'text_to_video_custom_visual_search_filters',
                'scenes': [
                    {
                        'story': 'The mountain ranges provide breathtaking views and challenging hiking trails.',
                        'background': {
                            'searchFilter': {
                                'category': 'Nature/Landscapes',
                                'query': 'majestic mountain peaks with hiking trails and scenic overlooks'
                            }
                        }
                    },
                    {
                        'story': 'Marine life thrives in the vibrant coral reefs of tropical waters.',
                        'background': {
                            'searchFilter': {
                                'category': 'Animals/Marine_Life',
                                'query': 'colorful coral reef with diverse fish and marine animals swimming'
                            }
                        }
                    },
                    {
                        'story': 'Modern technology is transforming the way we work and communicate.',
                        'background': {
                            'searchFilter': {
                                'category': 'Technology/Innovation',
                                'query': 'advanced technology devices and innovative digital interfaces'
                            }
                        }
                    },
                    {
                        'story': 'Urban landscapes showcase impressive architectural designs and city life.',
                        'background': {
                            'searchFilter': {
                                'category': 'Places_and_Landmarks/Urban_Areas',
                                'query': 'modern city skyline with skyscrapers and urban architecture'
                            }
                        }
                    },
                    {
                        'story': 'Professional athletes demonstrate exceptional skills in competitive sports.',
                        'background': {
                            'searchFilter': {
                                'category': 'Sports_and_Recreation/Team_Sports',
                                'query': 'professional athletes competing in team sports action shots'
                            }
                        }
                    }
                ]
            },
            headers={
                'Content-Type': 'application/json',
                'Authorization': access_token
            }
        )
        storyboard_response.raise_for_status()

        render_job_id = storyboard_response.json()['data']['jobId']
        print('Storyboard render job created with custom visual search filters')
        print(f'Job ID: {render_job_id}\n')

        # Step 3: Monitor Job Status
        print('Step 3: Monitoring job status...')
        job_completed = False
        job_result = None

        while not job_completed:
            job_status_response = requests.get(
                f'{API_BASE_URL}/v1/jobs/{render_job_id}',
                headers={
                    'Authorization': access_token
                }
            )
            job_status_response.raise_for_status()

            status = job_status_response.json()['data']['status']
            print(f'Current status: {status}')

            if status == 'completed':
                job_completed = True
                job_result = job_status_response.json()
                print('\nVideo with custom visual search filters created successfully!')
                print(f"Video URL: {job_result['data']['videoUrl']}")
            elif status == 'failed':
                raise Exception(f"Job failed: {json.dumps(job_status_response.json())}")
            else:
                # Wait 5 seconds before checking again
                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

# Run the function
if __name__ == '__main__':
    create_text_to_video_with_search_filters()

Key Parameters

Scene Object

  • story: The text content for the scene that will also be used for AI understanding and subtitle generation
  • background: Configuration for the scene's background visual

Background Search Filter

  • searchFilter: Configuration to control which visuals are selected
    • category (optional): Specific visual category to search within (see categories below)
    • query (optional): Media search query that influences visual selection to find the best match

Supported Visual Categories

The API supports a wide range of visual categories to help you find the perfect match:

Aerial

  • Aerial/Coastal_and_Marine
  • Aerial/Infrastructure
  • Aerial/Natural_Landscapes
  • Aerial/Urban_Landscapes

Animals

  • Animals/Farm_Animals
  • Animals/Marine_Life
  • Animals/Pets
  • Animals/Wildlife

Business and Professions

  • Business_and_Professions/Business_Concepts
  • Business_and_Professions/Office_Work
  • Business_and_Professions/Professions

Effects

  • Effects/Chemical_Reactions
  • Effects/Explosions
  • Effects/Fire_and_Smoke
  • Effects/Glitches
  • Effects/Lighting_Effects
  • Effects/Particles

Food and Beverage

  • Food_and_Beverage/Beverages
  • Food_and_Beverage/Food_Preparation
  • Food_and_Beverage/Meals

Graphics

  • Graphics/Backgrounds
  • Graphics/Effects
  • Graphics/Patterns

Nature

  • Nature/Landscapes
  • Nature/Plants_and_Trees
  • Nature/Sunrises_and_Sunsets
  • Nature/Waterfalls
  • Nature/Weather

People

  • People/Activities
  • People/Groups
  • People/Portraits

Places and Landmarks

  • Places_and_Landmarks/Rural_Areas
  • Places_and_Landmarks/Tourist_Attractions
  • Places_and_Landmarks/Urban_Areas

Sports and Recreation

  • Sports_and_Recreation/Individual_Sports
  • Sports_and_Recreation/Outdoor_Activities
  • Sports_and_Recreation/Team_Sports

Technology

  • Technology/Devices
  • Technology/Innovation

And many more categories...

How Search Filters Work

  1. Category Filtering: When you specify a category, the visual search is restricted to that specific category, ensuring you get visuals that match the theme.

  2. Query Enhancement: The query parameter acts as a media search query that helps identify the best visual for the scene. It provides specific details about what you're looking for, making the visual selection more accurate.

  3. Combined Effect: When both category and query are used together, you get highly targeted visual results:

    • Category narrows down the type of content
    • Query refines the specific visual characteristics

Best Practices

  1. Be Specific with Queries:

    • Use descriptive language in your queries
    • Include details about mood, action, or specific elements you want
    • Example: Instead of "mountain", use "majestic mountain peaks with hiking trails"

  2. Choose Appropriate Categories:

    • Select categories that align closely with your content
    • Use subcategories for more precise results
    • Example: Use Animals/Marine_Life instead of just Animals for ocean content

  3. Consistency:

    • Maintain consistent visual themes across related scenes
    • Use similar categories for scenes that should have cohesive visuals

Response

The API returns a job ID for monitoring the video creation progress. Once completed, you'll receive a video URL with visuals precisely matched to your search filters.

Notes

  • Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual API credentials
  • Both category and query are optional, but using them together provides the best results
  • The query parameter is particularly powerful for getting specific visual characteristics
  • Categories help narrow down the visual pool, while queries refine the exact match
  • You can use different categories and queries for each scene to create diverse, targeted visuals

Updated about 3 hours ago