Skip to main content
POST
/
v1
/
understand
/
upload
Video Caption / Human Re-identification
curl --request POST \
  --url https://security.memories.ai/v1/understand/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "video_url": "https://example.com/test_video.mp4",
  "user_prompt": "Summarize the video content and identify key persons",
  "system_prompt": "You are a video understanding system.",
  "callback": "https://yourserver.com/callback",
  "thinking": false,
  "qa": false,
  "reasoning_effort": "2",
  "persons": [
    {
      "name": "Alice",
      "url": "https://example.com/alice.jpg"
    }
  ]
}
'
{
  "code": "0000",
  "msg": "success",
  "data": {},
  "success": true,
  "failed": false
}

​
Prerequisites

  • You’re familiar with the concepts described on the Platform overview.
  • You have acquired for special memories.ai API key.
  • Callback URL: Required for asynchronous endpoints (/upload, /uploadFile).
  • File size: Maximum 8 GB.
  • Duration: Between 0-2 hours.
  • Optional ReID: Up to 5 reference person images can be provided.

​
Host URL

​
Endpoints

  • POST /v1/understand/upload – Upload video by URL
  • POST /v1/understand/uploadFile – Upload video by local file (multipart form)
  • POST /v1/understand/uploadSync – Upload video by URL (synchronous)
  • POST /v1/understand/uploadFileSync – Upload video by local file (synchronous)

​
Request Example (Upload by URL)

import requests, json

url = "https://security.memories.ai/v1/understand/upload"
headers = {"Authorization": "<API_KEY>"}
json_body = { 
    "video_url": "https://example.com/test_video.mp4", 
    "user_prompt": "Summarize the video content and identify key persons", 
    "system_prompt": "You are a video understanding system that analyzes content and detects persons.", 
    "callback": "https://yourserver.com/callback", 
    "thinking": False, 
    "qa": False, 
    "reasoning_effort": "2" 
}
response = requests.post(url, headers=headers, json=json_body)
print(response.json())

​
Request Example (Upload by Local File)

import requests, json

url = "https://security.memories.ai/v1/understand/uploadFile"
headers = {"Authorization": "<API_KEY>"}
# JSON request body
data = { 
    "user_prompt": "Summarize the video content and identify key persons", 
    "system_prompt": "You are a video understanding system that summarizes video content.", 
    "callback": "https://yourserver.com/callback", 
    "thinking": False, 
    "qa": False, 
    "reasoning_effort": "2" 
}
files = [ 
    ("req", ("req.json", json.dumps(data), "application/json")), 
    ("files", ("video.mp4", open("video.mp4", "rb"), "video/mp4")),
]
response = requests.post(url, files=files, headers=headers)
print(response.json())

​
Request Parameters

​
video_url
string
Public video URL (for /upload, /uploadSync).
​
user_prompt
string
required
Instruction for the model (e.g., “Summarize this”).
​
system_prompt
string
required
System context instructions.
​
callback
string
Callback URL (required for async).
​
thinking
boolean
default:"false"
Enable reasoning model.
​
reasoning_effort
string
Level 1-10 for thinking effort.

​
Response Example (Async)

{ 
    "code": 0, 
    "msg": "success", 
    "data": { 
        "task_id": "xxx" 
    }
}

​
Response Example (Sync)

{ 
    "code": 0, 
    "msg": "success", 
    "data": { 
        "data": { 
            "text": "A man enters the room and greets two colleagues...", 
        }, 
        "token": { "input": 123, "output": 456, "total": 579 } 
    }
}

Authorizations

​
Authorization
string
header
required

Body

application/json
​
video_url
string<uri>
required
Example:

"https://example.com/test_video.mp4"

​
user_prompt
string
required
Example:

"Summarize the video content and identify key persons"

​
system_prompt
string
required
Example:

"You are a video understanding system."

​
callback
string<uri>
Example:

"https://yourserver.com/callback"

​
thinking
boolean
default:false
​
qa
boolean
default:false
​
reasoning_effort
string
Example:

"2"

​
persons
object[]

Response

200 - application/json

Successful response

​
code
Example:

"0000"

​
msg
string
Example:

"success"

​
data
​
success
boolean
Example:

true

​
failed
boolean
Example:

false