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
    }
  ],
  "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.

​
Prerequisites

  • You’re familiar with the concepts described on the Platform overview.
  • You have created a memories.ai API key.
  • At least one video/image has been uploaded to memories.ai and is currently in PARSE status.

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/search 
/serve/api/v1/search

​
Authentication

Pass your API key in the Authorization request header. Requests without a valid API key are rejected. 
Authorization: <API_KEY>

​
Content Type

The endpoint expects a JSON body (application/json).

​
Request Example

import requests

headers = {"Authorization": "<API_KEY>"}

json_body = {
    "search_param": "<YOUR_PROMPT>",
    "search_type": "BY_CLIP",
    "unique_id": "default",
    "top_k": 10,
    "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
}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search",
    headers=headers,
    json=json_body
)
print(response.json())

​
Request Parameters

​
search_param
string
required
The natural-language search query. Must be non-empty.
​
search_type
string
default:"BY_CLIP"
One of BY_VIDEO, BY_CLIP, BY_AUDIO, BY_IMAGE. Defaults to BY_CLIP when omitted. BY_VIDEO is treated as BY_CLIP internally.
​
unique_id
string
default:"default"
Scope identifier used to select the folder to search against for the authenticated account. If the folder for this unique_id does not exist yet, it is created automatically. Must be non-empty when explicitly provided.
​
top_k
integer
default:"100"
Maximum number of results to return. Must be an integer in the range 1 – 1000 inclusive.
​
filtering_level
string
Similarity-score filter strength. One of low, medium, high (corresponds to minimum scores of 0.15, 0.225, 0.4 respectively). When omitted no level filter is applied.
​
video_nos
array
Optional list of video numbers to restrict the search to. Maximum 100 entries.
​
tag
string
Optional tag filter. Only results whose videos/images carry the tag are returned.
​
camera_tag
string
Optional camera/device model filter. Matches the camera_model field supplied at upload time.
​
datetime_taken
string
Optional capture time filter in the exact format yyyy-MM-dd HH:mm:ss (e.g. 2025-10-20 11:00:00). Invalid formats are rejected.
​
latitude
number
Optional latitude filter (decimal). Must be supplied together with longitude; supplying only one returns a validation error.
​
longitude
number
Optional longitude filter (decimal). Must be supplied together with latitude.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account search rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
  • Billing: This endpoint is metered — each successful call deducts points from your account balance.
  • Search modalities: BY_CLIP / BY_VIDEO search visual segments; BY_AUDIO searches spoken transcripts; BY_IMAGE searches the image library (response shape differs — see below).

​
Response Example — Video / Audio search (BY_CLIP / BY_VIDEO / BY_AUDIO)

{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "videoNo": "VI576925607808602112",
            "videoName": "1920447021987282945",
            "startTime": "13",
            "endTime": "18",
            "audio_ts": "...matched transcript text...",
            "score": 0.5221236659362116
        }
    ],
    "success": true,
    "failed": false
}

​
Response Fields

​
data[].videoNo
string
Video identifier.
​
data[].videoName
string
Internal stored name of the video.
​
data[].startTime
string
Matched segment start time, in seconds (as string).
​
data[].endTime
string
Matched segment end time, in seconds (as string).
​
data[].audio_ts
string
Matched audio transcript text (populated for BY_AUDIO and when audio transcription is available).
​
data[].score
number
Relevance score of the match.

​
Response Example — Image search (BY_IMAGE)

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

​
Response Fields

​
data.current_page
integer
Zero-based page index of the returned slice.
​
data.page_size
integer
Number of items per page.
​
data.total_count
integer
Total number of matching images.
​
data.item[].id
integer
Unique image identifier.
​
data.item[].name
string
Image file name / display name.
​
data.item[].img_url
string
Signed URL to the image.
​
data.item[].datetime_taken
integer
Capture time in milliseconds since epoch.
​
data.item[].camera_model
string
Camera/device model recorded at upload.
​
data.item[].latitude
number
Capture latitude.
​
data.item[].longitude
number
Capture longitude.
​
data.item[].score
number
Relevance score of the match.

​
Best Practices

  • Use top_k: Limit results to the most relevant items for efficiency.
  • Filter tuning: Adjust filtering_level to balance recall and precision (low = broad, high = strict).
  • Prompt clarity: Make search queries concise and descriptive for optimal ranking.

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.

Available options:
BY_VIDEO,
BY_CLIP,
BY_AUDIO,
BY_IMAGE
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.

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; for BY_IMAGE data is a paginated image-search object.

​
code
string
Example:

"0000"

​
msg
string
Example:

"success"

​
data
object
​
success
boolean
Example:

true

​
failed
boolean
Example:

false