Skip to main content
POST
/
serve
/
api
/
v1
/
search_public_similar_images
Search Public Videos by Image
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/search_public_similar_images \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form type=TIKTOK \
  --form unique_id=default \
  --form similarity=0.85
{
  "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
}

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)
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; for exact-phrase transcript search see Search Public — by Transcript.

​
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 = {"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

​
file
file
required
Query image. Allowed: .jpg, .jpeg, .png, .gif, .bmp, .webp. Maximum 20 MB.
​
type
string
default:"TIKTOK"
Platform to search. One of TIKTOK, YOUTUBE, INSTAGRAM.
​
similarity
number
default:"0.85"
Minimum similarity threshold (0 – 1). Only results with score ≥ this value are returned.

​
Response

{
    "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
}
​
data[].videoNo
string
Public video identifier (typically prefixed with PI-).
​
data[].videoName
string
Public video title or name.
​
data[].startTime
string
Matched keyframe start time, in seconds.
​
data[].endTime
string
Matched keyframe end time, in seconds.
​
data[].score
number
Visual similarity score (0 – 1).
​
data[].video_bucket
string
GCS bucket of our cached copy of the public video. Omitted when the storage location cannot be resolved.
​
data[].video_blob
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.
​
data[].keyframe_bucket
string
GCS bucket of the matched keyframe image.
​
data[].keyframe_blob
string
GCS blob (object) path of the matched keyframe image.

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

​
type
enum<string>
default:TIKTOK

Source platform to search within.

Available options:
TIKTOK,
YOUTUBE,
INSTAGRAM
​
unique_id
string
default:default

Scope identifier for the authenticated account.

​
similarity
number<double>
default:0.85

Minimum similarity threshold (0-1). Results below this score are filtered out.

Required range: 0 <= x <= 1

Response

200 - application/json

Successful response

​
code
string
Example:

"0000"

​
msg
string
Example:

"success"

​
data
object[]
​
success
boolean
Example:

true

​
failed
boolean
Example:

false