> ## 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.

# Video Caption

> Generate captions, summaries, and analysis for videos — with optional Human Re-ID to identify specific people.

<Info>
  **Product**: Visual Intelligence — Human ReID & Caption
  **Use case**: Identity-aware vision analysis — generate captions for videos and images, with optional reference photos to name specific people in the output (Human Re-identification)
  **Host**: `https://security.memories.ai`
  **Auth**: Dedicated API key required — contact [support@memories.ai](mailto:support@memories.ai)
</Info>

Analyze a video and generate a natural-language caption, summary, or Q\&A response. Optionally provide reference images to enable **Human Re-identification (ReID)** — the model will detect and name those individuals in its output.

**Base URL:** `https://security.memories.ai`

<Note>
  Access to this API requires a dedicated API key separate from the standard Memories.ai key. Contact [support@memories.ai](mailto:support@memories.ai) to request access.
</Note>

## Endpoints

| Method | Endpoint                        | Mode                                               |
| ------ | ------------------------------- | -------------------------------------------------- |
| `POST` | `/v1/understand/upload`         | Async — by URL                                     |
| `POST` | `/v1/understand/uploadFile`     | Async — by local file                              |
| `POST` | `/v1/understand/uploadSync`     | Sync — by URL (result returned immediately)        |
| `POST` | `/v1/understand/uploadFileSync` | Sync — by local file (result returned immediately) |

Async endpoints require a `callback` URL. Sync endpoints return the result directly in the response — suitable for shorter videos.

## Request Examples

<CodeGroup>
  ```python Async — by URL theme={null}
  import requests

  url = "https://security.memories.ai/v1/understand/upload"
  headers = {"Authorization": "sk-mavi-..."}

  payload = {
      "video_url": "https://example.com/video.mp4",
      "user_prompt": "Summarize the video and identify any known persons.",
      "system_prompt": "You are a video understanding system.",
      "callback": "https://your.app/callback",
      "persons": [
          {"name": "Alice", "url": "https://example.com/alice.jpg"},
          {"name": "Bob",   "url": "https://example.com/bob.jpg"}
      ],
      "thinking": False
  }

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

  ```python Sync — by URL theme={null}
  import requests

  url = "https://security.memories.ai/v1/understand/uploadSync"
  headers = {"Authorization": "sk-mavi-..."}

  payload = {
      "video_url": "https://example.com/video.mp4",
      "user_prompt": "What is the main activity in this video?",
      "system_prompt": "You are a video understanding system.",
      "thinking": False
  }

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

  ```python Async — by local file theme={null}
  import requests, json

  url = "https://security.memories.ai/v1/understand/uploadFile"
  headers = {"Authorization": "sk-mavi-..."}

  data = {
      "user_prompt": "Summarize the video content.",
      "system_prompt": "You are a video understanding system.",
      "callback": "https://your.app/callback",
      "thinking": False
  }

  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())
  ```
</CodeGroup>

## Parameters

<ParamField body="video_url" type="string">
  Publicly accessible video URL. Required for URL-based endpoints (`/upload`, `/uploadSync`). Omit when uploading a local file.
</ParamField>

<ParamField body="user_prompt" type="string" required>
  Instruction for the analysis — e.g. `"Summarize the video and identify key persons"`.
</ParamField>

<ParamField body="system_prompt" type="string" required>
  Role or context for the AI — e.g. `"You are a video understanding system."`.
</ParamField>

<ParamField body="callback" type="string">
  Public URL to receive the async result. Required for `/upload` and `/uploadFile`. Not used for sync endpoints.
</ParamField>

<ParamField body="persons" type="array">
  Reference people for Human Re-identification. Up to **5 entries**. Each entry:

  * `name` (string, required) — identifier for the person
  * `url` (string) — publicly accessible reference image URL
</ParamField>

<ParamField body="thinking" type="boolean" default="false">
  Enable reasoning mode for more detailed analysis.
</ParamField>

<ParamField body="reasoning_effort" type="string">
  Only applies when `thinking` is `true`. Level `1`–`10`; higher values use more tokens. Default `-1` (model decides automatically).
</ParamField>

<ParamField body="qa" type="boolean" default="false">
  `true` for conversational Q\&A style; `false` for information retrieval / caption style.
</ParamField>

## Video Requirements

* **Max file size:** 8 GB
* **Max duration:** 2 hours
* **Reference images (ReID):** up to 5 per request

## Response

### Async (`/upload`, `/uploadFile`)

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "8e03075a-2230-4e67-98d4-ba53f37c807a"
  }
}
```

The result is delivered to your `callback` URL when processing completes:

```json theme={null}
{
  "status": 0,
  "task_id": "8e03075a-2230-4e67-98d4-ba53f37c807a",
  "data": {
    "text": "Alice enters the room and greets two colleagues. Bob arrives shortly after.",
    "token": { "input": 123, "output": 456, "total": 579 }
  }
}
```

### Sync (`/uploadSync`, `/uploadFileSync`)

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "data": {
      "text": "The video shows a product demo in a conference room.",
      "token": { "input": 200, "output": 80, "total": 280 }
    }
  }
}
```

## Response Fields

<ResponseField name="code" type="integer">
  `0` = success, `-1` = failure.
</ResponseField>

<ResponseField name="data.task_id" type="string">
  Async only. Use this to correlate callback notifications.
</ResponseField>

<ResponseField name="data.data.text" type="string">
  Sync only. Generated caption, summary, or analysis text.
</ResponseField>

<ResponseField name="data.data.token" type="object">
  Sync only. Token usage: `input`, `output`, `total`.
</ResponseField>

## Human Re-identification (ReID)

Pass a `persons` array to identify specific individuals in the video. The model compares reference images against people detected in the video and names them in the output text.

```python theme={null}
"persons": [
    {"name": "Alice", "url": "https://example.com/alice.jpg"},
    {"name": "Bob",   "url": "https://example.com/bob.jpg"}
]
```

ReID is a feature of this endpoint — not a separate API call. Results appear naturally in the generated text (e.g., `"Alice enters first, followed by Bob."`).

## Notes

* Callback delivery is retried up to **5 times** until your endpoint returns `2xx`.
* Sync endpoints are best suited for videos under a few minutes. For long videos, use async endpoints.