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
    },
    {
      "start_time": 42,
      "end_time": 47.8,
      "score": 0.8124
    }
  ],
  "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.

​
Overview

The Search Clips by Image API lets you upload a query image together with a natural-language prompt and finds the time ranges (clips) within a single specified video that best match both. The prompt lets you steer the visual search toward particular attributes (e.g. “focus on the red shirt”, “ignore the background”).

​
Prerequisites

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

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/search_clips_by_image 
/serve/api/v1/search_clips_by_image

​
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 multipart/form-data. The file part carries the query image; other parameters are sent as form fields.

​
Request Example

import requests

url = "https://api.memories.ai/serve/api/v1/search_clips_by_image"
payload = {
    "video_no": "VI625239098370850816",
    "prompt": "focus on the red shirt, ignore background color",
    "unique_id": "default"
}
files = [
    ("file", ("query.png", open("/path/to/query.png", "rb"), "image/png"))
]
headers = {"Authorization": "<API_KEY>"}

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

​
Request Parameters

​
file
file
required
Query image. Must not be empty. Allowed extensions: .jpg, .jpeg, .png, .gif, .bmp, .webp (case-insensitive). Content-Type must start with image/. Maximum size 20 MB.
​
video_no
string
required
Unique identifier of the video to search within (e.g. VI625239098370850816). Must be non-empty.
​
prompt
string
required
Natural-language prompt that refines the visual match (e.g. “focus on the red shirt”). Required — the server rejects the request with “The prompt parameter cannot be empty!” when absent. Use English for best results.
​
unique_id
string
default:"default"
Scope identifier for the authenticated account.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account 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.
  • File validation: A request whose file fails any check (empty, unsupported type/extension, > 20 MB) is rejected immediately with an error identifying the offending filename.
  • Scope: Searching is restricted to the single video identified by video_no; this endpoint does not search across a library.

​
Response Example

{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "start_time": 12.5,
            "end_time": 18.2,
            "score": 0.8631
        },
        {
            "start_time": 42.0,
            "end_time": 47.8,
            "score": 0.8124
        }
    ],
    "success": true,
    "failed": false
}

​
Response Fields

​
code
string
Business status code. 0000 indicates success.
​
msg
string
Human-readable status message.
​
data[].start_time
number
Clip start time, in seconds.
​
data[].end_time
number
Clip end time, in seconds.
​
data[].score
number
Similarity / relevance score of the matched clip.

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