List Videos

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)

Browse and filter your Private Video Library. Returns a paginated list of uploaded videos with status, duration, file size, and any capture metadata.

Prerequisites

You have created a memories.ai API key.
You have uploaded at least one video using the Upload API (metadata-based filters require the video to have finished parsing so that its summary/metadata row is populated).

Endpoint

POST /serve/api/v1/list_videos

Authentication

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

Authorization: sk-mavi-...

Request Example

Uses application/json — send the request body as JSON, not form data.

Basic listing:

import requests

headers = {"Authorization": "sk-mavi-..."}
json_body = {
    "page": 1,
    "size": 200,
    "unique_id": "default"
}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/list_videos",
    headers=headers,
    json=json_body
)
print(response.json())

Listing filtered by capture metadata (GPS radius + camera + tag + minimum capture time):

json_body = {
    "page": 1,
    "size": 50,
    "unique_id": "default",
    # --- metadata filters ---
    "camera_model": "Canon EOS 5D",
    "tag": "holiday",
    "datetime_taken": 1729388400000,  # ms since epoch; only videos captured at/after this time
    "latitude": 39.9042,
    "longitude": 116.4074,             # latitude + longitude must be supplied together (≈20 km radius)
    # --- optional: restrict to a specific set of video_nos ---
    "video_nos": ["VI606404158946574336", "VI606402870447996928"]
}

Request Parameters

Basic filters

page

integer

default:"1"

One-based page number. Must be > 0.

size

integer

default:"200"

Number of items per page. Must be > 0.

unique_id

string

default:"default"

Scope identifier for the authenticated account (corresponds to the upload-time unique_id). Must be non-empty. If the folder for this unique_id does not exist yet, it is created automatically.

video_name

string

Exact-match filter on the stored video name.

video_no

string

Exact-match filter on a single video identifier.

video_nos

array

Restrict results to a specific set of video identifiers. Combined via AND with any other filter. When used alongside metadata filters, the final result is the intersection of the two sets.

status

string

Filter by processing status. One of PARSE, UNPARSE, FAIL. Note that the server rejects the legacy FAILED spelling with a JSON parse error referencing the live enum ([UNPARSE, PARSE, FAIL]).

Metadata filters

All metadata filters are resolved against the summary table that the upload pipeline populates after a video finishes parsing. A video whose summary is not yet available will not appear in the result when any metadata filter is applied.

camera_model

string

Exact-match filter on the camera_model supplied at upload time.

tag

string

Single tag filter — the video’s tag array must contain this value. To filter by multiple tags, issue separate requests and intersect client-side (server applies AND-with-other-filters semantics).

datetime_taken

integer

Minimum capture timestamp in milliseconds since epoch. Videos whose capture_timestamp >= datetime_taken are returned.

latitude

number

Decimal latitude. Must be supplied together with longitude; supplying only one returns “The latitude and longitude parameters must be provided together.”

longitude

number

Decimal longitude. Must be supplied together with latitude. The server applies a ~20 km radius geo-within filter around the point.

Notes & Limits

Rate limiting: The endpoint is protected by a per-account rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
Metadata-filter resolution: When any of camera_model, tag, datetime_taken, latitude+longitude is supplied, the server first queries the summary table, then restricts the listing to matching videos. If nothing matches, an empty page is returned (the request still succeeds).
Legacy compatibility: Requests that only use the basic filters (page / size / unique_id / video_name / video_no / status) behave exactly as before; response adds the new metadata fields only for videos that have them.

Response Example

Numeric fields (duration, size, create_time, total_count, datetime_taken) are returned as strings, even though they represent integers — convert with int(...) before doing arithmetic.

{
    "code": "0000",
    "msg": "success",
    "data": {
        "current_page": 1,
        "page_size": 20,
        "total_count": "2",
        "videos": [
            {
                "video_no": "VI702915390254350336",
                "video_name": "NkdWNOrQByo",
                "duration": "105",
                "size": "7798243",
                "status": "PARSE",
                "cause": "null",
                "create_time": "1777047288621",
                "video_url": "https://mavi-resource.openinterx.com/VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775.mp4",
                "cover_url": "https://mavi-resource.openinterx.com//VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775/frame_0032.jpg",
                "fps": null,
                "width": null,
                "height": null,
                "resolution_label": null,
                "tags": ["living_room", "couch", "cat", "kitchen", "pov_laundry", "api"],
                "bucket": "mavi-resource",
                "blob": "VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775.mp4"
            }
        ]
    },
    "success": true,
    "failed": false
}

Response Fields

code

string

Business status code. 0000 indicates success.

msg

string

Human-readable status message.

data.current_page

integer

Echo of the requested page number (one-based).

data.page_size

integer

Echo of the requested page size.

data.total_count

string

Total number of matching videos across all pages, returned as a string.

data.videos

array

Page of matching videos. Each item carries the basic video fields plus — when available — the capture-time metadata supplied at upload.

Video item fields

video_no

string

Unique video identifier.

video_name

string

Internal stored name of the video.

duration

string

Video duration in seconds, returned as a string (int(duration) to use it).

size

string

Video file size in bytes, returned as a string.

create_time

string

Upload time in milliseconds since epoch, returned as a string.

status

string

Processing status. One of:

PARSE — ready for chat/search.
UNPARSE — uploaded but not yet fully processed.
FAIL — processing failed (see cause).

cause

string

Failure reason. Always present; carries the literal string "null" when there is no failure.

video_url

string

Hosted CDN URL of the original video on mavi-resource.openinterx.com. Suitable as a file_uri for Gemini VLM without re-uploading.

cover_url

string

Hosted CDN URL of the auto-extracted cover frame (typically frame 32). Useful as a thumbnail in listing UIs.

fps

number

Frame rate of the source video. May be null for older uploads.

width

integer

Pixel width of the source video. May be null for older uploads.

height

integer

Pixel height of the source video. May be null for older uploads.

resolution_label

string

Human-readable resolution label (e.g. 720p). May be null for older uploads.

Metadata fields

These fields are only present when the corresponding value was supplied at upload time and the video’s summary row has been written.

datetime_taken

string

Capture timestamp in milliseconds since epoch, returned as a string.

camera_model

string

Camera/device model recorded at upload.

latitude

number

Decimal latitude.

longitude

number

Decimal longitude.

Storage fields

bucket

string

GCS bucket of the original video file. Omitted when the storage location cannot be resolved.

blob

string

GCS blob (object) path of the video file. Use it with bucket at GET /serve/api/v2/download?bucket=&blob= to fetch the file directly.

Authorizations

Authorization

string

header

required

Body

application/json

page

integer

default:1

One-based page number. Must be > 0.

Required range: x >= 1

size

integer

default:200

Items per page. Must be > 0.

Required range: x >= 1

unique_id

string

default:default

Scope identifier for the authenticated account. Folder is auto-created on first use.

video_name

string

Exact-match filter on the stored video name.

video_no

string

Exact-match filter on a single video identifier.

video_nos

string[]

Restrict results to a specific set of video identifiers. Combined via AND with other filters; intersected with the metadata-filter result when both are used.

Example:

[
  "VI606404158946574336",
  "VI606402870447996928"
]

status

enum<string>

Filter by processing status.

Available options:

PARSE,

UNPARSE,

FAILED

camera_model

string

Metadata filter: exact-match on the camera_model supplied at upload time.

Example:

"Canon EOS 5D"

tag

string

Metadata filter: single tag that must be present on the video.

Example:

"holiday"

datetime_taken

integer<int64>

Metadata filter: minimum capture timestamp in milliseconds since epoch. Matches videos whose capture_timestamp >= this value.

Example:

1729388400000

latitude

number<double>

Metadata filter: decimal latitude. Must be supplied together with longitude.

Example:

39.9042

longitude

number<double>

Metadata filter: decimal longitude. Must be supplied together with latitude. ~20 km geo-within radius.

Example:

116.4074

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

Reference

Prerequisites

Endpoint

Authentication

Request Example

Request Parameters

Basic filters

Metadata filters

Notes & Limits

Response Example

Response Fields

Video item fields

Metadata fields

Storage fields

Authorizations

Body

Response

Get Started

Index Upload

Search

Library Management

Reference

Documentation Index

​Prerequisites

​Endpoint

​Authentication

​Request Example

​Request Parameters

​Basic filters

​Metadata filters

​Notes & Limits

​Response Example

​Response Fields

​Video item fields

​Metadata fields

​Storage fields

Authorizations

Body

Response

Prerequisites

Endpoint

Authentication

Request Example

Request Parameters

Basic filters

Metadata filters

Notes & Limits

Response Example

Response Fields

Video item fields

Metadata fields

Storage fields