Search

Search across video files and segments to find relevant content

Changed on

Search for videos or video segments in collections to find relevant videos or moments/clips in a video

post/search

Request

  • Base URL
    https://api.cloudglue.dev/v1
  • Auth
    HTTP bearer

Request body

scope'file' | 'segment' | 'face' | 'moment'

Search scope - 'file' searches at file level (requires collections with enable_summary=true), 'segment' searches at segment level, 'face' searches for faces in videos using image matching, 'moment' searches moments produced by find-moments criteria in moments collections

collectionsstring[]

List of collection IDs to search within.

For text search (scope='file' or 'segment'): All collections must be of collection_type 'media-descriptions', 'rich-transcripts', 'metadata', or 'entities'. For file-level search, 'media-descriptions' and 'rich-transcripts' collections must have 'enable_summary: true' in their config. 'metadata' collections only support scope='file'. 'entities' collections are searchable at the scope matching their extraction level: file-level extraction (enable_video_level_entities or enable_metadata_mode) supports scope='file' only, segment-level extraction (enable_segment_level_entities) supports scope='segment' only.

For face search (scope='face'): All collections must be of collection_type 'face-analysis'.

For moment search (scope='moment'): All collections must be of collection_type 'moments'.

querystring

Text search query to find relevant content (required for scope='file', 'segment', or 'moment')

criterion_namestring

Narrow moment search to one criterion by name (scope='moment' only)

limitinteger

Maximum number of search results to return (applies to total items across groups when grouping)

thresholdnumber

Minimum score threshold to filter results. Can be any real number.

group_by_key'file'

Group results by file. Cannot be used with scope="file" or scope="moment" — grouped moment search is not supported and returns a 400. When specified, results are grouped by file_id.

sort_by'score' | 'item_count'

Sort order for results. Default: "score". When group_by_key is specified, can also use "item_count" to sort by number of items per group.

search_modalitiesstring[]

Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality.

Available modalities:

  • general_content: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string
  • speech_lexical: performs keyword based search (e.g. query of president matching president or presidential strings) and exact match (e.g. specifically find mentions of "Barack Obama" or "Donald Trump") against speech content present in search item
  • ocr_lexical: performs keyword based search and exact match against screen text content present in search item
  • tag_semantic: performs basic word semantic similarity search against tag values associated with search items (e.g. query=animal expected to match tags with value containing dog or cat)
  • tag_lexical: performs keyword based search and exact match against tag values associated with search items
  • doc_lexical: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search scope=file.

Only applicable when search scope=file or scope=segment.

label_filtersstring[]

Filter eligible search items by presence of one or more labels in the provided list (otherwise all tags will be considered in search response). Only supported for tag_semantic and tag_lexical search modalities

Response

Successful search results

idstring uuid required

ID of the search response

object'search' required

Object type, always 'search'

querystring

The search query that was executed (for text search) or the source image URL/base64 indicator (for face search)

scope'file' | 'segment' | 'face' | 'moment' required

The search scope that was used

group_by_key'file'

The key used for grouping results. Only present when group_by_key was specified in the request and results are grouped.

group_countinteger

Number of groups in the results. Only present when group_by_key is specified.

search_modalitiesstring[]

Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality.

Available modalities:

  • general_content: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string
  • speech_lexical: performs keyword based search (e.g. query of president matching president or presidential strings) and exact match (e.g. specifically find mentions of "Barack Obama" or "Donald Trump") against speech content present in search item
  • ocr_lexical: performs keyword based search and exact match against screen text content present in search item
  • tag_semantic: performs basic word semantic similarity search against tag values associated with search items (e.g. query=animal expected to match tags with value containing dog or cat)
  • tag_lexical: performs keyword based search and exact match against tag values associated with search items
  • doc_lexical: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search scope=file.

Only applicable when search scope=file or scope=segment.

totalinteger required

Total number of results returned. When group_by_key is specified, this represents the total number of items across all groups (not the number of groups).

limitinteger required

The limit that was applied to the search

Changes

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • breaking

      added to the / response property oneOf list for the response status

    • warning

      added the new moment enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new moment enum value to the request property