Search by Text

Search from Private Library

curl --request POST \
  --url https://api.memories.ai/serve/api/v1/search \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_param": "boat in the ocean",
  "search_type": "BY_CLIP",
  "top_k": 100,
  "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
}
'

import requests

url = "https://api.memories.ai/serve/api/v1/search"

payload = {
    "search_param": "boat in the ocean",
    "search_type": "BY_CLIP",
    "top_k": 100,
    "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
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_param: 'boat in the ocean',
    search_type: 'BY_CLIP',
    top_k: 100,
    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
  })
};

fetch('https://api.memories.ai/serve/api/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.memories.ai/serve/api/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_param' => 'boat in the ocean',
    'search_type' => 'BY_CLIP',
    'top_k' => 100,
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.memories.ai/serve/api/v1/search"

	payload := strings.NewReader("{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.memories.ai/serve/api/v1/search")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.memories.ai/serve/api/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

POST

serve

api

Search from Private Library

curl --request POST \
  --url https://api.memories.ai/serve/api/v1/search \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_param": "boat in the ocean",
  "search_type": "BY_CLIP",
  "top_k": 100,
  "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
}
'

import requests

url = "https://api.memories.ai/serve/api/v1/search"

payload = {
    "search_param": "boat in the ocean",
    "search_type": "BY_CLIP",
    "top_k": 100,
    "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
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_param: 'boat in the ocean',
    search_type: 'BY_CLIP',
    top_k: 100,
    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
  })
};

fetch('https://api.memories.ai/serve/api/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.memories.ai/serve/api/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_param' => 'boat in the ocean',
    'search_type' => 'BY_CLIP',
    'top_k' => 100,
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.memories.ai/serve/api/v1/search"

	payload := strings.NewReader("{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.memories.ai/serve/api/v1/search")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.memories.ai/serve/api/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_param\": \"boat in the ocean\",\n  \"search_type\": \"BY_CLIP\",\n  \"top_k\": 100,\n  \"filtering_level\": \"medium\",\n  \"video_nos\": [\n    \"VI635764894954369024\"\n  ],\n  \"tag\": \"test1\",\n  \"camera_tag\": \"Canon EOS 5D\",\n  \"datetime_taken\": \"2025-10-20 11:00:00\",\n  \"latitude\": 88.88,\n  \"longitude\": 88.88,\n  \"folder_id\": 671631448308117500\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

Product: Visual Search Use case: Upload videos and images, auto-index them, then search by natural language, image, or transcript phrase Host: https://api.memories.ai/serve/api/v1 Auth: Authorization: sk-mavi-... (no Bearer prefix)

Search across images you have uploaded to your Private Image Library. This is a separate library from your Private Video Library — it uses a different endpoint (BY_IMAGE) and returns image results, not video clips. To search videos instead, see Search by Text, Search by Image, or Search by Transcript.

Prerequisites

You have created a memories.ai API key.
At least one image has been uploaded via Upload Image and is in PARSE status.

Endpoint

POST https://api.memories.ai/serve/api/v1/search

Use search_type=BY_IMAGE to search the Private Image Library. Using any other search_type on this endpoint searches the video library instead.

Authentication

Authorization: sk-mavi-...

Request Example

import requests

headers = {"Authorization": "sk-mavi-..."}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search",
    headers=headers,
    json={
        "search_param": "sunset over the ocean",
        "search_type": "BY_IMAGE",
        "top_k": 20
    }
)
print(response.json())

Parameters

string

required

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

string

required

Must be BY_IMAGE to search the Private Image Library.

folder_id is not supported for BY_IMAGE search and will be rejected. Folder filtering applies to video search only.

integer

default:"100"

Maximum results to return. Range: 1 – 1000.

string

Minimum similarity score:

low — score ≥ 0.15
medium — score ≥ 0.225
high — score ≥ 0.4

Omit to return all results regardless of score.

string

Filter to images carrying this tag.

string

Filter to images captured at or after this time. Format: yyyy-MM-dd HH:mm:ss.

number

GPS latitude filter. Must be paired with longitude.

number

GPS longitude filter. Must be paired with latitude.

Response

BY_IMAGE returns image items — a different response shape from video search.

{
    "code": "0000",
    "msg": "success",
    "data": {
        "current_page": 0,
        "page_size": 20,
        "total_count": 5,
        "item": [
            {
                "id": 619915496901337088,
                "name": "beach_sunset.jpg",
                "img_url": "https://storage.googleapis.com/.../beach_sunset.jpg?...",
                "datetime_taken": 1757285520000,
                "camera_model": "Canon EOS 5D",
                "latitude": 39.9042,
                "longitude": 116.4074,
                "score": 0.4711,
                "bucket": "mavi-image",
                "blob": "<user>/beach_sunset.jpg"
            }
        ]
    },
    "success": true,
    "failed": false
}

integer

Zero-based page index.

integer

Items per page.

integer

Total matching images.

integer

Unique image identifier.

string

Image filename or display name.

string

Signed URL to access the image. Expires — do not cache long-term.

integer

Capture timestamp in milliseconds since epoch.

string

Camera model recorded at upload time.

number

GPS latitude where the image was captured.

number

GPS longitude where the image was captured.

string

GCS bucket of the image. Omitted when the storage location cannot be resolved.

string

GCS blob (object) path of the image. Use it with bucket at GET /serve/api/v2/download?bucket=&blob= to fetch the file directly.

number

Relevance score. Higher is more relevant.

Notes & Limits

Rate limiting: Exceeding the per-account rate limit returns an error. See Rate limits.
Billing: Each successful call deducts credits from your account balance.

Authorizations

Authorization

string

header

required

Body

application/json

search_param

string

required

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

Example:

"boat in the ocean"

search_type

enum<string>

default:BY_CLIP

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

Available options:

BY_VIDEO,

BY_CLIP,

BY_AUDIO,

BY_IMAGE,

BY_CAPTION

Example:

"BY_CLIP"

top_k

integer

default:100

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

Required range: 1 <= x <= 1000

filtering_level

enum<string>

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

Available options:

low,

medium,

high

Example:

"medium"

video_nos

string[]

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

Maximum array length: 100

Example:

["VI635764894954369024"]

tag

string

Optional tag filter.

Example:

"test1"

camera_tag

string

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

Example:

"Canon EOS 5D"

datetime_taken

string

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

Example:

"2025-10-20 11:00:00"

latitude

number<double>

Optional latitude filter. Must be supplied together with longitude.

Example:

88.88

longitude

number<double>

Optional longitude filter. Must be supplied together with latitude.

Example:

88.88

folder_id

integer

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:

671631448308117500

Response

200 - application/json

Successful response

Response shape depends on search_type. For BY_CLIP / BY_VIDEO / BY_AUDIO data is an array of video-search items (carries video_bucket/video_blob and, for BY_CLIP, keyframe_bucket/keyframe_blob); for BY_IMAGE data is a paginated image-search object (items carry bucket/blob); for BY_CAPTION data is an array of caption-search items carrying the embedding vector, text, user_id, and time range.

code

string

Example:

"0000"

msg

string

Example:

"success"

data

object

Option 1 · object[]
Option 2 · object
Option 3 · object[]

Show child attributes

success

boolean

Example:

true

failed

boolean

Example:

false

Get Started

Index Upload

Search

Library Management

Folder Management

Reference

Prerequisites

Endpoint

Authentication

Request Example

Parameters

Response

Notes & Limits

Authorizations

Body

Response

​Prerequisites

​Endpoint

​Authentication

​Request Example

​Parameters

​Response

​Notes & Limits

Authorizations

Body

Response

Prerequisites

Endpoint

Authentication

Request Example

Parameters

Response

Notes & Limits