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

# Scene Detection

> Detect scene boundaries in a video asset

<Info>
  **Product**: Visual Agents
  **Use case**: Managed endpoints powering Memories.ai's open-source video search and editing agents (queries, video clipping/editing, screenplay extraction)
  **Host**: `https://mavi-backend.memories.ai/serve/api/v2`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

This endpoint analyzes a video and automatically detects scene boundaries based on visual content changes. It returns an array of scene segments, each with start and end frame numbers.

<Warning>
  This endpoint performs **scene detection** (automatic segmentation), not manual video clipping. It identifies natural scene transitions in the video and returns the frame ranges for each detected scene.
</Warning>

<Warning>
  This is an **async endpoint**. You must configure a webhook URL in [Webhooks Settings](https://api-platform.memories.ai/webhooks) before calling this endpoint, otherwise you will not receive the processing results. See [Webhooks Configuration Guide](/visual-intelligence/getting-started/webhooks) for details.
</Warning>

<Note>
  **Pricing:**

  * \$0.02/second of video
</Note>

### Code Examples

<CodeGroup>
  ```javascript fetch theme={null}
  const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
  const API_KEY = "sk-mavi-...";

  const response = await fetch(`${BASE_URL}/video/clip`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': API_KEY
    },
    body: JSON.stringify({
      asset_id: 're_657739295220518912'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```javascript axios theme={null}
  import axios from 'axios';

  const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
  const API_KEY = "sk-mavi-...";

  const response = await axios.post(`${BASE_URL}/video/clip`, {
    asset_id: 're_657739295220518912'
  }, {
    headers: {
      'Authorization': API_KEY
    }
  });

  console.log(response.data);
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2"
  API_KEY = "sk-mavi-..."
  HEADERS = {
      "Authorization": f"{API_KEY}"
  }

  def video_clip(asset_id):
      url = f"{BASE_URL}/video/clip"
      data = {"asset_id": asset_id}
      response = requests.post(url, json=data, headers=HEADERS)
      return response.json()

  # Usage example
  result = video_clip("re_657739295220518912")
  print(result)
  ```
</CodeGroup>

### Request Body

| Field     | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| asset\_id | string | Yes      | The video asset ID to detect scenes in |

### Response

Returns task information for the video clip creation operation.

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "task_id": "f432bc84bfd141d1b05c1d24af0abe6a"
    },
    "failed": false,
    "success": true
  }
  ```

  ```json Callback Response theme={null}
  {
    "code": 200,
    "message": "SUCCESS",
    "data": {
      "data": {
        "data": [
          {
            "end": 46,
            "start": 0
          },
          {
            "end": 143,
            "start": 47
          },
          {
            "end": 214,
            "start": 144
          },
          {
            "end": 290,
            "start": 215
          },
          {
            "end": 466,
            "start": 291
          },
          {
            "end": 518,
            "start": 467
          },
          {
            "end": 605,
            "start": 519
          }
        ],
        "exec_time": 7.277834177017212
      },
      "msg": "Scene detection completed successfully",
      "success": true
    },
    "task_id": "a33f84793d0849f78825dc83c3b42671"
  }
  ```
</ResponseExample>

### Response Parameters

| Parameter     | Type    | Description                                       |
| ------------- | ------- | ------------------------------------------------- |
| code          | string  | Response code indicating the result status        |
| msg           | string  | Response message describing the operation result  |
| data          | object  | Response data object containing task information  |
| data.task\_id | string  | Unique identifier of the video clip creation task |
| success       | boolean | Indicates whether the operation was successful    |
| failed        | boolean | Indicates whether the operation failed            |

### Callback Response Parameters

When the video clipping is complete, a callback will be sent to your configured webhook URL.

| Parameter               | Type    | Description                                                                                                 |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| code                    | string  | Response code (200 indicates success)                                                                       |
| message                 | string  | Status message (e.g., "SUCCESS")                                                                            |
| data                    | object  | Response data object containing scene segmentation results                                                  |
| data.data               | object  | Inner data object containing the clipping information                                                       |
| data.data.data          | array   | Array of scene segments with frame ranges                                                                   |
| data.data.data\[].start | integer | Starting frame number of the scene segment (based on original video FPS, convert to seconds: `start / fps`) |
| data.data.data\[].end   | integer | Ending frame number of the scene segment (based on original video FPS, convert to seconds: `end / fps`)     |
| data.data.exec\_time    | number  | Execution time for the clipping operation in seconds                                                        |
| data.msg                | string  | Detailed message about the clipping result                                                                  |
| data.success            | boolean | Indicates whether the clipping was successful                                                               |
| task\_id                | string  | The task ID associated with this clipping request                                                           |

### Understanding the Callback Response

The callback response contains an array of scene segments identified in the video, each with start and end frame numbers.

**Response Structure:**

```
callback_response
├── code: 200
├── message: "SUCCESS"
├── data
│   ├── data
│   │   ├── data: [array of scene segments]
│   │   │   └── [
│   │   │       {
│   │   │         start: 0,
│   │   │         end: 46
│   │   │       },
│   │   │       {
│   │   │         start: 47,
│   │   │         end: 143
│   │   │       },
│   │   │       ...
│   │   │     ]
│   │   └── exec_time: 7.277834177017212
│   ├── msg: "Scene detection completed successfully"
│   └── success: true
└── task_id: "a33f84793d0849f78825dc83c3b42671"
```

**How to access the data:**

* Scene segments: `callback_response.data.data.data`
* Number of scenes detected: `callback_response.data.data.data.length`
* First scene start frame: `callback_response.data.data.data[0].start`
* First scene end frame: `callback_response.data.data.data[0].end`
* Execution time: `callback_response.data.data.exec_time`
* Success status: `callback_response.data.success`
* Task ID: `callback_response.task_id`

**Frame Range Format:**
Each segment represents a continuous scene in the video:

* `start`: The frame number where the scene begins (inclusive)
* `end`: The frame number where the scene ends (inclusive)
* Frame numbers are 0-indexed and based on the **original video's FPS**
* Scenes are automatically detected based on visual content changes

**Converting frame numbers to seconds:**

To convert frame numbers to time, you need the video's FPS (frames per second), which can be obtained via the [Get Metadata](/visual-intelligence/base/get-metadata) endpoint.

```
time_in_seconds = frame_number / fps
```

For example, if the video is 24 FPS:

* `{start: 0, end: 46}` → 0s to 1.92s
* `{start: 47, end: 143}` → 1.96s to 5.96s

### Notes

* Video clipping is processed asynchronously
* Returns a task\_id that can be used to track the clip creation progress
* Use the task\_id to query the status and results of clip creation
* Original video remains unchanged


## OpenAPI

````yaml POST /video/clip
openapi: 3.1.0
info:
  title: MAVI API Reference
  description: REST APIs for memory management, search, and entity operations
  version: v1.0.1
servers:
  - url: https://mavi-backend.memories.ai/serve/api/v2
security:
  - ApiKeyAuth: []
paths:
  /video/clip:
    post:
      summary: Clip Video
      operationId: video_clip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                asset_id:
                  type: string
                  description: The video asset ID to create a clip from
                  example: re_657739295220518912
              required:
                - asset_id
      responses:
        '200':
          description: Video clip creation initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: 200
                    description: Response code indicating the result status
                  msg:
                    type: string
                    example: success
                    description: Response message describing the operation result
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                        example: f432bc84bfd141d1b05c1d24af0abe6a
                        description: Unique identifier of the video clip creation task
                    description: Response data object containing task information
                  success:
                    type: boolean
                    example: true
                    description: Indicates whether the operation was successful
                  failed:
                    type: boolean
                    example: false
                    description: Indicates whether the operation failed
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````