> ## 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
> Search images you have uploaded to the Private Image Library using a natural-language text 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)
Search across images you have uploaded to your **Private Image Library**. This is a separate library from your Private Video Library — it uses a different endpoint (`BY_IMAGE`) and returns image results, not video clips.
To search videos instead, see [Search by Text](/visual-search/search-by-text), [Search by Image](/visual-search/search-by-image), or [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 image has been uploaded via [Upload Image](/visual-search/upload-image-from-file) and is in `PARSE` status.
## Endpoint
```
POST https://api.memories.ai/serve/api/v1/search
```
Use `search_type=BY_IMAGE` to search the Private Image Library. Using any other `search_type` on this endpoint searches the video library instead.
## Authentication
```
Authorization: sk-mavi-...
```
## 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": "sunset over the ocean",
"search_type": "BY_IMAGE",
"top_k": 20
}
)
print(response.json())
```
## Parameters
Natural-language search query. Must be non-empty.
Must be `BY_IMAGE` to search the Private Image Library.
`folder_id` is **not supported** for `BY_IMAGE` search and will be rejected. Folder filtering applies to video search only.
Maximum results to return. Range: **1 – 1000**.
Minimum similarity score:
* `low` — score ≥ 0.15
* `medium` — score ≥ 0.225
* `high` — score ≥ 0.4
Omit to return all results regardless of score.
Filter to images carrying this tag.
Filter to images 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
`BY_IMAGE` returns image items — a different response shape from video search.
```json theme={null}
{
"code": "0000",
"msg": "success",
"data": {
"current_page": 0,
"page_size": 20,
"total_count": 5,
"item": [
{
"id": 619915496901337088,
"name": "beach_sunset.jpg",
"img_url": "https://storage.googleapis.com/.../beach_sunset.jpg?...",
"datetime_taken": 1757285520000,
"camera_model": "Canon EOS 5D",
"latitude": 39.9042,
"longitude": 116.4074,
"score": 0.4711,
"bucket": "mavi-image",
"blob": "/beach_sunset.jpg"
}
]
},
"success": true,
"failed": false
}
```
Zero-based page index.
Items per page.
Total matching images.
Unique image identifier.
Image filename or display name.
Signed URL to access the image. Expires — do not cache long-term.
Capture timestamp in milliseconds since epoch.
Camera model recorded at upload time.
GPS latitude where the image was captured.
GPS longitude where the image was captured.
GCS bucket of the image. Omitted when the storage location cannot be resolved.
GCS blob (object) path of the image. Use it with `bucket` at `GET /serve/api/v2/download?bucket=&blob=` to fetch the file directly.
Relevance score. Higher is more relevant.
## 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
````