Make any-to-video search requests
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 bothquery_media_url
andquery_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.
Headers
Request
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
.
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.
The media you wish to use as a local file. This parameter is required for media queries if query_media_url
is not provided.
The text query to search for. This parameter is required for text queries. Note that the platform supports full natural language-based search.
The unique identifier of the index to search.
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:
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
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
Use this parameter to filter on the level of confidence that the results match your query.
Default: low
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
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]/v1.3/docs/guides/search/queries/text-queries#visual-and-audio) section.
Default: or
.
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
.
Specifies a stringified JSON object to filter your search results. Supports both system-generated metadata (example: video ID, duration) and user-defined metadata.
Syntax for filtering
The following table describes the supported data types, operators, and filter syntax:
System-generated metadata
The table below describes the system-generated metadata available for filtering your search results:
User-defined metadata
To filter by user-defined metadata:
- Add metadata to your video by calling the
PUT
method of the/indexes/:index-id/videos/:video-id
endpoint - Reference the custom field in your filter object. For example, to filter videos where a custom field named
needsReview
of type boolean istrue
, use{"needs_review": true}
.
For more details and examples, see the Filter search results page.
Response
Successfully performed a search request.
An array that contains your search results. For each match found, the model returns the following fields:
An object that provides information about pagination.
An object that contains details about the index you queried.