すべてのプロダクト
Search

このプロダクト

    :SubmitSnapshotJob

    ドキュメントセンター

    :SubmitSnapshotJob

    最終更新日:Feb 25, 2026

    スナップショットジョブを送信します。この API を呼び出すと、ApsaraVideo Media Processing (MPS) が入力ファイルに対してスナップショットの取得およびイメージのタイル処理（画像並べ）を実行します。

    操作説明

    • 単一の入力ファイルの最大サイズは 100 GB です。このサイズを超えるファイルでは、ジョブが失敗する可能性があります。

    • スナップショットジョブを送信する前に、ファイルが正しく Object Storage Service (OSS) にアップロード済みであることを確認してください。そうでない場合、ジョブは失敗します。OSS コールバックメッセージを設定することで、ファイルのアップロード状況を確認できます。

    • スナップショットジョブは同期モードおよび非同期モードをサポートしています。

      • 同期モードでは、単一のスナップショットのみの取得が可能です。イメージは API の応答返却時に生成されます。

      • 非同期モードでは、タイムリネスは保証されません。スナップショットジョブを送信すると、タスクは MPS キューに登録され、スケジューリングおよび実行待ちとなります。そのため、API の応答返却時にはスナップショットがまだ生成されていない場合があります。ジョブ完了後は、スナップショットジョブ結果の照会 API を定期的に呼び出して結果をポーリングするか、MPS キューに MNS トピックをアタッチして MNS メッセージ経由で結果を受信する必要があります。詳細については、「」および「メッセージ通知の受信」をご参照ください。

      • Interval または Num パラメーターのいずれかが設定されている場合、非同期モードが使用されます。

    • 現在、出力形式として JPG 形式のイメージのみがサポートされています。

    • スナップショットに関するその他のよくある質問については、「スナップショット FAQ」をご参照ください。

    クエリ/秒 (QPS) 制限

    この API の QPS 制限は、ユーザーあたり 50 クエリ/秒です。この制限を超えると、レート制限が適用され、業務に影響を及ぼす可能性があります。適切な頻度でこの API を呼び出してください。詳細については、「QPS 制限」をご参照ください。

    今すぐお試しください

    この API を OpenAPI Explorer でお試しください。手作業による署名は必要ありません。呼び出しに成功すると、入力したパラメーターに基づき、資格情報が組み込まれた SDK コードが自動的に生成されます。このコードをダウンロードしてローカルで使用できます。

    テスト

    RAM 認証

    下表に、この API を呼び出すために必要な認証情報を示します。認証情報は、RAM (Resource Access Management) ポリシーを使用して定義できます。以下で各列名について説明します。

    • アクション：特定のリソースに対して実行可能な操作。ポリシー構文ではAction要素として指定します。

    • API：アクションを具体的に実行するための API。

    • アクセスレベル：各 API に対して事前定義されているアクセスの種類。有効な値：create、list、get、update、delete。

    • リソースタイプ：アクションが作用するリソースの種類。リソースレベルでの権限をサポートするかどうかを示すことができます。ポリシーの有効性を確保するため、アクションの対象として適切なリソースを指定してください。

      • リソースレベルの権限を持つ API の場合、必要なリソースタイプはアスタリスク (*) でマークされます。ポリシーのResource要素で対応する ARN を指定してください。

      • リソースレベルの権限を持たない API の場合、「すべてのリソース」と表示され、ポリシーのResource要素でアスタリスク (*) でマークされます。

    • 条件キー：サービスによって定義された条件のキー。このキーにより、きめ細やかなアクセス制御が可能になります。この制御は、アクション単体に適用することも、特定のリソースに対するアクションに適用することもできます。Alibaba Cloud は、サービス固有の条件キーに加えて、すべての RAM 統合サービスに適用可能な一連の共通条件キーを提供しています。

    • 依存アクション：ある特定のアクションを実行するために、前提として実行が必要となる他のアクション。依存アクションの権限も RAM ユーザーまたは RAM ロールに付与する必要があります。

    アクション

    アクセスレベル

    リソースタイプ

    条件キー

    依存アクション

    mts:SubmitSnapshotJob

    create

    *All Resource

    *

    		 なし なし

    リクエストパラメーター

    パラメーター

    型

    必須 / 任意

    説明

    例
    Input

    string

    必須

    ジョブ入力に関する情報です。値は JSON オブジェクトである必要があります。ジョブ入力として使用する OSS オブジェクトを格納する OSS バケットを、MPS コンソールのメディアバケットとして登録する必要があります。OSS バケットをメディアバケットとして登録するには、MPS コンソールにログインし、左側のナビゲーションウィンドウから [ワークフロー] ＞ [メディアバケット] を選択して、[バケットの追加] をクリックします。OSS バケットがメディアバケットとして登録された後は、OSS オブジェクトに対して URL エンコーディングを実行する必要があります。例： {"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}。この例では、"example-bucket.example-location.aliyuncs.com/example/test.flv" オブジェクトを指定しています。

    説明

    OSS バケットは、ご利用の MPS サービスと同じリージョンに存在している必要があります。

    {"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
    SnapshotConfig

    string

    必須

    スナップショットの構成です。「データ型」トピックの「AliyunSnapshotConfig」セクションをご参照ください。

    説明

    SnapshotConfig 内にネストされた Interval パラメーターを設定した場合、指定された間隔でスナップショットが取得されます。Interval パラメーターのデフォルト値は 10（単位：秒）です。入力動画の長さが短いにもかかわらず、Num および Interval パラメーターの両方に大きな値を指定した場合、実際に取得されるスナップショットの数は指定数より少なくなることがあります。たとえば、10 秒の動画に対して Num を 5、Interval を 3 に設定した場合、取得可能なスナップショットの数は 5 に達しません。

    {"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
    UserData

    string

    任意

    カスタムデータです。文字、数字、ハイフン (-) のみを使用でき、最大サイズは 1,024 バイトです。カスタムデータは特殊文字で始めてはいけません。

    testid-001
    PipelineId

    string

    任意

    スナップショットジョブを送信する MPS キューの ID です。ID を取得するには、MPS コンソール にログインし、左側のナビゲーションウィンドウから [グローバル設定] ＞ [パイプライン] を選択します。

    説明

    指定した MPS キューに利用可能な Message Service (MNS) トピックがバインドされていることを確認してください。そうでない場合、関連するメッセージが期待通りに送信されない可能性があります。

    dd3dae411e704030b921e52698e5****

    レスポンスフィールド

    フィールド

    型

    説明

    例

    object

    レスポンスパラメーターです。

    RequestId

    string

    リクエストの ID です。

    19B6D8C5-A5DD-467A-B435-29D393C71E2D
    SnapshotJob

    object

    スナップショットジョブに関する情報です。

    CreationTime

    string

    ジョブが作成された時刻です。

    2021-05-19T03:11:48Z
    SnapshotConfig

    object

    スナップショットの構成です。

    Time

    string

    スナップショット取得の開始時刻です。単位：ミリ秒。

    5
    TileOut

    object

    タイル処理の構成です。

    Padding

    string

    タイル化されたイメージ内の連続する単一イメージ間の距離です。

    • デフォルト値：0。

    • 単位：ピクセル。

    0
    Color

    string

    背景色です。

    • デフォルト値：black。

    • リクエスト内で Color パラメーターを カラーキーワード または random として設定できます。

    説明

    背景色を黒に設定する場合は、カラーキーワードを次のいずれかの形式で指定できます：Black、black、#000000。

    black
    CellSelStep

    string

    単一イメージを選択する際のステップです。

    3
    CellHeight

    string

    単一イメージの高さです。デフォルト値は出力スナップショットの高さです。

    100
    CellWidth

    string

    単一イメージの幅です。デフォルト値は出力スナップショットの幅です。

    100
    Margin

    string

    タイル化されたイメージのマージン幅です。

    • デフォルト値：0。

    • 単位：ピクセル。

    5
    Columns

    string

    タイル化されたイメージに含まれる列数です。デフォルト値：10。

    10
    IsKeepCellPic

    string

    単一イメージを保持するかどうかを示します。有効な値：

    • true：単一イメージを保持します。

    • false：単一イメージを保持しません。

    • デフォルト値：true。

    false
    Lines

    string

    タイル化されたイメージに含まれる行数です。デフォルト値：10。

    10
    Interval

    string

    スナップショット取得の間隔です。

    • リクエストでこのパラメーターを指定した場合、指定された間隔でスナップショットが取得されます。リクエストでの値は 0 より大きい必要があります。

    • 単位：秒。

    • デフォルト値：10。

    20
    FrameType

    string

    スナップショットの種別です。デフォルト値：Normal。有効な値：

    • normal：通常フレーム。

    • intra：I フレーム（キーフレーム）。

    説明

    リクエストで FrameType パラメーターを intra に設定した場合、キーフレームのみが取得されます。指定された時刻にキーフレームが見つからない場合は、最も近いキーフレームが取得されます。同じスナップショットルールを適用した場合、キーフレームの取得は通常フレームよりも高速です。

    intra
    Width

    string

    出力スナップショットの幅です。

    8
    Height

    string

    出力スナップショットの高さです。

    8
    OutputFile

    object

    スナップショットジョブの出力ファイルに関する情報です。

    RoleArn

    string

    指定した RAM ロールの Alibaba Cloud リソースネーム (ARN) です。フォーマット：acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Object

    string

    スナップショットジョブの出力ファイルとして生成される OSS オブジェクトです。

    test.png
    Location

    string

    出力スナップショットを格納する OSS バケットが存在する OSS リージョンです。

    example-location
    Bucket

    string

    出力スナップショットを格納する OSS バケットです。

    example
    Num

    string

    スナップショットの数です。リクエストで Num パラメーターを設定した場合、指定された間隔でスナップショットが取得されます。

    10
    TileOutputFile

    object

    タイル処理ジョブの出力ファイルに関する情報です。

    RoleArn

    string

    指定した RAM ロールの ARN です。フォーマット：acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Object

    string

    タイル処理ジョブの出力ファイルとして生成される OSS オブジェクトです。

    example.png
    Location

    string

    オブジェクトを格納する OSS バケットが存在するリージョンの ID です。

    example-location
    Bucket

    string

    オブジェクトを格納する OSS バケットです。

    example
    TimeArray

    object

    TimePointList

    array

    指定された時刻ポイントの配列です。

    integer

    指定された時刻ポイントの配列です。単位はミリ秒で、小数点以下 2 桁の浮動小数点数で表されます。値は重複可能であり、任意の順序で送信できます。MPS が自動的にソートを行います。最大 100 個の時刻ポイントを指定できます。このパラメーターを指定した場合、Num、Time、Interval のいずれのパラメーターも指定してはいけません。いずれかが指定された場合、システムはエラー「InvalidParameter.Ambiguity」を返します。

    [10050, 50000, 110000, 1000500, 1100500]
    State

    string

    スナップショットジョブのステータスです。有効な値：

    • Submitted：ジョブが送信されました。

    • Snapshoting：ジョブが処理中です。

    • Success：ジョブが成功しました。

    • Fail：ジョブが失敗しました。

    Snapshoting
    Message

    string

    ジョブが失敗した場合に返されるエラーメッセージです。ジョブが成功した場合は、このパラメーターは返されません。

    The resource operated InputFile is bad
    MNSMessageResult

    object

    MNS が送信する、ジョブ結果を通知するメッセージです。

    MessageId

    string

    メッセージの ID です。ジョブが失敗した場合は、このパラメーターは返されません。

    799454621135656C7F815F198A76****
    ErrorMessage

    string

    ジョブが失敗した場合に返されるエラーメッセージです。ジョブが成功した場合は、このパラメーターは返されません。

    The resource operated InputFile is bad
    ErrorCode

    string

    ジョブが失敗した場合に返されるエラーコードです。ジョブが成功した場合は、このパラメーターは返されません。

    InvalidParameter
    Input

    object

    ジョブ入力に関する情報です。

    RoleArn

    string

    指定した RAM ロールの ARN です。フォーマット：acs:ram::$accountID:role/$roleName。

    acs:ram::1:role/testrole
    Object

    string

    入力ファイルとして使用される OSS オブジェクトです。

    example.flv
    Location

    string

    OSS バケットが存在するリージョンです。

    example-location'
    Bucket

    string

    オブジェクトを格納する OSS バケットです。

    example
    Count

    string

    取得されたスナップショットの数です。

    1
    TileCount

    string

    タイル化されたイメージに含まれる単一イメージの数です。

    5
    UserData

    string

    カスタムデータです。

    testid-001
    Code

    string

    ジョブが失敗した場合に返されるエラーコードです。ジョブが成功した場合は、このパラメーターは返されません。

    ResourceContentBad
    PipelineId

    string

    スナップショットジョブが送信された MPS キューの ID です。

    dd3dae411e704030b921e52698e5****
    Id

    string

    スナップショットジョブの ID です。

    f4e3b9ba9f3840c39d6e288056f0****

    例

    成功レスポンス

    JSONJSON

    {
  "RequestId": "19B6D8C5-A5DD-467A-B435-29D393C71E2D",
  "SnapshotJob": {
    "CreationTime": "2021-05-19T03:11:48Z",
    "SnapshotConfig": {
      "Time": "5",
      "TileOut": {
        "Padding": "0",
        "Color": "black",
        "CellSelStep": "3",
        "CellHeight": "100",
        "CellWidth": "100",
        "Margin": "5",
        "Columns": "10",
        "IsKeepCellPic": "false",
        "Lines": "10"
      },
      "Interval": "20",
      "FrameType": "intra",
      "Width": "8",
      "Height": "8",
      "OutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "test.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "Num": "10",
      "TileOutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "example.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "TimeArray": {
        "TimePointList": [
          0
        ]
      }
    },
    "State": "Snapshoting",
    "Message": "The resource operated InputFile is bad",
    "MNSMessageResult": {
      "MessageId": "799454621135656C7F815F198A76****",
      "ErrorMessage": "The resource operated InputFile is bad",
      "ErrorCode": "InvalidParameter"
    },
    "Input": {
      "RoleArn": "acs:ram::1:role/testrole",
      "Object": "example.flv",
      "Location": "example-location'",
      "Bucket": "example"
    },
    "Count": "1",
    "TileCount": "5",
    "UserData": "testid-001",
    "Code": "ResourceContentBad",
    "PipelineId": "dd3dae411e704030b921e52698e5****",
    "Id": "f4e3b9ba9f3840c39d6e288056f0****"
  }
}

    エラーコード

    完全なリストについては、「エラーコード」をご参照ください。

    変更履歴

    完全なリストについては、「変更履歴」をご参照ください。