> ## 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 Frame Description

> Generate timestamped visual descriptions of what appears on screen in a video.

<Info>
  **Product**: Visual Intelligence — Video Task APIs (application layer)
  **Use case**: Pre-packaged video analysis tasks built on top of the Video Model APIs — fixed prompt + workflow, you just POST a video and get a structured result. For full control over prompt and model selection, see Video Model APIs.
  **Host**: `https://mavi-backend.memories.ai/serve/api/v2`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

Analyzes video frames using a Gemini model and produces timestamped descriptions of **what is visually happening** — scene changes, on-screen actions, objects — rather than transcribing spoken words.

**Not the same as Video Caption**: [Video Caption](/visual-intelligence/caption/video-caption) runs on a dedicated `security.memories.ai` service, supports Human ReID (named person identification), and requires a separate API key. Use Video Frame Description for standard frame-by-frame analysis on assets you've uploaded via the main API.

<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:**

  * Input tokens: \$0.45/1M tokens
  * Output tokens: \$3.75/1M tokens
</Note>

## Supported Models

* `gemini-2.5-flash-lite`
* `gemini-2.5-flash`
* `gemini-2.5-flash-preview-09-2025`
* `gemini-2.5-flash-lite-preview-09-2025`

### Request Body

| Parameter | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| asset\_id | string | Yes      | The unique identifier of the video asset to generate visual descriptions for |
| model     | string | Yes      | The model to use for video description (e.g., `gemini-2.5-flash-lite`)       |

### Code Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://mavi-backend.memories.ai/serve/api/v2/transcriptions/async-generate-video \
    --header 'Authorization: sk-mavi-...' \
    --header 'Content-Type: application/json' \
    --data '{
      "asset_id": "re_657929111888723968",
      "model": "gemini-2.5-flash-lite"
    }'
  ```

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

  const response = await fetch(`${BASE_URL}/async-generate-video`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': API_KEY
    },
    body: JSON.stringify({
      asset_id: 're_657929111888723968',
      model: 'gemini-2.5-flash-lite'
    })
  });

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

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

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

  def async_generate_video(asset_id: str, model: str):
      url = f"{BASE_URL}/async-generate-video"
      data = {"asset_id": asset_id, "model": model}
      resp = requests.post(url, json=data, headers=HEADERS)
      return resp.json()

  # Usage example
  result = async_generate_video("re_657929111888723968", "gemini-2.5-flash-lite")
  print(result)
  ```
</CodeGroup>

### Response

Returns the video description task information.

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

  ```json Callback Response theme={null}
  {
    "code": 200,
    "message": "SUCCESS",
    "data": {
      "data": {
        "data": [
          {
            "end_time": 2.0,
            "start_time": 0.0,
            "transcript": "A drone shot flies over a dense forest with lush green trees and some bare branches, suggesting early spring."
          },
          {
            "end_time": 4.0,
            "start_time": 2.0,
            "transcript": "A woman in a flowing light green dress runs across a grassy area towards a wooden structure, her back to the camera."
          },
          {
            "end_time": 6.0,
            "start_time": 4.0,
            "transcript": "A close-up shows a person wearing a costume with antlers and dreadlocks, with a distressed expression."
          }
        ],
        "error_rate": 0.0,
        "usage_metadata": {
          "duration": 0.0,
          "model": "gemini-2.5-flash-lite",
          "output_tokens": 24641,
          "prompt_tokens": 283901
        }
      },
      "msg": "Video description completed successfully",
      "success": true
    },
    "task_id": "580e35a50faa437480b2d425bdcf1c87"
  }
  ```
</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 description task  |
| success       | boolean | Indicates whether the operation was successful   |
| failed        | boolean | Indicates whether the operation failed           |

### Callback Response Parameters

When the video description 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 description result and metadata     |
| data.data                                | object  | Inner data object containing description segments and usage information |
| data.data.data                           | array   | Array of description segments with timestamps                           |
| data.data.data\[].start\_time            | number  | Start time of the segment in seconds                                    |
| data.data.data\[].end\_time              | number  | End time of the segment in seconds                                      |
| data.data.data\[].transcript             | string  | Visual description text for this time segment                           |
| data.data.error\_rate                    | number  | Error rate of the description (0.0 means no errors)                     |
| data.data.usage\_metadata                | object  | Usage statistics for the API call                                       |
| data.data.usage\_metadata.duration       | number  | Processing duration in seconds                                          |
| data.data.usage\_metadata.model          | string  | The AI model used for description (e.g., "gemini-2.5-flash-lite")       |
| data.data.usage\_metadata.output\_tokens | integer | Number of tokens in the generated description                           |
| data.data.usage\_metadata.prompt\_tokens | integer | Number of tokens in the input prompt                                    |
| data.msg                                 | string  | Detailed message about the operation result                             |
| data.success                             | boolean | Indicates whether the description was successful                        |
| task\_id                                 | string  | The task ID associated with this description request                    |


## OpenAPI

````yaml POST /transcriptions/async-generate-video
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:
  /transcriptions/async-generate-video:
    post:
      summary: Async Generate Video Transcription
      description: Generate video transcription asynchronously.
      operationId: async_generate_video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                asset_id:
                  type: string
                  description: The video asset ID to transcribe
                  example: re_657929111888723968
                model:
                  type: string
                  description: The transcription model to use
                  example: gemini-2.5-flash-lite
              required:
                - asset_id
                - model
      responses:
        '200':
          description: Transcription task information
          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: ec2449885ba84c4f943a80ff0633158e
                        description: Unique identifier of the video transcription 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

````