Search Public — by Text - Memories.ai API

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
}

POST

serve

api

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)

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

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

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

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

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

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[]

Show child attributes

success

boolean

Example:

true

failed

boolean

Example:

false

Get Started

Index Upload

Search

Library Management

Folder Management

Reference

Search Public — by Text

Prerequisites

Request Example

Parameters

Response

Notes & Limits

Authorizations

Body

Response

​Prerequisites

​Request Example

​Parameters

​Response

​Notes & Limits

Authorizations

Body

Response

Prerequisites

Request Example

Parameters

Response

Notes & Limits