Sign in

v1

latestOpenAPI 3.1.02026-07-266827131.9 KB

Search from Private Library

post/serve/api/v1/search

Request body

search_paramstring required

Natural-language search query. Must be non-empty.

search_type'BY_VIDEO' | 'BY_CLIP' | 'BY_AUDIO' | 'BY_IMAGE' | 'BY_CAPTION'

Search modality. BY_VIDEO is treated as BY_CLIP internally. BY_CAPTION performs vector search over the video_transcript table and returns a different item shape (see response).

top_kinteger

Maximum number of results to return. Range 1-1000 for BY_CLIP/BY_AUDIO/BY_IMAGE. For BY_CAPTION the range is 1-200 (server-side default is 10 when null).

filtering_level'low' | 'medium' | 'high'

Similarity-score filter. low=0.15, medium=0.225, high=0.4.

video_nosstring[]

Optional list of video numbers to restrict the search to. Max 100.

tagstring

Optional tag filter.

camera_tagstring

Optional camera/device model filter. Matches the camera_model supplied at upload time.

datetime_takenstring

Optional capture-time filter in format yyyy-MM-dd HH:mm:ss.

latitudenumber double

Optional latitude filter. Must be supplied together with longitude.

longitudenumber double

Optional longitude filter. Must be supplied together with latitude.

folder_idinteger

Optional. Restrict results to a single folder. Omit to query across your entire account. -1 is the Default folder; a positive id must belong to your account.

Example request

{
  "search_param": "boat in the ocean",
  "search_type": "BY_CLIP",
  "filtering_level": "medium",
  "video_nos": [
    "VI635764894954369024"
  ],
  "tag": "test1",
  "camera_tag": "Canon EOS 5D",
  "datetime_taken": "2025-10-20 11:00:00",
  "latitude": 88.88,
  "longitude": 88.88,
  "folder_id": 671631448308117500
}

Response

Successful response

codestring
msgstring
successboolean
failedboolean

Example response

{
  "code": "0000",
  "msg": "success",
  "data": [
    {
      "videoNo": "VI576925607808602112",
      "videoName": "1920447021987282945",
      "startTime": "13",
      "endTime": "18",
      "audio_ts": "...matched transcript text...",
      "score": 0.5221236659362116,
      "video_bucket": "mavi-resource",
      "video_blob": "VI576925607808602112.mp4",
      "keyframe_bucket": "mavi-keyframe",
      "keyframe_blob": "<uuid>/keyframe-000013.jpg"
    }
  ],
  "success": true,
  "failed": false
}