すべてのプロダクト
Search

このプロダクト

    ApsaraVideo VOD:SubmitSnapshotJob

    ドキュメントセンター

    ApsaraVideo VOD:SubmitSnapshotJob

    最終更新日:Apr 07, 2026

    この操作を呼び出して、スナップショットジョブを送信し、動画から非同期でスナップショットをキャプチャします。

    操作説明

    • これは非同期 API です。ジョブを送信すると、ジョブ ID が返されます。その後、ジョブはキューに入れられ、非同期で処理されます。最終結果は、コールバック通知を介して送信されます。また、GetTask 操作を呼び出してジョブステータスを照会することもできます。

    • 現在、JPG フォーマットのスナップショットのみがサポートされています。

    • スナップショットジョブが完了すると、システムは EventType=SnapshotComplete および SubType=SpecifiedTime の SnapshotComplete イベント通知を生成します。

    QPS 制限

    この操作には、ユーザーあたり毎秒 30 クエリ (QPS) の制限があります。この制限を超える呼び出しは、システムによってレート制限の対象となり、ビジネスに影響を与える可能性があります。これに応じて呼び出しを計画してください。詳細については、「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 ロールに付与する必要があります。

    アクション

    アクセスレベル

    リソースタイプ

    条件キー

    依存アクション

    vod:SubmitSnapshotJob

    create

    *All Resource

    *

    		 なし なし

    リクエストパラメーター

    パラメーター

    型

    必須 / 任意

    説明

    例
    VideoId

    string

    任意

    動画の ID。動画 ID は、次のいずれかの方法で取得できます：

    • ApsaraVideo VOD コンソールにログインします。左側のナビゲーションウィンドウで、[メディアファイル] > [オーディオ/ビデオ] を選択して、動画 ID を表示します。

    • アップロード URL と認証情報を提供する CreateUploadVideo 操作のレスポンスから VideoId を取得します。

    • 動画がアップロードされた後、SearchMedia 操作のレスポンスから VideoId を取得します。

    d3e680e618708efbf2cae7cc9312****
    SpecifiedOffsetTime

    integer

    任意

    スナップショットをキャプチャする開始時刻。

    • 単位：ミリ秒。

    • デフォルト値：0。

    0
    Width

    string

    任意

    スナップショットの幅 (ピクセル単位)。有効な値：[8,4096]。デフォルト値は、ソースビデオの幅です。

    1280
    Height

    string

    任意

    スナップショットの高さ (ピクセル単位)。有効な値：[8,4096]。デフォルト値は、ソースビデオの高さです。

    720
    Count

    integer

    任意

    キャプチャするスナップショットの数。デフォルト値：1。

    1
    Interval

    integer

    任意

    スナップショットをキャプチャする間隔。値は 0 以上である必要があります。

    • 単位：秒。

    • デフォルト値：1。

    • Interval を 0 に設定すると、システムは動画の持続時間と Count の値に基づいて、等間隔でスナップショットをキャプチャします。

    1
    SpriteSnapshotConfig

    string

    任意

    スプライトを生成するための構成。このパラメーターを指定すると、システムはスプライトを生成します。パラメーター構造の詳細については、「SpriteSnapshotConfig」をご参照ください。

    {'CellWidth': 120, 'CellHeight': 68, 'Columns': 3,'Lines': 10, 'Padding': 20, 'Margin': 50}
    SnapshotTemplateId

    string

    任意

    スナップショットテンプレートの ID。

    • ID を指定する前に、スナップショットテンプレートを作成することを推奨します。詳細については、「AddVodTemplate」をご参照ください。

    • SnapshotTemplateId を指定すると、Action と VideoId を除く他のすべてのリクエストパラメーターは無視されます。

    f5b228fe693bf55bd87b789****
    UserData

    string

    任意

    JSON フォーマットのカスタム設定。このパラメーターを使用すると、カスタムユーザーデータを渡し、コールバック URL を指定できます。パラメーター構造の詳細については、「UserData」をご参照ください。

    説明

    メッセージコールバック機能を使用するには、まずコンソールで HTTP コールバック URL を設定し、対応するイベントタイプを選択する必要があります。そうしないと、コールバック設定は有効になりません。

    {"MessageCallback":{"CallbackURL":"http://.example.aliyundoc.com"},"Extend":{"localId":"xxx","example":"www"}}
    SpecifiedOffsetTimes

    array

    任意

    動画内のスナップショットをキャプチャする特定の時点の配列。単位：ミリ秒。最大 30 の時点を指定できます。

    integer

    任意

    特定の時点 (ミリ秒単位)。

    1000
    ReferenceId

    string

    任意

    小文字、大文字、数字、ハイフン (-)、アンダースコア (_) を含むことができるカスタム ID。ID は 6～64 文字の長さで、ユーザーごとに一意である必要があります。

    123-123
    説明

    Count または Interval の少なくとも 1 つを指定する必要があります。両方を指定した場合、システムはスナップショット数が少なくなる方のパラメーターを使用します。

    レスポンスフィールド

    フィールド

    型

    説明

    例

    object

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

    RequestId

    string

    リクエスト ID。

    25818875-5F78-5EB0-4AF6-D7393642****
    SnapshotJob

    object

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

    JobId

    string

    スナップショットジョブ ID。

    ad90a501b1b94b72374ad0050464****

    例

    成功レスポンス

    JSONJSON

    {
  "RequestId": "25818875-5F78-5EB0-4AF6-D7393642****",
  "SnapshotJob": {
    "JobId": "ad90a501b1b94b72374ad0050464****"
  }
}

    エラーコード

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

    変更履歴

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