> ## 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.
# Search by Text
> Semantic search across your Private Video Library with a natural-language query.
**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 retrieve the most semantically similar clip segments from your Private Video Library. This is the canonical "find me a moment" endpoint.
For related operations: [Search by Image (library-wide)](/visual-search/search-by-image) · [Search by Image (within a video)](/visual-search/search-by-image-in-video) · [Search by Transcript](/visual-search/search-by-transcript).
## Prerequisites
* You have [created a memories.ai API key](/visual-search/create-your-key).
* At least one video has been uploaded and is in `PARSE` status.
## Request Example
```python theme={null}
import requests
headers = {"Authorization": "sk-mavi-..."}
response = requests.post(
"https://api.memories.ai/serve/api/v1/search",
headers=headers,
json={
"search_param": "person walking on a beach at sunset",
"search_type": "BY_CLIP",
"folder_id": 671631448308117504,
"top_k": 10,
"filtering_level": "medium"
}
)
print(response.json())
```
## Parameters
Natural-language search query. Must be non-empty.
What to return:
* `BY_CLIP` — video clip segments (default). `BY_VIDEO` is an accepted alias.
* `BY_AUDIO` — audio moments (semantic match against transcripts).
* `BY_CAPTION` — caption-level vector search against the `video_transcript` table; the response shape is different (see [BY\_CAPTION response](#by-caption-response) below).
Server-side enum is `[BY_CLIP, BY_VIDEO, BY_AUDIO, BY_IMAGE, BY_CAPTION]`. `BY_IMAGE` is exposed via [Search by Image (within a video)](/visual-search/search-by-image-in-video).
Optional. Restrict results to a single folder. Omit to query across your entire account. `-1` is the Default folder. Must be a folder that belongs to your account.
Maximum results to return.
* For `BY_CLIP` / `BY_AUDIO`: range **1 – 1000**.
* For `BY_CAPTION`: range **1 – 200** (server-side default is **10** when `top_k` is `null`; otherwise the value you send is used).
Minimum similarity score:
* `low` — score ≥ 0.15
* `medium` — score ≥ 0.225
* `high` — score ≥ 0.4
Omit to return all results regardless of score.
Restrict search to these specific videos. Accepts up to **100** video IDs.
Filter to content carrying this tag.
Filter by camera model (must match `camera_model` set at upload time).
Filter to content captured at or after this time. Format: `yyyy-MM-dd HH:mm:ss`.
GPS latitude filter. Must be paired with `longitude`.
GPS longitude filter. Must be paired with `latitude`.
## Response
```json theme={null}
{
"code": "0000",
"msg": "success",
"data": [
{
"videoNo": "VI576925607808602112",
"videoName": "1920447021987282945",
"startTime": "13",
"endTime": "18",
"audio_ts": "the sun was setting over the water",
"score": 0.5221236659362116,
"video_bucket": "mavi-resource",
"video_blob": "VI576925607808602112.mp4",
"keyframe_bucket": "mavi-keyframe",
"keyframe_blob": "/keyframe-000013.jpg"
}
],
"success": true,
"failed": false
}
```
Unique identifier of the matched video.
Internal stored name of the video.
Start time of the matched segment, in seconds.
End time of the matched segment, in seconds.
Transcript text. Populated for `BY_AUDIO` searches when transcription is available.
Relevance score. Higher is more relevant.
GCS bucket of the original video file. Omitted when the storage location cannot be resolved.
GCS blob (object) path of the original video. Use it with `video_bucket` at `GET /serve/api/v2/download?bucket=&blob=` to fetch the file directly.
GCS bucket of the matched keyframe image (`BY_CLIP` only).
GCS blob (object) path of the matched keyframe image.
## BY\_CAPTION Response
When `search_type=BY_CAPTION`, the endpoint performs a vector similarity search over the `video_transcript` table and returns a different item shape:
```json theme={null}
{
"code": "0000",
"msg": "success",
"data": [
{
"video_no": "VI576925607808602112",
"text": "the sun was setting over the water",
"vector": [0.012, -0.034, 0.005, "..."],
"user_id": "",
"start_time": 12.5,
"end_time": 18.7,
"score": 0.82
}
],
"success": true,
"failed": false
}
```
Unique identifier of the matched video.
The caption segment text that matched.
Stored embedding vector of the matched caption row. Dimensionality is set by the embedding model and may be hundreds of floats — response size can grow accordingly.
Internal MD5-encoded user namespace identifier.
Start time of the matched caption, in seconds.
End time of the matched caption, in seconds.
Similarity score (`1 - distance`). Higher is more similar.
## Notes & Limits
* **Rate limiting**: Exceeding the per-account rate limit returns an error. See [Rate limits](/visual-search/rate-limits).
* **Billing**: Each successful call deducts credits from your account balance.
## OpenAPI
````yaml POST /serve/api/v1/search
openapi: 3.1.0
info:
title: Memories Platform API (Docs Mapping)
version: v1
description: OpenAPI mapping used by Mintlify Try it for the platform docs.
servers:
- url: https://api.memories.ai
security:
- ApiKeyAuth: []
paths:
/serve/api/v1/search:
post:
summary: Search from Private Library
operationId: search_private_library
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPrivateRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPrivateResponse'
components:
schemas:
SearchPrivateRequest:
type: object
properties:
search_param:
type: string
example: boat in the ocean
description: Natural-language search query. Must be non-empty.
search_type:
type: string
enum:
- BY_VIDEO
- BY_CLIP
- BY_AUDIO
- BY_IMAGE
- BY_CAPTION
default: BY_CLIP
example: BY_CLIP
description: >-
Search modality. BY_VIDEO is treated as BY_CLIP internally.
BY_CAPTION performs vector search over the video_transcript table
and returns a different item shape (see response).
top_k:
type: integer
default: 100
minimum: 1
maximum: 1000
description: >-
Maximum number of results to return. Range 1-1000 for
BY_CLIP/BY_AUDIO/BY_IMAGE. For BY_CAPTION the range is 1-200
(server-side default is 10 when null).
filtering_level:
type: string
enum:
- low
- medium
- high
example: medium
description: Similarity-score filter. low=0.15, medium=0.225, high=0.4.
video_nos:
type: array
items:
type: string
maxItems: 100
example:
- VI635764894954369024
description: Optional list of video numbers to restrict the search to. Max 100.
tag:
type: string
example: test1
description: Optional tag filter.
camera_tag:
type: string
example: Canon EOS 5D
description: >-
Optional camera/device model filter. Matches the camera_model
supplied at upload time.
datetime_taken:
type: string
example: '2025-10-20 11:00:00'
description: Optional capture-time filter in format yyyy-MM-dd HH:mm:ss.
latitude:
type: number
format: double
example: 88.88
description: Optional latitude filter. Must be supplied together with longitude.
longitude:
type: number
format: double
example: 88.88
description: Optional longitude filter. Must be supplied together with latitude.
folder_id:
type: integer
description: >-
Optional. Restrict results to a single folder. Omit to query across
your entire account. -1 is the Default folder; a positive id must
belong to your account.
example: 671631448308117500
required:
- search_param
SearchPrivateResponse:
type: object
description: >-
Response shape depends on search_type. For BY_CLIP / BY_VIDEO / BY_AUDIO
`data` is an array of video-search items (carries
video_bucket/video_blob and, for BY_CLIP,
keyframe_bucket/keyframe_blob); for BY_IMAGE `data` is a paginated
image-search object (items carry bucket/blob); for BY_CAPTION `data` is
an array of caption-search items carrying the embedding vector, text,
user_id, and time range.
properties:
code:
type: string
example: '0000'
msg:
type: string
example: success
data:
oneOf:
- type: array
items:
type: object
properties:
videoNo:
type: string
example: VI576925607808602112
videoName:
type: string
example: '1920447021987282945'
startTime:
type: string
example: '13'
description: Matched segment start time in seconds.
endTime:
type: string
example: '18'
description: Matched segment end time in seconds.
audio_ts:
type: string
description: Matched audio transcript (BY_AUDIO).
score:
type: number
format: double
example: 0.5221236659362116
video_bucket:
type: string
description: >-
GCS bucket of the original video file. Omitted when the
storage location cannot be resolved.
video_blob:
type: string
description: >-
GCS blob path of the original video. Use with video_bucket
at GET /serve/api/v2/download to fetch the file directly.
keyframe_bucket:
type: string
description: GCS bucket of the matched keyframe image (BY_CLIP only).
keyframe_blob:
type: string
description: GCS blob path of the matched keyframe image.
- type: object
properties:
current_page:
type: integer
example: 0
page_size:
type: integer
example: 20
total_count:
type: integer
format: int64
example: 5
item:
type: array
items:
type: object
properties:
id:
type: integer
format: int64
example: 619915496901337100
name:
type: string
example: OIX_ZOOM
img_url:
type: string
example: https://storage.googleapis.com/.../OIX_ZOOM.jpg?...
datetime_taken:
type: integer
format: int64
example: 1757285520000
camera_model:
type: string
example: Canon EOS 5D
latitude:
type: number
format: double
example: 39.9042
longitude:
type: number
format: double
example: 116.4074
score:
type: number
format: double
example: 0.4711
bucket:
type: string
description: GCS bucket of the image.
blob:
type: string
description: >-
GCS blob path of the image. Use with bucket at GET
/serve/api/v2/download to fetch the file directly.
- type: array
description: BY_CAPTION response items.
items:
type: object
properties:
video_no:
type: string
example: VI576925607808602112
text:
type: string
description: Matched caption segment text.
vector:
type: array
items:
type: number
description: >-
Stored embedding vector of the matched caption row.
Dimensionality depends on the embedding model.
user_id:
type: string
description: Internal MD5-encoded user namespace identifier.
start_time:
type: number
format: double
description: Caption start time in seconds.
end_time:
type: number
format: double
description: Caption end time in seconds.
score:
type: number
format: double
description: Similarity score (1 - distance).
success:
type: boolean
example: true
failed:
type: boolean
example: false
example:
code: '0000'
msg: success
data:
- videoNo: VI576925607808602112
videoName: '1920447021987282945'
startTime: '13'
endTime: '18'
audio_ts: ...matched transcript text...
score: 0.5221236659362116
video_bucket: mavi-resource
video_blob: VI576925607808602112.mp4
keyframe_bucket: mavi-keyframe
keyframe_blob: /keyframe-000013.jpg
success: true
failed: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````