> ## 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 Public — by Image

> Find visually similar frames across the public TikTok / YouTube / Instagram 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 visually similar frames from the pre-indexed public social-media library. For text queries see [Search Public — by Text](/visual-search/search-public-by-text); for exact-phrase transcript search see [Search Public — by Transcript](/visual-search/search-public-by-transcript).

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).

## 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 = {"type": "TIKTOK", "similarity": 0.85}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search_public_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="type" type="string" default="TIKTOK">
  Platform to search. One of `TIKTOK`, `YOUTUBE`, `INSTAGRAM`.
</ParamField>

<ParamField body="similarity" type="number" default="0.85">
  Minimum similarity threshold (0 – 1). Only results with score ≥ this value are returned.
</ParamField>

## Response

```json theme={null}
{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "videoNo": "PI-600947902470296459",
            "videoName": "Sample public video title",
            "startTime": "79",
            "endTime": "82",
            "score": 0.8631,
            "video_bucket": "mavi-public-video",
            "video_blob": "<scraper-id>.mp4",
            "keyframe_bucket": "mavi-public-keyframe",
            "keyframe_blob": "<uuid>/keyframe-000079.jpg"
        }
    ],
    "success": true,
    "failed": false
}
```

<ResponseField name="data[].videoNo" type="string">Public video identifier (typically prefixed with `PI-`).</ResponseField>
<ResponseField name="data[].videoName" type="string">Public video title or 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 our cached copy of the public video. Omitted when the storage location cannot be resolved.</ResponseField>
<ResponseField name="data[].video_blob" type="string">GCS blob (object) path of the cached 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.


## OpenAPI

````yaml POST /serve/api/v1/search_public_similar_images
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_public_similar_images:
    post:
      summary: Search Public Videos by Image
      operationId: search_public_similar_images
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SearchSimilarImagesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSimilarImagesResponse'
components:
  schemas:
    SearchSimilarImagesRequest:
      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.
        type:
          type: string
          enum:
            - TIKTOK
            - YOUTUBE
            - INSTAGRAM
          default: TIKTOK
          description: Source platform to search within.
        similarity:
          type: number
          format: double
          minimum: 0
          maximum: 1
          default: 0.85
          description: >-
            Minimum similarity threshold (0-1). Results below this score are
            filtered out.
      required:
        - file
    SearchSimilarImagesResponse:
      type: object
      properties:
        code:
          type: string
          example: '0000'
        msg:
          type: string
          example: success
        data:
          type: array
          items:
            type: object
            properties:
              videoNo:
                type: string
                example: PI-600947902470296459
              videoName:
                type: string
                example: Sample public video title
              startTime:
                type: string
                example: '79'
              endTime:
                type: string
                example: '82'
              score:
                type: number
                format: double
                example: 0.8631
              video_bucket:
                type: string
                description: >-
                  GCS bucket of our cached copy of the public video. Omitted
                  when the storage location cannot be resolved.
              video_blob:
                type: string
                description: >-
                  GCS blob path of the cached video. Use with video_bucket at
                  GET /serve/api/v2/download to fetch the file directly.
              keyframe_bucket:
                type: string
                description: GCS bucket of the matched keyframe image.
              keyframe_blob:
                type: string
                description: GCS blob path of the matched keyframe image.
        success:
          type: boolean
          example: true
        failed:
          type: boolean
          example: false
      example:
        code: '0000'
        msg: success
        data:
          - videoNo: PI-600947902470296459
            videoName: Sample public video title
            startTime: '79'
            endTime: '82'
            score: 0.8631
            video_bucket: mavi-public-video
            video_blob: <scraper-id>.mp4
            keyframe_bucket: mavi-public-keyframe
            keyframe_blob: <uuid>/keyframe-000079.jpg
          - videoNo: PI-600947902470296460
            videoName: Another public video
            startTime: '32'
            endTime: '35'
            score: 0.8712
            video_bucket: mavi-public-video
            video_blob: <scraper-id2>.mp4
            keyframe_bucket: mavi-public-keyframe
            keyframe_blob: <uuid2>/keyframe-000032.jpg
        success: true
        failed: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````