Human Re-identification (ReID)

Use this feature to identify and track specific people in videos or images. The API compares provided reference images against the media being analyzed and tags any detected matches.

Prerequisites

• You’re familiar with the concepts described on the Platform overview page.
• You have created a memories.ai API key.
• Reference images should be clear and high-quality to maximize accuracy.
• A maximum of 5 reference images can be provided per request.

Host URL

• https://security.memories.ai

Usage

Human re-identification is not a standalone endpoint. Instead, it is integrated as part of the Video Caption and Image Caption APIs.
You add a persons parameter to the request body with details of each individual you want to track.

---

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"}
    ]
}

response = requests.post(url, headers=headers, json=json_body)
print(response.json())

---

Request Example (Image ReID with File Upload)

import requests, json

url = "https://security.memories.ai/v1/understand/uploadImg"
headers = {"Authorization": "<API_KEY>"}

data = {
    "user_prompt": "Identify if Alice appears in this image.",
    "system_prompt": "You are an image analysis system with human re-identification capabilities.",
    "thinking": False
}

files = [
    ("req", ("req.json", json.dumps(data), "application/json")),
    ("file", ("test_image.png", open("test_image.png", "rb"), "image/png")),
    ("file", ("alice.png", open("alice.png", "rb"), "image/png"))
]

response = requests.post(url, files=files, headers=headers)
print(response.json())

---

Request Body (ReID Parameter)

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

Request Parameters

Name	Location	Type	Required	Description
persons	body	array	No	List of person descriptors (name + reference image URL or file)
» name	body	string	Yes	Person’s name or identifier
» url	body	string	No	Reference image URL (if file not uploaded)
file	body	binary	No	Reference image file (if URL not provided)

---

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
    }
  }
}

---

Response Structure

Name	Type	Required	Description
status	int	Yes	0 = success, -1 = failure
task_id	string	Yes	Unique task identifier
data	object	Yes	Response data
» text	string	Yes	Generated caption including detected person matches
» token	object	Yes	Token usage details

Note: Human ReID is always used in conjunction with Video or Image Caption APIs. It cannot be called independently.