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

search_param

string

required

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

search_type

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.

top_k

integer

default:"100"

Maximum results to return. Range: 1 – 1000.

filtering_level

string

Minimum similarity score:

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

Omit to return all results regardless of score.

tag

string

Filter to images carrying this tag.

datetime_taken

string

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

latitude

number

GPS latitude filter. Must be paired with longitude.

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
}

data.current_page

integer

Zero-based page index.

data.page_size

integer

Items per page.

data.total_count

integer

Total matching images.

data.item[].id

integer

Unique image identifier.

data.item[].name

string

Image filename or display name.

data.item[].img_url

string

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

data.item[].datetime_taken

integer

Capture timestamp in milliseconds since epoch.

data.item[].camera_model

string

Camera model recorded at upload time.

data.item[].latitude

number

GPS latitude where the image was captured.

data.item[].longitude

number

GPS longitude where the image was captured.

data.item[].bucket

string

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

data.item[].blob

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.

data.item[].score

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

Search by Transcript Search Public — by Text

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