Skip to main content
POST
/
serve
/
api
/
v1
/
upload
Upload Video from File
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form callback=https://your.app/callback \
  --form unique_id=default \
  --form 'datetime_taken=2025-10-20 11:00:00' \
  --form 'camera_model=Canon EOS 5D' \
  --form latitude=66.66 \
  --form longitude=66.66 \
  --form 'tags[0]=test1' \
  --form 'tags[1]=test2' \
  --form retain_original_video=true \
  --form 'video_transcription_prompt=Focus on the speaker and major scene changes.'
{
  "code": "0000",
  "msg": "success",
  "data": {
    "videoNo": "VI568102998803353600",
    "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
    "videoStatus": "UNPARSE",
    "uploadTime": "1744905509814"
  },
  "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)
Upload a video file from disk into your Private Video Library for indexing and search. To pull a video from a remote URL instead, use Upload Video — from URL. For images, use Upload Image. The upload queues the video for asynchronous indexing. The response returns immediately with videoStatus: "UNPARSE"; register a callback URL or poll Get Metadata with the returned videoNo to know when indexing reaches PARSE.

​
Prerequisites

  • You have created a memories.ai API key.
  • Supported formats: .mp4, .avi, .mkv, .mov. Content-Type of the file part must start with video/.
  • Video codecs: h264, h265, vp9, hevc.
  • Max file size: 3 GB.

​
Request Example

Uses multipart/form-data. Send all non-file parameters as form fields, not JSON.
import requests, os

headers = {"Authorization": "sk-mavi-..."}
file_path = "my_video.mp4"

with open(file_path, "rb") as f:
    response = requests.post(
        "https://api.memories.ai/serve/api/v1/upload",
        headers=headers,
        files={"file": (os.path.basename(file_path), f, "video/mp4")},
        data={
            "unique_id": "my-project",
            "callback": "https://your.app/callback",
            "datetime_taken": "2025-10-20 11:00:00",
            "camera_model": "Canon EOS 5D",
            "latitude": "39.9042",
            "longitude": "116.4074",
            "tags": ["tag1", "tag2"],
            "retain_original_video": True,
            "video_transcription_prompt": "Focus on spoken dialogue"
        }
    )
print(response.json())

​
Parameters

​
file
file
required
The video file. Extension must be .mp4, .avi, .mkv, or .mov and Content-Type must start with video/. Maximum 3 GB.
​
unique_id
string
default:"default"
Namespace to group videos under a logical folder in your account. Created automatically on first use. Must be non-empty when provided.
​
callback
string
URL that receives a POST notification when the video finishes indexing. Maximum 299 characters.
​
datetime_taken
string
Capture time in yyyy-MM-dd HH:mm:ss format (e.g. 2025-10-20 11:00:00). Invalid formats are rejected.
​
camera_model
string
Camera or device model name. Maximum 200 characters.
​
latitude
number
GPS latitude where the video was captured (decimal).
​
longitude
number
GPS longitude where the video was captured (decimal).
​
tags
array
User-defined tags (e.g. ["outdoor", "2025"]). Maximum 20 tags. An api tag is appended automatically.
​
retain_original_video
boolean
default:"true"
Whether to retain the original video file after indexing. Defaults to true.
​
video_transcription_prompt
string
Custom prompt to steer the transcription and video understanding focus.

​
Response Example

{
    "code": "0000",
    "msg": "success",
    "data": {
        "videoNo": "VI568102998803353600",
        "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
        "videoStatus": "UNPARSE",
        "uploadTime": "1744905509814"
    }
}

​
Response Fields

​
code
string
Business status code. 0000 indicates success.
​
msg
string
Human-readable status message.
​
data.videoNo
string
Unique identifier for the uploaded video. Use this in all subsequent operations.
​
data.videoName
string
Internal name assigned to the stored video.
​
data.videoStatus
string
Initial processing status. Always UNPARSE immediately after upload; transitions to PARSE once indexing completes.
​
data.uploadTime
string
Upload timestamp in milliseconds since epoch.

​
Knowing When Indexing Is Done

A successful upload returns videoStatus: "UNPARSE" — the video is queued for indexing but is not yet searchable. Two ways to wait for PARSE:
ApproachHow
Push (recommended for production)Provide a callback URL on upload; memories.ai POSTs to it when indexing completes.
PollCall Get Metadata with video_no=<the videoNo above> and check data.status until it becomes PARSE.
Do not use Get Task Status here. That endpoint is for batch Upload from Social Media tasks, which return a taskId. Single-file uploads return videoNo, not taskId.
Callback payload, if you registered one: 
{
    "videoNo": "VI554046065381212160",
    "status": "PARSE"
}

​
Notes & Limits

  • Rate limiting: Exceeding the per-account upload rate limit returns an error. See Rate limits.
  • Concurrent indexing: There is a cap on how many videos can be in the indexing queue within a rolling 2-hour window. New uploads are rejected once the cap is reached until prior videos finish parsing.
  • Billing: Each upload deducts credits from your account. Insufficient balance causes the request to fail.

Authorizations

​
Authorization
string
header
required

Body

multipart/form-data
​
file
file
required

Video file to upload. Allowed extensions: .mp4, .avi, .mkv, .mov. Content-Type must start with video/. Max size 3 GB.

​
callback
string<uri>

Callback URL invoked when the video moves to the parsing stage. Max 299 characters.

Maximum string length: 299
Example:

"https://your.app/callback"

​
unique_id
string
default:default

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

​
datetime_taken
string

Capture time in format yyyy-MM-dd HH:mm:ss.

Example:

"2025-10-20 11:00:00"

​
camera_model
string

Camera/device model. Max 200 characters.

Maximum string length: 200
Example:

"Canon EOS 5D"

​
latitude
number<double>
Example:

66.66

​
longitude
number<double>
Example:

66.66

​
tags
string[]

User-defined tags. Max 20. The server automatically appends an 'api' tag.

Maximum array length: 20
Example:
["test1", "test2"]
​
retain_original_video
boolean
default:true
​
video_transcription_prompt
string
Example:

"Focus on the speaker and major scene changes."

Response

200 - application/json

Successful response

​
code
string

Business status code. 0000 indicates success.

Example:

"0000"

​
msg
string
Example:

"success"

​
data
object
Example:
{
  "videoNo": "VI568102998803353600",
  "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
  "videoStatus": "UNPARSE",
  "uploadTime": "1744905509814"
}
​
success
boolean
Example:

true

​
failed
boolean
Example:

false