Classify

Deprecation notice

The Classify API has been deprecated on Feb 28, 2025.

Recommended alternative: Update to the 1.3 version of the API and use the Pegasus video understanding model to classify videos.

Resources: Migration guide > Use Pegasus to classify videos.

The resources.Classify class provides methods to classify a set of videos or all the videos within an index.

Related quickstart notebook](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/TwelveLabs_Quickstart_Classify.ipynb)

Methods

Classify a set of videos

Description: This method classifies a set of videos based on the provided parameters and returns the first page of results.

Function signature and example:

1def videos(
2 self,
3 video_ids: List[str],
4 options: List[Union[str, Literal["visual", "conversation", "text_in_video"]]],
5 classes: List[models.ClassifyClassParams],
6 *,
7 conversation_option: Optional[Union[str, Literal["semantic", "exact_match"]]] = "semantic",
8 page_limit: Optional[int] = None,
9 include_clips: Optional[bool] = None,
10 threshold: Optional[Dict[str, Any]] = None,
11 show_detailed_score: Optional[bool] = None,
12 **kwargs
13) -> models.ClassifyPageResult

Parameters:

NameTypeRequiredDescription
video_idsList[str]YesA list containing the unique identifiers of the videos that you want to classify
optionsList[Union[str, Literal["visual", "conversation", "text_in_video"]]]YesA list that specifies the sources of information the platform uses when it categorizes a video.
classesList[models.ClassifyClassParams]YesAn array of ClassifyClassParams objects containing the names and the definitions of entities or actions that the platform must identify.
conversation_optionOptional[Union[str, Literal["semantic", "exact_match"]]]NoSpecifies the type of match the platform will perform.
page_limitOptional[int]NoThe maximum number of results per page.
include_clipsOptional[bool]NoSet this parameter to true to retrieve detailed information about each matching video clip.
thresholdOptional[Dict[str, Any]]NoThresholds for different classification options.
show_detailed_scoreOptional[bool]NoWhether to show detailed scores in the result.
**kwargsdictNoAdditional keyword arguments for the request.

Return value: Returns a models.ClassifyPageResult object containing the classification results.

API Reference: For a description of each field in the request and response, see the Classify a set of videos page.

Related guides:

Classify all the videos within an index

Description: This method classifies all the videos within a specific index based on the provided parameters and returns the first page of results.

Function signature and example:

1def index(
2 self,
3 index_id: str,
4 options: List[Union[str, Literal["visual", "conversation", "text_in_video"]]],
5 classes: List[models.ClassifyClassParams],
6 *,
7 conversation_option: Optional[Union[str, Literal["semantic", "exact_match"]]] = "semantic",
8 page_limit: Optional[int] = None,
9 include_clips: Optional[bool] = None,
10 threshold: Optional[Dict[str, Any]] = None,
11 show_detailed_score: Optional[bool] = None,
12 **kwargs
13) -> models.ClassifyPageResult
NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index containing the videos you want to classify.
optionsList[Union[str, Literal["visual", "conversation", "text_in_video"]]]YesAn array that specifies the sources of information the platform uses when it categorizes a video.
classesList[models.ClassifyClassParams]YesAn array of ClassifyClassParams objects containing the names and the definitions of entities or actions that the platform must identify.
conversation_optionOptional[Union[str, Literal["semantic", "exact_match"]]]NoSpecifies the type of match the platform will perform.
page_limitOptional[int]NoThe maximum number of results per page.
include_clipsOptional[bool]NoSet this parameter to true to retrieve detailed information about each matching video clip.
thresholdOptional[Dict[str, Any]]NoThresholds for different classification options.
show_detailed_scoreOptional[bool]NoWhether to show detailed scores in the result.
**kwargsdictNoAdditional keyword arguments for the request.

Return value: Returns a models.ClassifyPageResult object containing the classification results.

API Reference: For a description of each field in the request and response, see the Classify all the videos within an index page.

Related guides:

Retrieve a specific page of results

Description: This method retrieves a specific page of results. This method provides direct pagination. Choose it mainly when the total number of items is manageable, or you must fetch a single page of results.

Function signature and example:

1def by_page_token(
2 self,
3 page_token: str,
4 **kwargs
5) -> models.ClassifyPageResult

Parameters:

NameTypeRequiredDescription
pageTokenstrYesA token that identifies the page to retrieve.
**kwargsdictNoAdditional keyword arguments for the request.

Return value: Returns a models.ClassifyPageResult object containing the classification results for the specified page.

API Reference: For a description of each field in the request and response, see the Retrieve a specific page of results page.

Related guides:

Iterative pagination

If your application must retrieve a large number of items, use iterative pagination. To retrieve the first page of results, invoke the index or videos methods of the classify object. To retrieve subsequent pages of results, use the iterator protocol.

Python
1CLASSES = [
2 {
3 "name": "DanceTok",
4 "prompts": [
5 "Dance tutorial",
6 "Dance group",
7 "Dance competition"
8 ]
9 },
10 {
11 "name": "CookTok",
12 "prompts": [
13 "Cooking tutorial",
14 "Cooking ustensils review"
15 ]
16 }
17]
18
19def print_classify_page_result(result):
20 print("Classification results:")
21 data = getattr(result, 'data', result)
22 if isinstance(data, list):
23 for video_data in data:
24 print_classify_video_data(video_data)
25 else:
26 print_classify_video_data(data)
27
28def print_classify_video_data(video_data):
29 print(f"Video ID: {video_data.video_id}")
30 for class_data in video_data.classes:
31 print_classify_class(class_data)
32 print() # Add a blank line between videos
33
34def print_classify_class(class_data):
35 print(f" Class name: {class_data.name}")
36 print(f" Score: {class_data.score}")
37 print(f" Duration ratio: {class_data.duration_ratio}")
38 if class_data.clips:
39 print(" Clips:")
40 for clip in class_data.clips:
41 print_classify_clip(clip)
42
43def print_classify_clip(clip):
44 print(f" Start: {clip.start}")
45 print(f" End: {clip.end}")
46 print(f" Score: {clip.score}")
47 print(f" Option: {clip.option}")
48 print(f" Prompt: {clip.prompt}")
49 print(f" Thumbnail URL: {clip.thumbnail_url or 'N/A'}")
50 if clip.detailed_scores:
51 print_classify_detailed_score(clip.detailed_scores)
52
53def print_classify_detailed_score(detailed_score):
54 print(f" Max score: {detailed_score.max_score}")
55 print(f" Avg score: {detailed_score.avg_score}")
56 print(f" Normalized score: {detailed_score.normalized_score}")
57
58
59result = client.classify.index(
60 index_id="<YOUR_INDEX_ID>",
61 options=["visual", "conversation"],
62 classes=CLASSES,
63 include_clips=True,
64 show_detailed_score=True,
65 page_limit=1
66)
67
68print_classify_page_result(result)
69
70page_number = 2
71while True:
72 try:
73 print(f"Page {page_number}")
74 print_classify_page_result(next(result))
75 page_number += 1
76 except StopIteration:
77 break
78
79print("No more results.")
Built with