SubmitMediaProducingJob接口主要用于提交一個媒體剪輯合成任務。當用戶需要對視頻或音頻素材進行剪輯、合成或其他形式的后期制作時,可以通過調用此API接口來實現自動化處理。
接口說明
- 該接口返回合成任務的提交結果,不保證接口返回時視頻已合成完畢。合成任務將進入后臺排隊,異步執行。
- 云剪輯時間線中引用的素材,既可以是素材庫中的媒資,也可以直接引用 OSS 文件,暫不支持外部地址或 CDN 地址。當素材為 OSS 文件時,MediaUrl 僅支持 OSS 地址格式,如:https://your-bucket.oss-region-name.aliyuncs.com/your-object.ext。
- 視頻合成完成后,會自動注冊媒資,此時媒資還是分析中狀態,當媒資分析完成后,可以根據 MediaId 獲取成片時長及分辨率信息。
使用限制
- 該接口的流量控制值為 30 QPS。
- 視頻軌、圖片軌、字幕軌的軌道數每種均限制最多 100 個。
- 素材個數無限制,素材文件總大小不能超過 1 TB。
- 輸入或輸出 OSS Bucket 所在 Region,必須和使用 IMS 的 Region 保持一致。
- 當輸出為視頻時,成片分辨率有以下限制:
- 寬高都不能小于 128 px。
- 寬高都不能大于 4096 px。
- 短邊不能大于 2160 px。
調試
您可以在OpenAPI Explorer中直接運行該接口,免去您計算簽名的困擾。運行成功后,OpenAPI Explorer可以自動生成SDK代碼示例。
授權信息
下表是API對應的授權信息,可以在RAM權限策略語句的Action
元素中使用,用來給RAM用戶或RAM角色授予調用此API的權限。具體說明如下:
- 操作:是指具體的權限點。
- 訪問級別:是指每個操作的訪問級別,取值為寫入(Write)、讀取(Read)或列出(List)。
- 資源類型:是指操作中支持授權的資源類型。具體說明如下:
- 對于必選的資源類型,用背景高亮的方式表示。
- 對于不支持資源級授權的操作,用
全部資源
表示。
- 條件關鍵字:是指云產品自身定義的條件關鍵字。
- 關聯操作:是指成功執行操作所需要的其他權限。操作者必須同時具備關聯操作的權限,操作才能成功。
操作 | 訪問級別 | 資源類型 | 條件關鍵字 | 關聯操作 |
---|---|---|---|---|
ice:SubmitMediaProducingJob | *全部資源 * |
| 無 |
請求參數
名稱 | 類型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
ProjectId | string | 否 | 剪輯工程 ld。 注意 必須填寫 ProjectId、Timeline、TemplateId 三個參數中的一個,剩余兩個參數填寫為空。 | xxxxxfb2101cb318xxxxx |
Timeline | string | 否 | 云剪輯任務時間線。具體結構定義,請參見 Timeline 配置說明。 注意 必須填寫 ProjectId、Timeline、TemplateId 三個參數中的一個,剩余兩個參數填寫為空。 | {"VideoTracks":[{"VideoTrackClips":[{"MediaId":"****4d7cf14dc7b83b0e801c****"},{"MediaId":"****4d7cf14dc7b83b0e801c****"}]}]} |
TemplateId | string | 否 | 模板 Id,用于快速低門檻的構建時間線。 注意 必須填寫 ProjectId、Timeline、TemplateId 三個參數中的一個,剩余兩個參數填寫為空。
當 TemplateId 不為空時,ClipsParam 不能為空。 | ****96e8864746a0b6f3**** |
ClipsParam | string | 否 | 見模板使用文檔 | |
ProjectMetadata | string | 否 | 剪輯工程的元數據信息,Json 格式。具體結構定義參見 ProjectMetadata 。 | {"Description":"剪輯視頻描述","Title":"剪輯標題測試"} |
OutputMediaTarget | string | 否 | 輸出成品的目標類型。取值:
| oss-object |
OutputMediaConfig | string | 是 | 輸出成品的目標配置,Json 格式。可以設置輸出成品的在 OSS 上的 URL,或者 VOD Bucket 中的存儲位置。 輸出到 OSS 時,輸出目標的 MediaURL 必填;輸出到 VOD 時,StorageLocation 和 FileName 兩個參數必填。 | {"MediaURL":"https://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4"} |
UserData | string | 否 | 自定義設置,Json 格式,長度限制為 512 字節。支持自定義回調地址配置。其中:
| {"NotifyAddress":"https://xx.com/xx","RegisterMediaNotifyAddress":"https://xxx.com/xx"} |
ClientToken | string | 否 | 保證請求冪等性。 | ****12e8864746a0a398**** |
Source | string | 否 | 剪輯合成請求來源,取值范圍:
| OPENAPI |
EditingProduceConfig | string | 否 | 剪輯合成參數, 參數詳情。 說明
EditingProduceConfig 沒有配置封面圖片時,則默認使用視頻的第一幀作為封面。
| { "AutoRegisterInputVodMedia": "true", "OutputWebmTransparentChannel": "true" } |
MediaMetadata | string | 否 | 合成視頻的元數據,JSON 格式。具體結構定義,請參見 MediaMetadata 。 | { "Title":"test-title", "Tags":"test-tags1,tags2" } |
OutputMediaConfig 參數示例
示例:輸出到 OSS
{
"MediaURL":"https://my-test-bucket.oss-cn-shanghai.aliyuncs.com/test/xxxxxtest001xxxxx.mp4",
"Bitrate": 2000,
"Width": 800,
"Height": 680
}
當輸出到 OSS 時,MediaURL 必填。OutputMediaTarget 參數默認值為 "oss-object", 表示輸出到 OSS。 其他參數可以選填,其中 Bitrate 用來設置輸出成品的碼率,通常碼率越高越清晰,最大可以設置到 5000。 Width, Height 用來設置成品的分辨率。
OSS URL 的路徑格式: https://bucketname.oss-region-name.aliyuncs.com/xxx/yyy.ext
bucketname 是 OSS Bucket 的名稱。
oss-region-name.aliyuncs.com 是 OSS 文件的外網 Endpoint,比如上海,北京,杭州的分別是:
oss-cn-shanghai.aliyuncs.com
oss-cn-hangzhou.aliyuncs.com
oss-cn-beijing.aliyuncs.com
示例:輸出到 vod
{
"StorageLocation": "outin-*xxxxxx7d2a3811eb83da00163exxxxxx.oss-cn-shanghai.aliyuncs.com",
"FileName": "output.mp4",
"Bitrate": 2000,
"Width": 800,
"Height": 680
}
當輸出到 VOD 時, StorageLocation 和 FileName 兩個參數必填。OutputMediaTarget 參數設置為 "vod-media", 表示輸出到點播 VOD 的存儲 Bucket。點播 VOD 可以使用的存儲位置可以在 VOD 里面上傳媒資后,在媒資的存儲地址中看到。
OutputMediaConfig 結構中的參數說明
屬性名 | 類型 | 描述 |
---|---|---|
MediaURL | String | 輸出的媒資的 URL (當 OutputMediaTarget 的目標為 oss-object 時, 指定 OSS 文件的 HTTP URL 路徑), 如:http://xxx-bucket-name.oss-cn-shanghai.aliyuncs.com/OSS 跟調用的服務所在區域相同。 |
StorageLocation | String | 當 OutputMediaTarget 的目標為 vod-media 時, 指定 storage location 來存儲媒資到 VOD;storage location 是 VOD 中的文件存儲位置, 不包含 http:// 的前綴, 如:outin-xxxxxx.oss-cn-shanghai.aliyuncs.com。 |
FileName | String | 當 OutputMediaTarget 的目標為 vod-media 時,指定 fileName(包含文件后綴,不含路徑)作為輸出文件名。 |
Width | Integer | 輸出成品的寬。可以不填,默認值是多個素材的最大寬。 |
Height | Integer | 輸出成品的高。可以不填,默認值是多個素材的最大高。 |
Bitrate | Integer | 輸出成品的碼率,單位為 Kbps。可以不填,默認值是多個素材的最高碼率。 |
VodTemplateGroupId | String | 合成成片輸出到 vod,指定 vod 轉碼模板組。如不需要 VOD 轉碼,請填寫 "VOD_NO_TRANSCODE"。 |
返回參數
示例
正常返回示例
JSON
格式
{
"RequestId": "****36-3C1E-4417-BDB2-1E034F****",
"ProjectId": "****b4549d46c88681030f6e****",
"JobId": "****d80e4e4044975745c14b****",
"MediaId": "****c469e944b5a856828dc2****",
"VodMediaId": "****d8s4h75ci975745c14b****"
}
錯誤碼
HTTP status code | 錯誤碼 | 錯誤信息 |
---|---|---|
400 | InvalidParameter | The specified parameter \ is not valid. |
404 | ProjectNotFound | The specified project not found |
訪問錯誤中心查看更多錯誤碼。
變更歷史
變更時間 | 變更內容概要 | 操作 |
---|---|---|
2023-11-23 | OpenAPI 錯誤碼發生變更 | 查看變更詳情 |
2023-04-25 | OpenAPI 錯誤碼發生變更、OpenAPI 入參發生變更 | 查看變更詳情 |
2021-11-16 | OpenAPI 錯誤碼發生變更、OpenAPI 入參發生變更、OpenAPI 返回結構發生變更 | 查看變更詳情 |