Skip to main content
GET
/
serve
/
api
/
v1
/
get_metadata
Get Video Metadata
curl --request GET \
  --url https://api.memories.ai/serve/api/v1/get_metadata \
  --header 'Authorization: <api-key>'
{
  "code": "0000",
  "msg": "success",
  "data": {
    "video_no": "VI606404158946574336",
    "video_name": "182082-867762198_tiny",
    "duration": 12,
    "size": 3284512,
    "status": "PARSE",
    "create_time": 1754037217992,
    "resolution_label": "720P",
    "fps": 30,
    "width": 1280,
    "height": 720,
    "datetime_taken": 1729388400000,
    "camera_model": "Canon EOS 5D",
    "latitude": 39.9042,
    "longitude": 116.4074,
    "tags": [
      "holiday",
      "beijing",
      "api"
    ],
    "bucket": "mavi-resource",
    "blob": "VI606404158946574336.mp4"
  },
  "success": true,
  "failed": false
}

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.

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)
Fetch the full metadata record for a single video in your Private Video Library — status, duration, resolution, GPS, camera model, and tags. This is also the canonical way to poll indexing status after Upload Video or Upload Image — read data.status and wait for it to become PARSE.

​
Prerequisites

  • You have created a memories.ai API key.
  • You have uploaded the target video using the Upload API (metadata fields only become available after the video finishes parsing and its summary row is populated).

​
Endpoint

GET /serve/api/v1/get_metadata

​
Authentication

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

​
Request Example

import requests

url = "https://api.memories.ai/serve/api/v1/get_metadata"
params = {
    "video_no": "VI606404158946574336",
    "unique_id": "default"
}
headers = {"Authorization": "sk-mavi-..."}

response = requests.get(url, headers=headers, params=params)
print(response.json())

​
Query Parameters

​
video_no
string
required
The video identifier returned by the upload API (e.g. VI606404158946574336). Must be non-empty.
​
unique_id
string
default:"default"
Scope identifier for the authenticated account (corresponds to the upload-time unique_id). Must be non-empty when explicitly provided.

​
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 availability: The capture-time metadata fields (datetime_taken / camera_model / latitude / longitude) are only present when the corresponding value was supplied at upload and the video’s summary row has been written (i.e. after parsing completes). Videos not yet parsed return the basic fields only.
  • Not found is not an error: If the video does not exist (or does not belong to this account), the response is code: "0000", success: true, data: null — check data for None explicitly rather than relying on the status code.
  • Numeric field types are inconsistent: duration, size, and create_time are returned as strings; fps, width, height are returned as actual integers. Cast duration/size/create_time with int(...) before arithmetic.

​
Response Example

{
    "code": "0000",
    "msg": "success",
    "data": {
        "video_no": "VI702915390254350336",
        "video_name": "NkdWNOrQByo",
        "duration": "105",
        "size": "7798243",
        "status": "PARSE",
        "create_time": "1777047288621",
        "resolution_label": "720p",
        "fps": 30,
        "width": 640,
        "height": 360,
        "tags": ["living_room", "couch", "cat", "kitchen", "pov_laundry", "api"],
        "bucket": "mavi-resource",
        "blob": "VI702915390254350336.mp4"
    },
    "success": true,
    "failed": false
}

​
Response Fields

​
code
string
Business status code. 0000 indicates success.
​
msg
string
Human-readable status message.
​
data
object
The video item. null when the video is not found.

​
Basic fields

​
data.video_no
string
Unique video identifier.
​
data.video_name
string
Internal stored name of the video.
​
data.duration
string
Video duration in seconds, returned as a string (int(duration) to use it).
​
data.size
string
File size in bytes, returned as a string.
​
data.create_time
string
Upload time in milliseconds since epoch, returned as a string.
​
data.status
string
Processing status. One of PARSE, UNPARSE, FAIL.
​
data.cause
string
Failure reason — only present when status=FAIL.
​
data.resolution_label
string
Human-readable resolution label (e.g. 720p, 1080p). Lower-case p.
​
data.fps
integer
Frames per second.
​
data.width
integer
Frame width in pixels.
​
data.height
integer
Frame height in pixels.

​
Metadata fields

These are only present when the corresponding value was supplied at upload time and the video’s summary row has been written.
​
data.datetime_taken
string
Capture timestamp in milliseconds since epoch, returned as a string.
​
data.camera_model
string
Camera/device model recorded at upload.
​
data.latitude
number
Decimal latitude.
​
data.longitude
number
Decimal longitude.
​
data.tags
array
Combined tag set: user-supplied tags from upload plus scene/object tags auto-generated by the indexing pipeline (e.g. living_room, couch, cat), plus the auto-appended api tag. Unlike list_videos, this endpoint always returns tags once the video has finished parsing, even if no user tags were supplied at upload — the auto tags alone are enough to populate it.

​
Storage fields

​
data.bucket
string
GCS bucket of the video file. Omitted when the storage location cannot be resolved.
​
data.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. Note: video_url and cover_url are deliberately not returned by this endpoint — use bucket/blob instead.

Authorizations

​
Authorization
string
header
required

Query Parameters

​
video_no
string
required

Video identifier. Must be non-empty.

​
unique_id
string
default:default

Scope identifier for the authenticated account.

Response

200 - application/json

Successful response

​
code
string
Example:

"0000"

​
msg
string
Example:

"success"

​
data
object
​
success
boolean
Example:

true

​
failed
boolean
Example:

false