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 have acquired a special memories.ai API key (ReID is not provided for general API keys).
  • Reference images should be clear and high-quality.
  • Max 5 reference images per request.

​
Host URL

https://security.memories.ai

​
Endpoints

  • POST /v1/understand/upload – Upload video by URL
  • POST /v1/understand/uploadFile – Upload video by local file
Human Re-identification is integrated as part of the Video Caption and Image Caption APIs. You add a persons parameter to the request body.

​
Request Example (Video ReID with URL Upload)

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 and identify known persons.", 
    "system_prompt": "You are a video understanding system that can detect and identify people.", 
    "callback": "https://yourserver.com/callback", 
    "persons": [ 
        {"name": "Alice", "url": "https://example.com/alice.jpg"}, 
        {"name": "Bob", "url": "https://example.com/bob.jpg"} 
    ],
    "thinking": True, 
    "reasoning_effort": "2" 
}
response = requests.post(url, headers=headers, json=json_body)
print(response.json())

​
Request Example (Image ReID with File Upload)

# Upload with local file
url = "https://security.memories.ai/v1/understand/uploadFile"
data = { 
    "user_prompt": "Summarize the video and identify known persons", 
    "system_prompt": "You are an image analysis system with human re-identification capabilities", 
    "callback": "https://yourserver.com/callback", 
    "persons": [ 
        { "name": "Alice" }, 
        { "name": "Bob" } 
    ],
    "thinking": True
}
files = [ 
    ("req", ("req.json", json.dumps(data), "application/json")), 
    ('files', ('test_video.mp4', open("test.mp4", 'rb'), 'video/mp4')), 
    ('files', ('alice.jpg', open("alice.jpg", 'rb'), 'image/jpeg')), 
    ('files', ('bob.jpg', open("bob.jpg", 'rb'), 'image/jpeg'))
]
response = requests.post(url, files=files, headers=headers)
print("Status Code:", response.status_code)
print("Response Body:", response.text)

​
Request Body (ReID Parameter)

persons: 
  - name: "Alice" 
    url: "https://example.com/alice.jpg" 
  - name: "Bob" 
    url: "https://example.com/bob.jpg"

​
Callback Notification Payload

If persons are provided, the result will indicate whether those individuals were detected. 
{ 
    "status": 0, 
    "task_id": "a1b2c3d4e5", 
    "data": { 
        "text": "Bob and Alice are both present in the video. Alice enters first, followed by Bob.", 
        "token": { "input": 210, "output": 92, "total": 302 } 
    }
}

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