Skip to main content
POST
/
serve
/
api
/
v1
/
search
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",
  "unique_id": "default",
  "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
}
'
{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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",
        "unique_id": "default",
        "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.
​
unique_id
string
default:"default"
Namespace scoping the search to a folder in your account.
​
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"

​
unique_id
string
default:default

Scope/folder identifier for the authenticated account.

​
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

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
​
success
boolean
Example:

true

​
failed
boolean
Example:

false