> ## 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.

# Search by Image

> Find visually similar frames across all videos in your Private Video Library using a query image.

<Info>
  **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)
</Info>

Upload a query image and retrieve frames from anywhere in your Private Video Library that are visually similar. To restrict the search to one specific video instead, use [Search by Image — Within a Video](/visual-search/search-by-image-in-video). For text queries see [Search by Text](/visual-search/search-by-text).

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).
* At least one video has been uploaded and is in `PARSE` status.

## Request Example

<Note>Uses `multipart/form-data`. The `file` part carries the query image; other parameters are sent as form fields.</Note>

```python theme={null}
import requests

headers = {"Authorization": "sk-mavi-..."}
files = [("file", ("query.png", open("query.png", "rb"), "image/png"))]
data = {"folder_id": 671631448308117504, "similarity": 0.85}

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

## Parameters

<ParamField body="file" type="file" required>
  Query image. Allowed: `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.webp`. Maximum **20 MB**.
</ParamField>

<ParamField body="folder_id" type="integer">
  Optional. Restrict results to a single folder. Omit to query across your entire account. `-1` is the Default folder. Must be a folder that belongs to your account.
</ParamField>

<ParamField body="similarity" type="number" default="0.85">
  Minimum similarity threshold (0 – 1).
</ParamField>

## Response

```json theme={null}
{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "videoNo": "VI576925607808602112",
            "videoName": "beach_day.mp4",
            "startTime": "42",
            "score": 0.9123,
            "video_bucket": "mavi-resource",
            "video_blob": "VI576925607808602112.mp4",
            "keyframe_bucket": "mavi-keyframe",
            "keyframe_blob": "<uuid>/keyframe-000042.jpg"
        }
    ],
    "success": true,
    "failed": false
}
```

<ResponseField name="data[].videoNo" type="string">Identifier of the matched video.</ResponseField>
<ResponseField name="data[].videoName" type="string">Internal stored name.</ResponseField>
<ResponseField name="data[].startTime" type="string">Matched keyframe start time, in seconds.</ResponseField>
<ResponseField name="data[].endTime" type="string">Matched keyframe end time, in seconds.</ResponseField>
<ResponseField name="data[].score" type="number">Visual similarity score (0 – 1).</ResponseField>
<ResponseField name="data[].video_bucket" type="string">GCS bucket of the original video file. Omitted when the storage location cannot be resolved.</ResponseField>
<ResponseField name="data[].video_blob" type="string">GCS blob (object) path of the original video. Use it with `video_bucket` at `GET /serve/api/v2/download?bucket=&blob=` to fetch the file directly.</ResponseField>
<ResponseField name="data[].keyframe_bucket" type="string">GCS bucket of the matched keyframe image.</ResponseField>
<ResponseField name="data[].keyframe_blob" type="string">GCS blob (object) path of the matched keyframe image.</ResponseField>

## Notes & Limits

* **Rate limiting**: Exceeding the per-account rate limit returns an error. See [Rate limits](/visual-search/rate-limits).
* **Billing**: Each successful call deducts credits from your account balance.