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

# Image Caption

> Analyze one or more images and generate captions or descriptions — from a URL, local file, or base64.

<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 images and generate natural-language captions or descriptions. Supports single and batch inputs via URL, local file upload, or base64 encoding.

**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                             | Input method                            |
| ------ | ------------------------------------ | --------------------------------------- |
| `POST` | `/v1/understand/uploadImg`           | URL (single or batch)                   |
| `POST` | `/v1/understand/uploadImgFile`       | Local file (single or batch, multipart) |
| `POST` | `/v1/understand/uploadImgFileBase64` | Base64-encoded (single or batch)        |

**Supported formats:** `image/png`, `image/jpeg`

## Request Examples

<CodeGroup>
  ```python By URL — single image theme={null}
  import requests

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

  payload = {
      "url": "https://example.com/photo.jpg",
      "user_prompt": "What is happening in this image?",
      "system_prompt": "You are an image understanding system.",
      "thinking": False
  }

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

  ```python By URL — multiple images theme={null}
  import requests

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

  payload = {
      "urls": [
          "https://example.com/photo1.jpg",
          "https://example.com/photo2.png"
      ],
      "user_prompt": "Describe what is happening in each image.",
      "system_prompt": "You are an image understanding system.",
      "thinking": False
  }

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

  ```python By local file theme={null}
  import requests, json

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

  data = {
      "user_prompt": "Describe this image in detail.",
      "system_prompt": "You are an image understanding system.",
      "thinking": False
  }

  files = [
      ("req",  ("req.json", json.dumps(data), "application/json")),
      ("file", ("photo.jpg", open("photo.jpg", "rb"), "image/jpeg")),
  ]

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

  ```python By base64 theme={null}
  import requests, base64

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

  with open("photo.png", "rb") as f:
      img_b64 = base64.b64encode(f.read()).decode("utf-8")

  payload = {
      "user_prompt": "Describe this image in ten words.",
      "image_base64": img_b64,
      "img_type": "image/png",
      "thinking": False
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

## Parameters

<ParamField body="url" type="string | array">
  Single image URL (string) or list of image URLs (array). Used for `/uploadImg` only.
</ParamField>

<ParamField body="user_prompt" type="string" required>
  Instruction for the analysis — e.g. `"What is happening in this image?"`.
</ParamField>

<ParamField body="system_prompt" type="string">
  Role or context for the AI — e.g. `"You are an image understanding system."`.
</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).
</ParamField>

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

<ParamField body="image_base64" type="string">
  Base64-encoded single image. Used with `/uploadImgFileBase64`. Requires `img_type`.
</ParamField>

<ParamField body="images" type="array">
  Batch base64 input. Each item: `{ "image_base64": "...", "img_type": "image/png" }`.
</ParamField>

<ParamField body="img_type" type="string">
  MIME type of the base64 image — `"image/png"` or `"image/jpeg"`. Required when using `image_base64`.
</ParamField>

## Response

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "text": "A person is sitting at a desk reviewing documents in a well-lit office.",
    "token": {
      "input": 273,
      "output": 79,
      "total": 352
    }
  }
}
```

## Response Fields

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

<ResponseField name="data.text" type="string">
  Generated caption or descriptive text.
</ResponseField>

<ResponseField name="data.token.input" type="integer">
  Number of input tokens consumed.
</ResponseField>

<ResponseField name="data.token.output" type="integer">
  Number of output tokens generated.
</ResponseField>

<ResponseField name="data.token.total" type="integer">
  Total token count.
</ResponseField>

<ResponseField name="model_time" type="integer">
  Model processing time in milliseconds.
</ResponseField>

<ResponseField name="upload_time" type="integer">
  Upload time in milliseconds.
</ResponseField>