Make any-to-video search requests

post

https://api.twelvelabs.io/v1.3/search

Use this endpoint to search for relevant matches in an index using text or various media queries.

Text queries:

Use the query_text parameter to specify your query.

Media queries:

Set the query_media_type parameter to the corresponding media type (example: image).
Specify either one of the following parameters:
- query_media_url: Publicly accessible URL of your media file.
- query_media_file: Local media file.
  If both query_media_url and query_media_file are specified in the same request, query_media_url takes precedence.

Before using a media file as a query, ensure that the file meets the prerequisites.

NOTE: This endpoint is rate-limited. For details, see the Rate limits page.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request to perform a search on a video index.

query_media_type

string

enum

The type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to image.

Allowed:

query_media_url

string

The publicly accessible URL of the media file you wish to use. This parameter is required for media queries if query_media_file is not provided.

query_media_file

file

The media you wish to use as a local file. This parameter is required for media queries if query_media_url is not provided.

query_text

string

The text query to search for. This parameter is required for text queries. Note that the platform supports full natural language-based search.

index_id

string

required

The unique identifier of the index to search.

search_options

array of strings

required

Specifies the sources of information the platform uses when performing a search. You must include the search_options parameter separately for each desired source of information.

NOTES:

The search options you specify must be a subset of the model 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.

Example:
To search using both visual and audio cues, include this parameter twice in the request as shown below:

--form search_options=visual \
--form search_options=audio \

search_options*

Allowed:

adjust_confidence_level

float

Defaults to 0.5

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_by

string

enum

Defaults to clip

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

Allowed:

threshold

string

enum

Defaults to low

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

Default: low

Allowed:

sort_option

string

enum

Defaults to score

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 grouped by video.

Default: score

Allowed:

operator

string

enum

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

Allowed:

page_limit

integer

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

filter

string

This parameter accepts a stringified object to filter search results:

For string fields: Use the exact match operator (=) to return results that exactly equal the specified value. Syntax: "field": "value".
For numeric fields: Use either exact match (=) or comparison operators (gte, lte) for arithmetic comparisons Syntax: "field": number or "field": { "gte": number, "lte": number }.

The filter object can contain the following properties:

id: An array of strings to filter by specific video IDs. Example: "id": ["video1", "video2"].
duration: An object to filter your search results based on the duration of the video containing the segment that matches your query. Example: "duration": { "gte": 600, "lte": 800 }.
width: A numeric value to filter by video width. Example: "width": 1920 or "width": { "gte": 1280, "lte": 1920 }
height: A numeric value to filter by video height. Example: "height": 1080 or "height": { "gte": 720, "lte": 1080 }.
size: A numeric value to filter by video size in bytes. Example: "size": 1048576 or "size": { "gte": 1048576, "lte": 5242880 }.
filename: A string value to filter by file name. Example: "filename": "Animal Encounters part 1".

To enable filtering by custom fields:

Add metadata to your video by calling the the PUT method of the /indexes/:index-id/videos/:video-id endpoint
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.

Headers

x-api-key

string

required

Your API key.

NOTE: You can find your API key on the API Key page.

Responses

429

If the rate limit is reached, the platform returns an HTTP 429 - Too many requests error response. The response body is empty.

200Successfully performed a search request.

400The request has failed.