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
    }
  ],
  "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.

​
Prerequisites

  • You’re familiar with the concepts described on the Platform overview.
  • You have created a memories.ai API key.

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/search_public 
/serve/api/v1/search_public

​
Authentication

Pass your API key in the Authorization request header. Requests without a valid API key are rejected. 
Authorization: <API_KEY>

​
Content Type

The endpoint expects a JSON body (application/json).

​
Request Example

import requests

headers = {"Authorization": "<API_KEY>"}

json_body = {
    "search_param": "<YOUR_PROMPT>",
    "search_type": "BY_VIDEO",
    "type": "TIKTOK",
    "unique_id": "default",
    "top_k": 10,
    "filtering_level": "medium"
}

response = requests.post(
    "https://api.memories.ai/serve/api/v1/search_public",
    headers=headers,
    json=json_body
)
print(response.json())

​
Request Body Example

{
    "search_param": "Find sprint race with Usain Bolt",
    "search_type": "BY_VIDEO",
    "type": "TIKTOK",
    "top_k": 3,
    "filtering_level": "medium"
}

​
Request Parameters

​
search_param
string
required
The natural-language search query. Must be non-empty.
​
search_type
string
default:"BY_CLIP"
Search modality. Must be BY_VIDEO or BY_AUDIO. BY_VIDEO is treated as BY_CLIP internally. Sending BY_CLIP or BY_IMAGE is explicitly rejected on this endpoint (use the dedicated clip/image search endpoints instead).
​
type
string
default:"TIKTOK"
Source platform to search within. One of TIKTOK, YOUTUBE, INSTAGRAM. Defaults to TIKTOK when omitted.
​
unique_id
string
default:"default"
Scope identifier for the authenticated account. Must be non-empty when explicitly provided.
​
top_k
integer
default:"100"
Maximum number of results to return. Must be an integer in the range 1 – 1000 inclusive.
​
filtering_level
string
Similarity-score filter strength. One of low, medium, high (corresponds to minimum scores of 0.15, 0.225, 0.4 respectively). When omitted no level filter is applied.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account public-search rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
  • Billing: This endpoint is metered — each successful call deducts points from your account balance.
  • Unsupported search_type values on this endpoint:
    • BY_CLIP → rejected with “Search type BY_CLIP is not supported in this API endpoint. Please use the search_clip endpoint instead.”
    • BY_IMAGE → rejected with “Search public type BY_IMAGE is not supported in this API endpoint.”

​
Response Example

{
    "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
        }
    ],
    "success": true,
    "failed": false
}

​
Response Fields

​
code
string
Business status code. 0000 indicates success.
​
msg
string
Human-readable status message.
​
data[].videoNo
string
Public video identifier (typically prefixed with PI-).
​
data[].videoName
string
Public video title/name.
​
data[].startTime
string
Matched segment start time, in seconds (as string).
​
data[].endTime
string
Matched segment end time, in seconds (as string).
​
data[].audio_ts
string
Matched audio transcript text (populated for BY_AUDIO).
​
data[].score
number
Relevance score of the match.

​
Best Practices

  • Platform selection: Use the type parameter to specify the desired dataset (TikTok, YouTube, Instagram).
  • Use top_k: Limit results to the most relevant items for efficiency.
  • Filter tuning: Adjust filtering_level to balance recall and precision (low = broad, high = strict).
  • Prompt clarity: Make queries concise and descriptive for optimal retrieval.

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