Frame capture-Intelligent Media Management(IMM)-阿里云帮助中心

This document explains how to use the Intelligent Media Management (IMM) media transcoding API to capture video frames and save them as static images.

Overview

Frame capture extracts specific frames from a video and saves them as static images.

Use cases

Snapshot: Save a specific moment in a video as a static image to create a poster.
Analysis: Extract keyframes for analysis, such as facial recognition and object detection.
Thumbnail creation: Create thumbnails or cover images for videos.
Playback summary: Select multiple key moments from a video to generate a concise summary or preview.
Screenshot sharing and recording: Capture and save or share a specific frame while watching a video.

Supported audio and video formats

Category	Format
Audio	All mainstream formats, such as AAC, MP3, WAV, FLAC, WMA, AC3, and OPUS.
Video	All mainstream formats, such as MP4, MPEG-TS, MKV, MOV, AVI, FLV, M3U8, WebM, WMV, RM, and VOB.

How to use

Prerequisites

Create an AccessKey. For more information, see Create an AccessKey.
Activate Object Storage Service (OSS) and create a bucket. For more information, see Create a bucket.
Activate Intelligent Media Management (IMM). For more information, see Activate IMM.
Create a project in the IMM console. For more information, see Create a project.
Note
- You can also call an API operation to create a project. For more information, see Create a project.
- You can call the ListProjects operation to list all projects that are created in a specified region.

Step 1: Upload a file

In the OSS console, upload a media file to a bucket located in the same region as your IMM project.

On the File Management page of the bucket, click Upload File. Then, click Scan File to select the media file that you want to upload. Make sure that the file ACL is set to Inherit from Bucket and click Upload File. The size of a single file cannot exceed 5 GB.

Step 2: Perform frame capture

Call the CreateMediaConvertTask operation to create a frame capture task.

Parameters

The following example uses the IMM project test-project to perform frame capture on the video file oss://test-bucket/video-demo/brewing.mov. For more information about media processing features, see Media transcoding.

Note

You can use the media transcoding API in OpenAPI Explorer to process video files. For more information, see the SDK sample code.
For frame capture, do not set the Target.URI and Target.Container parameters.
We recommend that you set the URI filename in Targets to the snapshot-{index}.{autoext} format by using variables. After snapshots are saved, filenames such as snapshot-1.png and snapshot-2.png are generated. For more information about the relevant variables, see TargetURI template.

Capture a frame for a video thumbnail

Capture a single frame to use as a video thumbnail. This ensures that the resolution of the image is the same as that of the video.

Output format: jpg
Start time: 5 seconds
Number of frames: 1
Output path: oss://test-bucket/video-demo/cover.jpg
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {  
    "MNS": {    
      "TopicName": "test-mns-topic" 
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "StartTime": 5,
            "Number": 1,
            "URI": "oss://test-bucket/video-demo/cover.jpg"
          }
        ]
      }
    }
  ]
}

Capture frames for AI training and inference

An image frame is captured every 10 seconds for AI model training or inference. The resolution of the output image is limited to 512x512.

Output format: jpg
Interval: 10 seconds
Resize method: crop. For more information, see Resize methods.
Output width: 512 px
Output height: 512 px
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {  
    "MNS": {    
      "TopicName": "test-mns-topic"  
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Interval": 10,
            "ScaleType": "crop",
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}",
            "Width": 512,
            "Height": 512
          }
        ]
      }
    }
  ]
}

Capture frames to analyze a video segment

Starting from the 11-second mark, capture five frames at 4-second intervals to analyze a video segment. The width and height of the output images are half of the video resolution. The images are saved in PNG format.

Output format: png
Start time: 11 seconds
Interval: 4 seconds
Number of frames: 5
Resize method: crop. For more information, see Resize methods.
Output width: Half of the original video width.
Output height: Half of the original video height.
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {  
    "MNS": {    
      "TopicName": "test-mns-topic"
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "png",
            "StartTime": 11,
            "Interval": 4,
            "Number": 5,
            "ScaleType": "crop",
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}",
            "Width": 0.5,
            "Height": 0.5
          }
        ]
      }
    }
  ]
}

Capture event keyframes from a video

This method uses the dhash algorithm to analyze content similarity between video frames. Based on a threshold, it extracts frames with significant changes to serve as event keyframes.

Important

You may need to adjust the threshold based on your business requirements.

Output format: jpg
Interval: 1 second
Capture mode: dhash
Threshold: 15
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {
    "MNS": {
      "TopicName": "test-mns-topic"
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Interval": 1,
            "Mode": "dhash",
            "Threshold": 15,
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}"
          }
        ]
      }
    }
  ]
}

Capture representative keyframes for inference

Use the dhash algorithm to analyze the content similarity of video frames and capture the five frames with the most significant changes.

Output format: jpg
Keyframe interval: 1 second
Capture mode: dhash
Number of frames: 5
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {
    "MNS": {
      "TopicName": "test-mns-topic"
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Interval": 1,
            "Mode": "dhash",
            "Number": 5,
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}"
          }
        ]
      }
    }
  ]
}

Capture all IDR frames

Output format: jpg
Capture mode: keyframe
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {
    "MNS": {
      "TopicName": "test-mns-topic"
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Mode": "keyframe",
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}"
          }
        ]
      }
    }
  ]
}

Capture 10 frames at even intervals

Output format: jpg
Capture mode: average
Number of frames: 10
Output path: oss://test-bucket/video-demo/snapshot-{index}.{autoext}
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {
    "MNS": {
      "TopicName": "test-mns-topic"
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/Winemaking.mov"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Mode": "average",
            "Number": 10,
            "URI": "oss://test-bucket/video-demo/snapshot-{index}.{autoext}"
          }
        ]
      }
    }
  ]
}

Capture an audio cover

Output format: jpg
Number of frames: 1
Output path: oss://test-bucket/video-demo/cover.jpg
Completion notification: Send a message to the MNS topic named "test-mns-topic".

Visit OpenAPI Explorer for a pre-filled SDK sample. You can modify the parameters as needed for debugging.

Sample request parameters:

{
  "ProjectName": "test-project",
  "Notification": {  
    "MNS": {    
      "TopicName": "test-mns-topic"  
    }
  },
  "Sources": [
    {
      "URI": "oss://test-bucket/video-demo/test.mp3"
    }
  ],
  "Targets": [
    {
      "Image": {
        "Snapshots": [
          {
            "Format": "jpg",
            "Number": 1,
            "URI": "oss://test-bucket/video-demo/cover.jpg"
          }
        ]
      }
    }
  ]
}

Billing

Frame capture generates the following billable items for OSS and IMM:

OSS: For more information about pricing, see OSS Pricing.

API	Billable item	Description
GetObject	GET requests	You are charged based on the number of successful requests.
	Infrequent Access data retrieval	Retrieving Infrequent Access data incurs a data retrieval fee.
	Archive-direct data retrieval	If you read an archived object from a bucket for which archive-direct is enabled, you are charged a fee for data retrieval.
	Transfer acceleration	If you enable transfer acceleration and use an acceleration endpoint to access your bucket, you are charged a fee for transfer acceleration based on data volume.
PutObject	PUT requests	You are charged based on the number of successful requests.
PutObject	Storage fees	You are charged for storage based on the storage class, size, and storage duration of an object.
HeadObject	GET requests	You are charged based on the number of successful requests.

IMM: For more information about pricing, see IMM billable items.
Important
Starting from 11:00 (UTC+8) on July 28, 2025, the prices for the IMM frame capture service will be adjusted. For more information, see the IMM billing adjustment notice.
API
Billable item
Description
CreateMediaConvertTask
VideoFraming
You are charged for video frame capture based on the number of successfully captured frames.

Resize methods

Resize method

Resize effect

stretch

Stretches the image to fill the target dimensions. A different aspect ratio will distort the output image.

crop

Resizes and crops the image. The image is resized proportionally to cover the target dimensions, then cropped to the target width and height.

fill

Resizes the image and adds black borders. The image is proportionally resized to fit within the target dimensions, filling the remaining space with black borders.

fit

Resizes the image without adding black borders. The image is proportionally resized to fit within the target dimensions. If the aspect ratio of the output image is different from that of the original image, the width and height of the output image will not be the same as the specified dimensions.