> ## 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 — Within a Video

> Find matching time ranges inside one specific video using a query image and a natural-language prompt.

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

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](/visual-search/search-by-image); for text-only queries use [Search by Text](/visual-search/search-by-text).

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).
* The target 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 = {
    "video_no": "VI625239098370850816",
    "prompt": "focus on the red shirt, ignore background"
}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search_clips_by_image",
    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="video_no" type="string" required>
  Identifier of the video to search within (e.g. `VI625239098370850816`).
</ParamField>

<ParamField body="prompt" type="string" required>
  Natural-language prompt that refines the match (e.g. `"focus on the red shirt"`). Use English for best results.
</ParamField>

## Response

```json theme={null}
{
    "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
}
```

<ResponseField name="data[].start_time" type="number">Clip start time, in seconds.</ResponseField>
<ResponseField name="data[].end_time" type="number">Clip end time, in seconds.</ResponseField>
<ResponseField name="data[].score" type="number">Similarity score (0 – 1).</ResponseField>
<ResponseField name="data[].video_bucket" type="string">GCS bucket of the target video file. Omitted when the storage location cannot be resolved.</ResponseField>
<ResponseField name="data[].video_blob" type="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.</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.


## OpenAPI

````yaml POST /serve/api/v1/search_clips_by_image
openapi: 3.1.0
info:
  title: Memories Platform API (Docs Mapping)
  version: v1
  description: OpenAPI mapping used by Mintlify Try it for the platform docs.
servers:
  - url: https://api.memories.ai
security:
  - ApiKeyAuth: []
paths:
  /serve/api/v1/search_clips_by_image:
    post:
      summary: Search Clips by Image
      operationId: search_clips_by_image
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SearchClipsByImageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchClipsByImageResponse'
components:
  schemas:
    SearchClipsByImageRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: >-
            Query image. Allowed extensions: .jpg/.jpeg/.png/.gif/.bmp/.webp.
            Content-Type must start with image/. Max 20 MB.
        video_no:
          type: string
          example: VI625239098370850816
          description: Unique identifier of the video to search within. Must be non-empty.
        prompt:
          type: string
          example: focus on the red shirt, ignore background color
          description: >-
            Natural-language prompt that refines the visual match. Must be
            non-empty. English recommended.
      required:
        - file
        - video_no
        - prompt
    SearchClipsByImageResponse:
      type: object
      properties:
        code:
          type: string
          example: '0000'
        msg:
          type: string
          example: success
        data:
          type: array
          items:
            type: object
            properties:
              start_time:
                type: number
                format: double
                example: 12.5
                description: Clip start time in seconds.
              end_time:
                type: number
                format: double
                example: 18.2
                description: Clip end time in seconds.
              score:
                type: number
                format: double
                example: 0.8631
                description: Similarity score.
              video_bucket:
                type: string
                description: >-
                  GCS bucket of the target video file. Omitted when the storage
                  location cannot be resolved.
              video_blob:
                type: string
                description: >-
                  GCS blob path of the target video. Use with video_bucket at
                  GET /serve/api/v2/download to fetch the file directly.
        success:
          type: boolean
          example: true
        failed:
          type: boolean
          example: false
      example:
        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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````