Text queries allow you to use natural language to find video segments matching specific keywords or phrases.

Note the following about using text queries:

The platform supports full natural language-based search. The following examples are valid queries: "birds flying near a castle," "sun shining on the water," "chickens on the road," "an officer holding a child's hand," and "crowd cheering in the stadium."
The platform supports queries in multiple languages. For a complete list, see the Supported languages page.
To search for specific text shown in videos, use queries that target on-screen text rather than objects or concepts. Note that the platform may return both textual and visual matches. For example, searching for the word "smartphone" might return both segments where "smartphone" appears as on-screen text and segments where smartphones are visible as objects.
To detect logos, specify the text within the logo. If the logo doesn't contain text, you can search using image queries.

Examples

This section provides examples of performing search requests using single queries. Ensure that the prerequisites are met before proceeding.

Visual

The platform analyzes video content as you would see and hear from it, including actions, objects, sounds, and events, excluding human speech. To search using visual cues, invoke the query method of the search object with the following parameters:

index_id: A string representing the unique identifier of the index to search.
query_text: A string representing your search query. Note that the platform supports full natural language-based search. The following examples are valid queries: "birds flying near a castle," "sun shining on the water," "chickens on the road," "an officer holding a child's hand," and "crowd cheering in the stadium."
options: An array of strings specifying the sources of information the platform uses when performing a search. This example searches using visual cues.

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>", 
  query_text="<YOUR_QUERY>", 
  options=["visual"]
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
    )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>'
  queryText: '<YOUR_QUERY>',
  options: ['visual'],
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
    );
  });
}

The example output below was truncated for brevity:

video_id=65d60bcf48db9fa780cb415e score=83.73 start=273.96875 end=289.0625 confidence=high video_id=65d60bcf48db9fa780cb415e score=83.55 start=397.921875 end=439.84375 confidence=high 
video_id=65d60bcf48db9fa780cb415e score=83.46 start=294.5625 end=311.84375 confidence=high 
video_id=65d60bcf48db9fa780cb415e score=83.45 start=233.0 end=247.78125 confidence=high

Audio

The platform analyzes human speech within your videos. The following example sets the value of the options parameter to ["audio"] to search using human speech as the source of information.

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>", 
    query_text="<YOUR_QUERY>" 
    options=["audio"], 
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
    )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['audio'],
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
    );
  });
}

The example output below was truncated for brevity:

 video_id=65d5fbad48db9fa780cb415c score=70.05 start=347.04 end=363.929 confidence=low
 video_id=65d5fbad48db9fa780cb415c score=58.75 start=366.869 end=405.589 confidence=low

Visual and audio

The following example sets the value options parameter to ["visual", "audio"] and the value of the operator parameter to and to specify that the platform should return the results for which all the selected sources of information match:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>",
  query_text="<YOUR_QUERY>",
  options=["visual","audio"],
  operator="and"
)
# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}"
    )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['visual', 'audio'],
  operator: 'and',
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
    );
  });
}

The example output below was truncated for brevity:

video_id=639963a1ce36463e0199c8c7 score=76.79 start=420.66 end=430.23 confidence=medium
video_id=6399637ace36463e0199c8c6 score=58.99 start=665.745 end=676.795 confidence=low