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",
"top_k": 100,
"filtering_level": "medium"
}
'import requests
url = "https://api.memories.ai/serve/api/v1/search_public"
payload = {
"search_param": "Find sprint race with Usain Bolt",
"search_type": "BY_VIDEO",
"type": "TIKTOK",
"top_k": 100,
"filtering_level": "medium"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
search_param: 'Find sprint race with Usain Bolt',
search_type: 'BY_VIDEO',
type: 'TIKTOK',
top_k: 100,
filtering_level: 'medium'
})
};
fetch('https://api.memories.ai/serve/api/v1/search_public', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.memories.ai/serve/api/v1/search_public",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'search_param' => 'Find sprint race with Usain Bolt',
'search_type' => 'BY_VIDEO',
'type' => 'TIKTOK',
'top_k' => 100,
'filtering_level' => 'medium'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.memories.ai/serve/api/v1/search_public"
payload := strings.NewReader("{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.memories.ai/serve/api/v1/search_public")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.memories.ai/serve/api/v1/search_public")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}"
response = http.request(request)
puts response.read_body{
"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
}Public Video Library
Search Public — by Text
Semantic text search across the public TikTok / YouTube / Instagram video library.
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",
"top_k": 100,
"filtering_level": "medium"
}
'import requests
url = "https://api.memories.ai/serve/api/v1/search_public"
payload = {
"search_param": "Find sprint race with Usain Bolt",
"search_type": "BY_VIDEO",
"type": "TIKTOK",
"top_k": 100,
"filtering_level": "medium"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
search_param: 'Find sprint race with Usain Bolt',
search_type: 'BY_VIDEO',
type: 'TIKTOK',
top_k: 100,
filtering_level: 'medium'
})
};
fetch('https://api.memories.ai/serve/api/v1/search_public', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.memories.ai/serve/api/v1/search_public",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'search_param' => 'Find sprint race with Usain Bolt',
'search_type' => 'BY_VIDEO',
'type' => 'TIKTOK',
'top_k' => 100,
'filtering_level' => 'medium'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.memories.ai/serve/api/v1/search_public"
payload := strings.NewReader("{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.memories.ai/serve/api/v1/search_public")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.memories.ai/serve/api/v1/search_public")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"search_param\": \"Find sprint race with Usain Bolt\",\n \"search_type\": \"BY_VIDEO\",\n \"type\": \"TIKTOK\",\n \"top_k\": 100,\n \"filtering_level\": \"medium\"\n}"
response = http.request(request)
puts response.read_body{
"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
}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)Prerequisites
- You have created a memories.ai API key.
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
string
required
Natural-language search query. Must be non-empty.
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_CLIPis an accepted alias.BY_AUDIO— spoken-word transcripts (semantic, not exact-match).audio_tsis only populated in the response for this mode.
code: "0003" and a JSON deserialization error listing the live enum values.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.integer
default:"100"
Maximum results to return. Range: 1 – 1000.
string
Minimum similarity score threshold:
low— score ≥ 0.15medium— score ≥ 0.225high— score ≥ 0.4
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
}
string
Public video identifier (typically prefixed with
PI-).string
Public video title or name.
string
Matched segment start time, in seconds.
string
Matched segment end time, in seconds.
string
Transcript text of the segment. Populated for
BY_AUDIO searches.number
Relevance score. Higher is more relevant.
string
GCS bucket of our cached copy of the public video. Omitted when the storage location cannot be resolved.
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.string
GCS bucket of the matched keyframe image (
BY_CLIP only).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
Body
application/json
Natural-language search query. Must be non-empty.
Example:
"Find sprint race with Usain Bolt"
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"
Source platform to search within.
Available options:
TIKTOK, YOUTUBE, INSTAGRAM Maximum number of results to return. Range 1-1000.
Required range:
1 <= x <= 1000Similarity-score filter. low=0.15, medium=0.225, high=0.4.
Available options:
low, medium, high Example:
"medium"
