Skip to main content
POST
/
serve
/
api
/
v1
/
search_clips_by_image
Search Clips by Image
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/search_clips_by_image \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form video_no=VI625239098370850816 \
  --form 'prompt=focus on the red shirt, ignore background color' \
  --form unique_id=default
{
  "code": "0000",
  "msg": "success",
  "data": [
    {
      "start_time": 12.5,
      "end_time": 18.2,
      "score": 0.8631,
      "video_bucket": "mavi-resource",
      "video_blob": "VI576925607808602112.mp4"
    },
    {
      "start_time": 42,
      "end_time": 47.8,
      "score": 0.8124,
      "video_bucket": "mavi-resource",
      "video_blob": "VI576925607808602112.mp4"
    }
  ],
  "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 within a single video. Combine a query image with a natural-language prompt to refine what the search treats as a match (e.g. “focus on the red shirt”). For library-wide image search use Search by Image; for text-only queries use Search by Text.

​
Prerequisites

​
Request Example

Uses multipart/form-data. The file part carries the query image; other parameters are sent as form fields.
import requests

headers = {"Authorization": "sk-mavi-..."}
files = [("file", ("query.png", open("query.png", "rb"), "image/png"))]
data = {
    "video_no": "VI625239098370850816",
    "prompt": "focus on the red shirt, ignore background",
    "unique_id": "default"
}

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

​
Parameters

​
file
file
required
Query image. Allowed: .jpg, .jpeg, .png, .gif, .bmp, .webp. Maximum 20 MB.
​
video_no
string
required
Identifier of the video to search within (e.g. VI625239098370850816).
​
prompt
string
required
Natural-language prompt that refines the match (e.g. "focus on the red shirt"). Use English for best results.
​
unique_id
string
default:"default"
Namespace scoping the search to a folder in your account.

​
Response

{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "start_time": 12.5,
            "end_time": 18.2,
            "score": 0.8631,
            "video_bucket": "mavi-resource",
            "video_blob": "VI576925607808602112.mp4"
        },
        {
            "start_time": 42.0,
            "end_time": 47.8,
            "score": 0.8124,
            "video_bucket": "mavi-resource",
            "video_blob": "VI576925607808602112.mp4"
        }
    ],
    "success": true,
    "failed": false
}
​
data[].start_time
number
Clip start time, in seconds.
​
data[].end_time
number
Clip end time, in seconds.
​
data[].score
number
Similarity score (0 – 1).
​
data[].video_bucket
string
GCS bucket of the target video file. Omitted when the storage location cannot be resolved.
​
data[].video_blob
string
GCS blob (object) path of the target video. Use it with video_bucket at GET /serve/api/v2/download?bucket=&blob= to fetch the file directly.

​
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

multipart/form-data
​
file
file
required

Query image. Allowed extensions: .jpg/.jpeg/.png/.gif/.bmp/.webp. Content-Type must start with image/. Max 20 MB.

​
video_no
string
required

Unique identifier of the video to search within. Must be non-empty.

Example:

"VI625239098370850816"

​
prompt
string
required

Natural-language prompt that refines the visual match. Must be non-empty. English recommended.

Example:

"focus on the red shirt, ignore background color"

​
unique_id
string
default:default

Scope identifier for the authenticated account.

Response

200 - application/json

Successful response

​
code
string
Example:

"0000"

​
msg
string
Example:

"success"

​
data
object[]
​
success
boolean
Example:

true

​
failed
boolean
Example:

false