Make a text-to-video search request

POST

This endpoint will be deprecated. TwelveLabs recommends you use the Any-to-video search endpoint instead.

Notes
  • When you use pagination, you will not be charged for retrieving subsequent pages of results.
  • This endpoint is rate-limited. For details, see the Rate limits page.

Request

This endpoint expects an object.
querystringRequired

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.”, “crowd cheering in the stadium.”

index_idstringRequired

The unique identifier of the index to search.

search_optionslist of stringsRequired

An array that specifies the sources of information the platform uses when performing a search. For details, see the Search options page.

Notes
  • The search options you specify must be a subset of the engine options used when you created the index.
  • You can specify multiple search options in conjunction with the operator parameter described below to broaden or narrow your search.
adjust_confidence_leveldoubleOptional

This parameter specifies the strictness of the thresholds for assigning the high, medium, or low confidence levels to search results. If you use a lower value, the thresholds become more relaxed, and more search results will be classified as having high, medium, or low confidence levels. You can use this parameter to include a broader range of potentially relevant video clips, even if some results might be less precise.

Min: 0 Max: 1 Default: 0.5

group_byenumOptionalDefaults to clip
Allowed values: videoclip

Use this parameter to group or ungroup items in a response. It can take one of the following values:

  • video: The platform will group the matching video clips in the response by video.
  • clip: The matching video clips in the response will not be grouped.

Default: clip

thresholdenumOptionalDefaults to low
Allowed values: highmediumlownone

Use this parameter to filter on the level of confidence that the results match your query.

Default: low

sort_optionenumOptionalDefaults to score
Allowed values: scoreclip_count

Use this parameter to specify the sort order for the response.

When performing a search, the platform determines the level of confidence that each video clip matches your search terms. By default, the search results are sorted on the level of confidence in descending order.

If you set this parameter to score and group_by is set to video, the platform will determine the maximum value of the score field for each video and sort the videos in the response by the maximum value of this field. For each video, the matching video clips will be sorted by the level of confidence.

If you set this parameter to clip_count and group_by is set to video, the platform will sort the videos in the response by the number of clips. For each video, the matching video clips will be sorted by the level of confidence. You can use clip_count only when the matching video clips are sorted by video.

Default: score

operatorstringOptionalDefaults to or

When you perform a search specifying multiple sources of information, you can use the this parameter to broaden or narrow your search.

The following logical operators are supported:

  • or

  • and

For details and examples, see the Using multiple sources of information section.

Default: or.

conversation_optionenumOptionalDefaults to semantic
Allowed values: semanticexact_match

Specifies the type of match the platform will perform. The following values are supported: semantic and exact_match. For details, see the Conversation option page.

Default: semantic

page_limitintegerOptionalDefaults to 10

The number of items to return on each page. When grouping by video, this parameter represents the number of videos per page. Otherwise, it represents the maximum number of video clips per page.

Max: 50.

filterobjectOptional

For string fields, the filter parameter returns only the results that equal the value you specify. The following example filters on the videos whose title is “Animal Encounters part 1”: "title": "Animal Encounters part 1".

For numeric fields, the filter parameter returns the results that match based on the arithmetic comparison. The following example filters on the videos whose height is greater than or equal to 400 and less than or equal to 500: "height": { "gte": 400, "lte": 500 }.

To enable filtering by custom fields:

  1. Add metadata to your video by calling the the PUT method of the /indexes/:index-id/videos/:video-id endpoint
  2. Use the custom fields as filter criteria in your queries. For example, to return only videos where a custom field named needsReview of type boolean is true, use: "needs_review": true.

For more details and examples, see the Filter search results based on metadata page.

Response

Successfully performed a search request.

datalist of objectsOptional

An array that contains your search results. For each match found, the engine returns the following fields:

page_infoobjectOptional

An object that provides information about pagination.

search_poolobjectOptional

An object that contains details about the index you queried.

Errors

Built with