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.

​
Prerequisites

  • You’re familiar with the concepts described on the Platform overview.
  • You have created a memories.ai API key.
  • Supported file extensions: .mp4, .avi, .mkv, .mov. The request’s Content-Type on the file part must start with video/.
  • Video and audio codecs: h264, h265, vp9, or hevc.
  • Audio track: Required if you intend to use the audio transcription feature.
  • Max file size: 3 GB per upload.

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/upload 
/serve/api/v1/upload

​
Authentication

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

​
Content Type

The endpoint expects multipart/form-data. All non-file parameters must be sent as form fields (not JSON).

​
Request Example

import os
import requests

headers = {"Authorization": "<API_KEY>"}
file_path = "<VIDEO_FILE_PATH>"

files = {
    "file": (os.path.basename(file_path), open(file_path, 'rb'), "video/mp4")
}
data = {
    "callback": "<CallBack URL>",
    "unique_id": "test1020",
    "datetime_taken": "2025-10-20 11:00:00",
    "camera_model": "Canon EOS 5D",
    "latitude": "66.66",
    "longitude": "66.66",
    "tags": ["test1", "test2", "test3", "test4", "test5"],
    "retain_original_video": True,
    "video_transcription_prompt": "<YOUR_CUSTOMIZED_PROMPT_FOR_VIDEO_FOCUS>"
}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/upload",
    files=files,
    data=data,
    headers=headers
)
print(response.json())

​
Callback Notification Payload

If you provide a callback, memories.ai will send a POST request to it once the video has been uploaded or parsed. 
{
    "videoNo": "VI554046065381212160",
    "status": "PARSE"
}

​
Request Parameters

​
file
file
required
The video file to upload. Must not be empty. The file extension must be one of .mp4, .avi, .mkv, .mov (case-insensitive) and the Content-Type of the file part must start with video/. Maximum size 3 GB.
​
unique_id
string
default:"default"
Scope identifier used to group videos under a logical folder for the authenticated account. If the folder for this unique_id does not exist yet, it is created automatically on the first upload. Must be non-empty when explicitly provided.
​
callback
string
Callback URL that will receive a POST notification when the video moves to the parsing stage. Maximum length 299 characters.
​
datetime_taken
string
Capture time of the video in the exact format yyyy-MM-dd HH:mm:ss (e.g. 2025-10-20 11:00:00). Invalid formats are rejected.
​
camera_model
string
Camera/device model name. Maximum length 200 characters.
​
latitude
number
Latitude where the video was captured. Must be a valid decimal number (e.g. 66.66).
​
longitude
number
Longitude where the video was captured. Must be a valid decimal number (e.g. 66.66).
​
tags
array
List of user-defined tags (e.g. ["test1", "test2"]). Maximum 20 tags per request. The server automatically appends an api tag to every upload.
​
retain_original_video
boolean
default:"true"
Whether to retain the original uploaded video file. Defaults to true.
​
video_transcription_prompt
string
Custom prompt that steers the video transcription/understanding focus.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account upload rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
  • Concurrent indexing limit: There is a per-user cap on the number of videos that can be in the “indexing/unparsed” state within a rolling 2-hour window. New uploads are rejected once this cap is reached until previous videos finish parsing.
  • Billing: This endpoint is metered — the cost of the upload is checked and deducted from your account balance at request time. Insufficient balance will cause the request to fail.
  • m3u8: Only accounts on a dedicated allow-list may upload m3u8 sources via this endpoint; the standard file-upload flow is for regular video files.

​
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; any other value indicates an error and msg will describe it.
​
msg
string
Human-readable status message.
​
data.videoNo
string
Unique identifier assigned to the uploaded video. Use this value for all subsequent operations (status queries, transcription, summary, chat, delete, etc.).
​
data.videoName
string
Internal name assigned to the stored video.
​
data.videoStatus
string
Initial processing status. Typically UNPARSE immediately after upload; the video will transition to parsing asynchronously.
​
data.uploadTime
string
Upload timestamp in milliseconds since epoch (as a string).

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