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

# Extract Video Frames

> Extract individual frames from a video asset

<Info>
  **Product**: Visual Intelligence — Asset Management
  **Use case**: Upload, manage, and download video/image assets used by other Visual Intelligence APIs
  **Host**: `https://mavi-backend.memories.ai/serve/api/v2`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

This endpoint automatically extracts frames from a video file at regular intervals.

<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.01/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/extract-frames`, {
    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/extract-frames`, {
    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 extract_frames(asset_id):
      url = f"{BASE_URL}/video/extract-frames"
      data = {"asset_id": asset_id}
      response = requests.post(url, json=data, headers=HEADERS)
      return response.json()

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

### Request Body

| Field     | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| asset\_id | string | Yes      | The video asset ID to extract frames from |

### Response

Returns task information for the frame extraction operation.

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

  ```json Callback Response theme={null}
  {
    "code": 200,
    "message": "SUCCESS",
    "data": {
      "asset_ch_ids": [
        "imc_666914042514116608_0",
        "imc_666914042514116608_1",
        "imc_666914042514116608_2",
        "..."
      ],
      "asset_id": "im_666914042514116608"
    },
    "task_id": "90b7eaf351824f3ba88229eaf2bf7c3d"
  }
  ```
</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 frame extraction task   |
| success       | boolean | Indicates whether the operation was successful   |
| failed        | boolean | Indicates whether the operation failed           |

### Callback Response Parameters

When the frame extraction 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 the extracted frame information                                                                                                                                                                                                                            |
| data.asset\_ch\_ids | array  | Array of individual frame asset IDs. Use any `asset_ch_id` with the [Download](/visual-intelligence/base/download) or [Get Metadata](/visual-intelligence/base/get-metadata) endpoint to download or query a **single frame image**.                                                       |
| data.asset\_id      | string | The parent group asset ID for the entire frame collection. Use this ID with the [Download](/visual-intelligence/base/download) endpoint to download **all frames as a zip package**, or with [Get Metadata](/visual-intelligence/base/get-metadata) to list all frames in this collection. |
| task\_id            | string | The task ID associated with this frame extraction request                                                                                                                                                                                                                                  |

### Using the Returned IDs

Frame IDs follow the pattern `imc_<parent_id>_<frame_index>` (0-indexed).

| ID                                                       | [Download](/visual-intelligence/base/download) returns | [Get Metadata](/visual-intelligence/base/get-metadata) returns |
| -------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
| `data.asset_id` (e.g. `im_666914042514116608`)           | Zip of all frames                                      | List of all frames in the collection                           |
| `data.asset_ch_ids[n]` (e.g. `imc_666914042514116608_0`) | Single frame image                                     | Metadata for that frame                                        |

```python theme={null}
download_asset("imc_666914042514116608_0")   # single frame
download_asset("im_666914042514116608")       # all frames as zip
```


## OpenAPI

````yaml POST /video/extract-frames
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/extract-frames:
    post:
      summary: Extract Video Frames
      operationId: extract_frames
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                asset_id:
                  type: string
                  description: The video asset ID to extract frames from
                  example: re_657739295220518912
              required:
                - asset_id
      responses:
        '200':
          description: Frame extraction 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: 1e8ae1075e054e8abb58e7598c53cbf1
                        description: Unique identifier of the frame extraction 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

````