Skip to main content
POST
/
serve
/
api
/
v1
/
search_public
Search from Public Video Sources
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/search_public \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_param": "Find sprint race with Usain Bolt",
  "search_type": "BY_VIDEO",
  "type": "TIKTOK",
  "unique_id": "default",
  "top_k": 100,
  "filtering_level": "medium"
}
'
{
  "code": "0000",
  "msg": "success",
  "data": [
    {
      "videoNo": "PI-600947902470296459",
      "videoName": "They played in their OPPONENTS jerseys?!?",
      "startTime": "23",
      "endTime": "27",
      "audio_ts": "...matched transcript text...",
      "score": 0.7350679636001586,
      "video_bucket": "mavi-public-video",
      "video_blob": "<scraper-id>.mp4",
      "keyframe_bucket": "mavi-public-keyframe",
      "keyframe_blob": "<uuid>/keyframe-000023.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)
Use a natural-language query to find relevant clips or audio moments from the pre-indexed public social-media library — no upload required. For image queries see Search Public — by Image; for exact-phrase transcript search see Search Public — by Transcript.

​
Prerequisites

​
Request Example

import requests

headers = {"Authorization": "sk-mavi-..."}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search_public",
    headers=headers,
    json={
        "search_param": "sprint race with Usain Bolt",
        "search_type": "BY_VIDEO",
        "type": "TIKTOK",
        "top_k": 10,
        "filtering_level": "medium"
    }
)
print(response.json())

​
Parameters

​
search_param
string
required
Natural-language search query. Must be non-empty.
​
search_type
string
default:"BY_VIDEO"
What to search. The server-side enum is [BY_CLIP, BY_VIDEO, BY_AUDIO, BY_IMAGE]; only the first three are meaningful here (BY_IMAGE is exposed via the dedicated Search Public — by Image endpoint).
  • BY_VIDEO — video clips (default). BY_CLIP is an accepted alias.
  • BY_AUDIO — spoken-word transcripts (semantic, not exact-match). audio_ts is only populated in the response for this mode.
Unknown values are rejected with code: "0003" and a JSON deserialization error listing the live enum values.
​
type
string
default:"TIKTOK"
Platform to search. One of TIKTOK, YOUTUBE, INSTAGRAM. The server does not validate this string — passing an unknown value silently falls back to a default rather than returning an error, so prefer one of the documented values explicitly.
​
top_k
integer
default:"100"
Maximum results to return. Range: 1 – 1000.
​
filtering_level
string
Minimum similarity score threshold:
  • low — score ≥ 0.15
  • medium — score ≥ 0.225
  • high — score ≥ 0.4
When omitted, no score filter is applied.

​
Response

{
    "code": "0000",
    "msg": "success",
    "data": [
        {
            "videoNo": "PI-600947902470296459",
            "videoName": "They played in their OPPONENTS jerseys?!?",
            "startTime": "23",
            "endTime": "27",
            "audio_ts": "...matched transcript text...",
            "score": 0.7350679636001586,
            "video_bucket": "mavi-public-video",
            "video_blob": "<scraper-id>.mp4",
            "keyframe_bucket": "mavi-public-keyframe",
            "keyframe_blob": "<uuid>/keyframe-000023.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 segment start time, in seconds.
​
data[].endTime
string
Matched segment end time, in seconds.
​
data[].audio_ts
string
Transcript text of the segment. Populated for BY_AUDIO searches.
​
data[].score
number
Relevance score. Higher is more relevant.
​
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 (BY_CLIP only).
​
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

application/json
​
search_param
string
required

Natural-language search query. Must be non-empty.

Example:

"Find sprint race with Usain Bolt"

​
search_type
enum<string>
default:BY_CLIP

Search modality. Only BY_VIDEO and BY_AUDIO are accepted here; BY_CLIP and BY_IMAGE are explicitly rejected. BY_VIDEO is treated as BY_CLIP internally.

Available options:
BY_VIDEO,
BY_AUDIO
Example:

"BY_VIDEO"

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

​
top_k
integer
default:100

Maximum number of results to return. Range 1-1000.

Required range: 1 <= x <= 1000
​
filtering_level
enum<string>

Similarity-score filter. low=0.15, medium=0.225, high=0.4.

Available options:
low,
medium,
high
Example:

"medium"

Response

200 - application/json

Successful response

​
code
string
Example:

"0000"

​
msg
string
Example:

"success"

​
data
object[]
​
success
boolean
Example:

true

​
failed
boolean
Example:

false