調用SubmitSnapshotJob介面建立截圖-ApsaraVideo for Media Processing-阿里雲

提交截圖作業。調用本介面之後ApsaraVideo for Media Processing會對輸入檔案進行截圖和拼圖。

介面說明

輸入單個檔案大小最大支援 100 GB，超過可能導致執行失敗。
請確認檔案已成功上傳至 OSS 後再提交截圖作業，否則會導致執行失敗。您可通過配置 OSS 回調訊息確認檔案上傳狀態。
截圖作業分為同步和非同步模式。
- 同步模式僅支援單張截圖，會在介面返回時產生圖片。
- 非同步模式不保證時效性，在提交截圖作業後，任務會添加到管道中排隊，被調度執行。所以在介面返回時，不保證截圖已經產生。執行完成後需要調用查詢截圖作業結果介面輪詢執行結果，或通過為管道綁定 MNS 訊息接收執行結果，具體請參見接收訊息通知。
- 只要設定了 Interval 和 Num 中的任何一個參數，就表示使用非同步模式。
目前僅支援產生 JPG 格式圖片。
更多截圖常見問題，請參見截圖常見問題。

QPS 限制

本介面的單使用者 QPS 限制為 50 次/秒。超過限制，API 呼叫會被限流，這可能會影響您的業務，請合理調用。更多資訊，請參見 QPS 限制。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

mts:SubmitSnapshotJob

create

*全部資源

*

無

請求參數

名稱	類型	必填	描述	樣本值
Input	string	是	作業輸入。詳細說明請參見 Input 詳情。說明在ApsaraVideo for Media Processing API 中，Object 必須經過URL Encoding（基於 UTF-8 編碼）後使用。 OSS 的地區需要與當前 MPS 所在地區保持一致。	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	是	截圖配置。詳細說明，請參見 SnapshotConfig 參數詳情。	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	否	使用者自訂資料。支援中英文、數字、短劃線（-），不能以特殊字元開頭，最大長度 1024 個位元組。	testid-001
PipelineId	string	否	管道 ID，詳細說明，請參見基本概念。可選值：可以通過 MPS 控制台 > 全域設定 > 管道查詢和建立管道。如果需要非同步通知，請為管道綁定 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。單位：px。	0
Color	string	背景顏色。預設：black。可取值範圍：顏色關鍵字，random。說明其中顏色關鍵字支援三種格式，比如黑色，支援 Black，black，#000000。	black
CellSelStep	string	選取單圖片步長。	3
CellHeight	string	單圖片高度。預設截圖輸出解析度高度。	100
CellWidth	string	單圖片寬度。預設截圖輸出解析度寬度。	100
Margin	string	外框寬度。預設：0。單位：px。	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 參數設定為 I 幀（主要畫面格），將只截取主要畫面格。如果指定的時間節點為非主要畫面格，則就近選取主要畫面格。在同等截圖規則下，主要畫面格截圖比普通幀截圖速度快。	intra
Width	string	截圖輸出圖片寬度。	8
Height	string	截圖輸出圖片高度。	8
OutputFile	object	截圖輸出 OSS 配置。
RoleArn	string	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	截圖輸出檔案（OSS Object）。	test.png
Location	string	截圖輸出 OSS Bucket 所在資料中心（OSS Location）。	example-location
Bucket	string	截圖輸出檔案所在 OSS Bucket。	example
Num	string	截圖數量。若指定則表示序列截圖。	10
TileOutputFile	object	拼圖任務大圖的輸出 OSS 配置。
RoleArn	string	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	輸出檔案（OSS Object）。	example.png
Location	string	輸出 OSS Bucket 所在資料中心（OSS Location）。	example-location
Bucket	string	輸出檔案所在 OSS Bucket。	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	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	輸入檔案（OSS Object）。	example.flv
Location	string	輸入 OSS Bucket 所在資料中心（OSS Location）。	example-location'
Bucket	string	輸入檔案所在 OSS Bucket。	example
Count	string	截取圖片的數量。	1
TileCount	string	拼圖圖片數量。	5
UserData	string	使用者自訂資料。	testid-001
Code	string	分析失敗時錯誤碼。若成功則不返回此參數。	ResourceContentBad
PipelineId	string	管道 ID。	dd3dae411e704030b921e52698e5****
Id	string	截圖作業 ID。	f4e3b9ba9f3840c39d6e288056f0****

樣本

正常返回樣本

JSON格式

{
  "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****"
  }
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。