すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:マルチフレームのビデオスナップショット

最終更新日:Mar 21, 2026

Object Storage Service (OSS) に保存されているビデオからフレームを抽出し、画像として保存します。この機能を使用して、サムネイルの生成、AI 訓練データセットの準備、シーンチェンジの検出、ビデオプレビューストリップの構築などを行います。

利用シーン

  • サムネイルとカバーの生成:代表的なフレームを抽出し、ビデオのカバーやサムネイルとして使用します。

  • AI 訓練データ:モデルトレーニングや推論パイプラインのために、一定間隔でフレームをサンプリングします。

  • シーンチェンジの検出:`dhash` モードを使用して、視覚的なコンテンツが大幅に変化するフレームをキャプチャします。

  • ビデオプレビュー:均等に分散されたフレームを抽出し、ユーザーにビデオコンテンツの概要を素早く提供します。

  • オーディオカバーの抽出:FLAC などのオーディオファイルから埋め込まれたアルバムアートワークを抽出します。

  • スクリーンショットの共有と録画:ユーザーがビデオを視聴中に気に入ったフレームを保存または共有したい場合、その瞬間のビデオフレームをキャプチャできます。

仕組み

ソースビデオを OSS バケットにアップロードします。x-oss-async-process パラメーターと video/snapshots 操作を使用して、非同期フレームキャプチャタスクを送信します。タスクが完了すると、キャプチャされたフレームは指定した出力パスに保存されます。

このトピックのすべての例では、x-oss-async-process ヘッダーを使用します。同期処理はサポートされていません。
image

前提条件

開始する前に、以下の準備が整っていることを確認してください:

SDK を使用したフレームのキャプチャ

フレームキャプチャは非同期のみです。Java、Python、または Go の SDK を使用してタスクを送信します。

重要

出力パスからファイル拡張子 (たとえば .jpg など) を省略した場合、システムによってシリアル番号のサフィックス (たとえば _0_1.jpg) が自動的に追加されます。 拡張子を含めると、最後にキャプチャされたフレームのみが保存されます。 すべてのフレームを保持するには、拡張子を省略します。 シリアル番号のフォーマットをカスタマイズするには、ApsaraVideo Media Processing の変数を使用します。

Java

Java SDK 3.17.4 以降が必要です。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;

import java.util.Base64;

public class Demo {
    public static void main(String[] args) throws ClientException {
        // バケットが配置されているリージョンのエンドポイント
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 汎用の Alibaba Cloud リージョン ID
        String region = "cn-hangzhou";
        // 環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET からアクセス認証情報を読み取る
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        String bucketName = "examplebucket";
        // 出力オブジェクト名 (拡張子なし — システムが自動的にシリアル番号を追加します)
        String targetKey = "dest.png";
        // ソースビデオオブジェクト名
        String sourceKey = "src.mp4";

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // フレームキャプチャのパラメーター:JPG 出力、100x100 px、クロップスケーリング、10 秒間隔
            String style = "video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000";
            // バケット名と出力オブジェクト名を Base64 エンコードする
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
            String process = String.format("%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0",
                    style, bucketEncoded, targetEncoded);
            // 非同期フレームキャプチャタスクを送信する
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());
        } finally {
            ossClient.shutdown();
        }
    }
}

Python

Python SDK 2.18.4 以降が必要です。

# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET からアクセス認証情報を読み取る
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    region = 'cn-hangzhou'
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    source_key = 'src.mp4'
    # 出力オブジェクト名 (拡張子なし — システムが自動的にシリアル番号を追加します)
    target_key = 'dest.png'

    # フレームキャプチャのパラメーター:JPG 出力、100x100 px、クロップスケーリング、10 秒間隔
    style = 'video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000'

    # バケット名と出力オブジェクト名を Base64 エンコードする
    bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
    process = f"{style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}/notify,topic_QXVkaW9Db252ZXJ0"

    try:
        # 非同期フレームキャプチャタスクを送信する
        result = bucket.async_process_object(source_key, process)
        print(f"EventId: {result.event_id}")
        print(f"RequestId: {result.request_id}")
        print(f"TaskId: {result.task_id}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Go

Go SDK 3.0.2 以降が必要です。

package main

import (
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // 環境変数 OSS_ACCESS_KEY_ID と OSS_ACCESS_KEY_SECRET からアクセス認証情報を読み取る
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    client, err := oss.New(
        "https://oss-cn-hangzhou.aliyuncs.com", "", "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region("cn-hangzhou"),
    )
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "examplebucket"
    bucket, err := client.Bucket(bucketName)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    sourceKey := "src.mp4"
    // 出力オブジェクト名 (拡張子なし — システムが自動的にシリアル番号を追加します)
    targetKey := "dest.png"

    // フレームキャプチャのパラメーター:JPG 出力、100x100 px、クロップスケーリング、10 秒間隔
    style := "video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000"

    // バケット名と出力オブジェクト名を Base64 エンコードする
    bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
    targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
    process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v/notify,topic_QXVkaW9Db252ZXJ0",
        style, bucketNameEncoded, targetKeyEncoded)

    // 非同期フレームキャプチャタスクを送信する
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
        log.Fatalf("Failed to submit frame capture task: %s", err)
    }

    fmt.Printf("EventId: %s\n", result.EventId)
    fmt.Printf("RequestId: %s\n", result.RequestId)
    fmt.Printf("TaskId: %s\n", result.TaskId)
}

パラメーター

アクション:video/snapshots

パラメータータイプ必須デフォルト説明
f文字列はい出力画像のフォーマット。有効な値:jpgpng
ss整数いいえ0 (動画の開始位置)開始時間 (ミリ秒)。0 より大きい値を設定すると、特定のオフセットから開始します。
m文字列いいえinterスナップショットモード。詳細は、スナップショットモードをご参照ください。
num整数いいえ0 (制限なし)キャプチャするフレーム数。動画の長さや他のパラメーターにより、実際のカウントは指定した値より少なくなる場合があります。avg モードでは、このパラメーターは必須であり、0 にはできません。
inter整数いいえ0 (すべてのフレーム)キャプチャ間隔 (ミリ秒)。この値がソース動画のキーフレーム間隔より小さい場合、フレームはキーフレーム間隔でキャプチャされます。key モードまたは avg モードでは使用されません。
thr整数いいえ0dhash モードのコンテンツ変更のしきい値 (0~100)。値が大きいほど、キャプチャされるフレーム数は少なくなります。この値は 25 以下に保ち、コンテンツに合わせて調整することを推奨します。dhash モードでのみ有効です。
w整数いいえソースの幅出力画像の幅 (ピクセル単位、32~4096)。
h整数いいえソースの高さ出力画像の高さ (ピクセル単位、32~4096)。
pw整数いいえ100ソース動画の幅に対する出力幅のパーセンテージ (0~200)。w が設定されている場合は無視されます。
ph整数いいえ100ソース動画の高さに対する出力高さのパーセンテージ (0~200)。h が設定されている場合は無視されます。
scaletype文字列いいえstretchスケーリングメソッド。詳細は、スケーリングメソッドをご参照ください。
sys/saveas パラメーターおよび notify パラメーターは、ビデオスナップショットにも使用されます。詳細については、「保存先の指定」および「通知」をご参照ください。

スナップショットモード

モード説明
inter (デフォルト)固定間隔inter パラメーターで設定された間隔でフレームをキャプチャします。フレーム数は num パラメーターによって制御されます。
keyキーフレーム: ソースビデオから IDR フレームのみをキャプチャします。フレーム数は num パラメーターによって制御されます。このモードでは inter パラメーターは効果がありません。
avg平均: ビデオの持続時間全体にわたって num パラメーターで指定された数のフレームを均等に分配します。このモードでは inter パラメーターは効果がありません。num は 0 より大きい必要があります。
dhashコンテンツ認識inter パラメーターで設定された間隔でフレームをキャプチャし、次に thr パラメーターで設定されたしきい値を超えて視覚的コンテンツが変化するフレームをフィルター処理します。返されるフレーム数は num パラメーターによって制御されます。

スケーリング方法

動作使用場面
stretch (デフォルト)画像を正確なディメンションに引き伸ばして埋めます。アスペクト比は維持されません。歪みが許容される固定サイズのサムネイル
crop画像をディメンションに合わせてスケーリングし、はみ出した部分をクロップします。アスペクト比は維持されます。正確なディメンションが必要なソーシャルメディアのプレビュー
fill画像をディメンション内に収まるようにスケーリングし、残りのスペースを黒帯で埋めます。アスペクト比は維持されます。レターボックスまたはピラーボックス形式の出力
fit画像をディメンション内に収まるように比例的にスケーリングします。黒帯は追加されず、出力はターゲットのディメンションより小さくなる場合があります。画像全体を表示する必要があるサムネイル
w/h および pw/ph の両方が設定されている場合、pw および ph は無視されます。

出力ファイル名

出力オブジェクト名は、sys/saveas で指定するパスから決定されます:

  • ファイル拡張子なしの場合: システムは、シリアル番号と拡張子を自動的に追加します。たとえば、出力パスが frames/output の場合、キャプチャされたフレームは frames/output_0_1.jpgframes/output_0_2.jpg などとして保存されます。これにより、すべてのキャプチャされたフレームが保持されます。

  • ファイル拡張子ありの場合(例: frames/output.jpg):最後にキャプチャされたフレームのみが保存され、以前のファイルが上書きされます。

シリアル番号のフォーマットをカスタマイズするには、ApsaraVideo Media Processing の変数をご参照ください。

API の例

REST API を直接呼び出すには、「署名バージョン 4 (推奨)」で説明されているようにリクエスト署名を計算します。

API を呼び出す前に、IMM プロジェクトをバケットにアタッチしてください。詳細については、「AttachOSSBucket」をご参照ください。

AI モデルトレーニング用に 10 秒ごとに 1 フレームをキャプチャ

example.mkv から 10 秒ごとの間隔でフレームをキャプチャします。出力: 512×512 の JPG イメージ、クロップ スケーリング。

設定

設定
ソースexample.mkv
出力フォーマットJPG
間隔10 秒
解像度512×512 px(切り抜き)
出力パスoss://outbucket/outobjprefix-%d.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,f_jpg,w_512,h_512,scaletype_crop,inter_10000|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

11 秒目から 4 秒間隔で 5 フレームをキャプチャ

11 秒目から開始し、4 秒間隔で 5 フレームの PNG をキャプチャします。出力ディメンションは、ソースビデオの解像度の 50% です。

設定

設定
ソースexample.mkv
出力フォーマットPNG
開始時間11 秒
間隔4 秒
フレーム数5
解像度ソースの幅と高さの 50%
出力パスoss://outbucket/outobjprefix-%d.png
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,ss_11000,f_png,pw_50,ph_50,num_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

dhash を使用してイベントキーフレームをキャプチャ

`dhash` を使用してシーンチェンジを検出し、視覚的なコンテンツが大幅に変化するフレームを抽出します。

重要

お使いの特定のコンテンツに合わせて、thr パラメーターを調整してください。dhash アルゴリズムはしきい値に対して敏感です。

設定

設定
ソースexample.mkv
スナップショットモードdhash
出力フォーマットJPG
しきい値15
間隔1 秒
解像度ソースと同じ
出力パスoss://outbucket/outobjprefix-%d.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,m_dhash,f_jpg,inter_1000,thr_15|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

最も重要なシーンチェンジフレーム 5 つをキャプチャ

`dhash` を使用して、最も重要な視覚的変化がある 5 つのフレームを見つけます。これは推論パイプラインに適しています。

設定

設定
ソースexample.mkv
スナップショットモードdhash
出力フォーマットJPG
フレーム数5
間隔1 秒
解像度ソースと同じ
出力パスoss://outbucket/outobjprefix-%d.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,m_dhash,f_jpg,inter_1000,num_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

すべての IDR キーフレームをキャプチャ

ビデオからすべての IDR フレームを抽出します。独立してデコード可能なフレームの完全なセットを取得するのに役立ちます。

設定

設定
ソースexample.mkv
スナップショットモードkey
出力フォーマットJPG
解像度ソースと同じ
出力パスoss://outbucket/outobjprefix-%d.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,m_key,f_jpg|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

均等に分散された 10 フレームをキャプチャ

ビデオの全期間にわたって均等に分散された 10 フレームを抽出します。

設定

設定
ソースexample.mkv
スナップショットモードavg
出力フォーマットJPG
フレーム数10
解像度ソースと同じ
出力パスoss://outbucket/outobjprefix-%d.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,m_avg,f_jpg,num_10|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

オーディオカバーアートの抽出

一部のオーディオファイル (FLAC など) にはアルバムアートワークが埋め込まれています。ビデオスナップショット機能を使用して、カバー画像を抽出します。

設定

設定
ソースexample.flac
出力フォーマットJPG
解像度ソースと同じ
出力パスoss://outbucket/cover.jpg
通知MNS トピック example-mns-topic
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

x-oss-async-process=video/snapshots,f_jpg|sys/saveas,b_b3V0YnVja2V0,o_Y292ZXIuanBnCg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

課金

ビデオスナップショットは IMM サービスを使用し、OSS と IMM の両方で課金項目が発生します。

OSS 料金 — 詳細については、「OSS 料金」をご参照ください。

API課金項目基準
GetObjectGET リクエスト成功したリクエストごと
GetObjectインターネット経由の外部へのトラフィックデータ量(パブリックエンドポイント(例: oss-cn-hangzhou.aliyuncs.com)またはアクセラレーションエンドポイントを使用する場合に適用)
GetObject取得した低頻度アクセスデータの量データ量 (低頻度アクセスストレージクラスのオブジェクトに適用)
GetObjectアーカイブオブジェクトのリアルタイムアクセスで取得したデータの量データ量 (アーカイブのリアルタイムアクセスが有効な場合に適用)
GetObject転送アクセラレーションデータ量 (転送アクセラレーションが有効な場合に適用)
PutObjectPUT リクエスト成功したリクエストごと
PutObjectストレージ料金ストレージクラス、サイズ、期間
HeadObjectGET リクエスト成功したリクエストごと

IMM の料金 — 料金の詳細については、「IMM の課金項目」をご参照ください。

重要

2025年7月28日 11:00(UTC + 08:00)より、IMM はビデオスナップショットの価格を引き下げました。対象となる課金項目は VideoFraming です。詳細については、「」および「IMM 課金調整のお知らせ」をご参照ください。

API課金項目基準
CreateMediaConvertTaskVideoFraming成功したスナップショットごと

制限事項

  • 動画スナップショットは、x-oss-async-process を使用した非同期処理のみをサポートします。同期処理はサポートされていません。

  • ソースビデオにタイムスタンプエラーやストリームの破損がある場合、フレームキャプチャが失敗したり、不正な数の画像ファイルが生成されたりすることがあります。

  • 匿名アクセスは拒否されます。

よくある質問

ビデオスナップショット機能は黒画面のフィルタリングをサポートしていますか?

いいえ、黒画面のフィルタリングはサポートされていません。

ビデオスナップショット機能は短いビデオのサムネイル生成をサポートしていますか?

いいえ。短いアニメーションプレビューを作成するには、代わりにビデオからアニメーション画像への変換機能を使用してください。詳細については、「ビデオをアニメーション画像に変換」をご参照ください。

ソースビデオにフォーマットの制限はありますか?

いいえ。すべての主要なビデオフォーマットがサポートされています。

キーフレームモードで、スナップショットの時間が最初の 1 秒以内に収まる場合、キャプチャされるフレームはその時点より前の最も近いキーフレームですか?

はい。

キャプチャされたフレームが期待されるビデオコンテンツではなく、灰色の画像が表示されます。原因は何ですか?

灰色の画像は通常、ビデオのビットレートが高すぎて、スナップショットプロセスが正しくデコードできないことを意味します。フレームをキャプチャする前に、ビデオをより低いビットレートにトランスコードしてください。