使用API提取視頻高光片段的介面參數說明-智能媒體服務-阿里雲

本文旨在介紹SubmitHighlightExtractionJob - 提交高光提取任務，以及通過GetSmartHandleJob擷取高光提取任務的返回參數。

重要

注意：在此介面中，所有媒資的OSS URL中的地區（region）必須與調用OpenAPI服務地址中的地區（region）保持一致。
支援的地區：華東2（上海）、華北2（北京）、華東1（杭州）、華南1（深圳）、美國（西部）、新加坡。其中動作標籤識別的能力（對應參數為Strategy.EnableActionRecog和Strategy.CustomActions），目前的版本僅支援華東2（上海）地區開放。
目前的版本暫不支援輸入不含字幕和人聲的視頻素材，請您務必仔細甄別視頻素材是否符合此條件。

使用說明

從多個視頻素材擷取高光片段的介面說明，請參見SubmitHighlightExtractionJob - 提交高光提取任務，API關鍵參數詳見下文InputConfig 參數說明、OutputConfig 參數說明。
高光片段擷取任務的詳細資料，請參見GetSmartHandleJob - 擷取智慧工作提示結果，任務結果中的關鍵參數詳見AiResult 參數說明。

InputConfig 參數說明

使用者可通過配置InputConfig，指定視頻素材、高光拆條配置等參數。

參數

類型

說明

是否必填

MediaArray

List<Media>

影視劇素材僅可使用視訊格式。可通過傳入媒資ID或素材OSS URL列表進行上傳。視頻的總時間長度最多為兩小時，數量上限為30個。
素材支援的格式詳見視頻格式。

重要

暫不支援輸入不含字幕和人聲的視頻素材

是

Strategy

高光片段拆條策略配置：

Count：單個素材中提取高光片段的數量，其取值範圍為[1,10]，預設值設定為5。
ClipDuration：每個高光片段的期望時間長度，單位秒，取值範圍[3,60]，預設值為15。每個高光片段的時間長度將圍繞該數值呈現一定幅度的波動。
EnableActionRecog: 是否開啟動作識別，預設false。
CustomActions: 自訂動作標籤，優先按照傳入的標籤名稱做映射。例如： ["打鬥","哭泣"]。數組長度上限為50，每個標籤字元上限為5。

否

Strategy 參數說明

參數	類型	說明	是否必填
Count	Integer	單個素材中提取高光片段的數量，其取值範圍為[1,10]，預設值設定為5。	否
ClipDuration	Float	每個高光片段的期望時間長度，單位秒，取值範圍[3,60]，預設值為15。每個高光片段的時間長度將圍繞該數值呈現一定幅度的波動。	否
EnableActionRecog	Boolean	是否開啟動作識別，預設false。說明動作識別僅支援華東2（上海）地區	否
CustomActions	List<String>	自訂動作標籤，優先按照傳入的標籤名稱做映射。例如： ["打鬥","哭泣"]。數組長度上限為50，每個標籤字元上限為5。說明動作識別僅支援華東2（上海）地區	否
HighlightDescription	String	高光提取策略描述。僅在ThemeConfig.ThemeType=SmoothHighlight時生效樣本：優先選取情緒外化明顯、反差感強烈、劇情衝突集中、戲劇性突出的情境，如男主XXX通過動作表達憤怒或守護，身份與行為反差製造張力，圍繞核心矛盾展開，並包含離奇對話或轉折事件，增強代入感與話題度。	否
FaceInfo	FaceInfo	設定人臉資訊有助於識別人物角色。如果希望在高光中儘可能多地展示某些角色，建議配置此參數。	否

FaceInfo 參數說明

參數	類型	說明	是否必填
ImageInfoList	List<ImageInfo>	人物（人臉）照片列表，列表長度上限200。	否

ImageInfo 參數說明

參數	類型	說明	樣本值	是否必填
Name	String	人物（人臉）名稱	丹尼爾	是
ImageURL	String	人物（人臉）照片儲存地址，需要是公網可訪問的URL連結。請確保人臉圖片中僅包含一名個體，並且人臉應清晰可見，無明顯遮擋或缺失現象。	http://[your-cdn-domain]/[your-file-path]/face1.png	是，二選一必填
ImageId	String	圖片媒資ID	**9d46c886b45481030f6e**	是，二選一必填

Media 參數說明

參數

類型

說明

是否必填

MediaId

String

媒資ID

二選一必填

都填寫時優先取用MediaId

MediaURL

String

媒資URL，僅支援自有OSS

參數樣本

{
  "MediaArray": [
    {
      "MediaId": "1cb94770da*******75e6e6c5486302"
    }
  ],
  "Strategy": {
    "Count": 5,
    "ClipDuration": 15,
    "EnableActionRecog": true,
    "CustomActions":  ["打鬥","哭泣"],
    "HighlightDescription":"優先選取具備以下特徵的情境。情緒外化明顯：男主XXX通過動作直接表達強烈情緒，如憤怒、守護或逆襲（如男主XXX與大哥之間的“較勁”）；反差感強烈：通過行為或身份的反差傳遞內在衝突（如權力爭奪、情感張力）；劇情衝突集中：圍繞主角的核心矛盾展開，如家族對抗、身份偽裝等，提升觀眾代入感；戲劇性情節突出：包含離奇對話或轉折事件（如“女扮男裝被認出”），增強吸引力和話題度。",
    "FaceInfo":{"ImageInfoList":[{"Name":"寧X","ImageURL":"http://[your-cdn-domain]/[your-file-path]/face1.png"}]}
  }
}

OutputConfig 參數說明

使用者可通過配置OutputConfig，指定成片輸出地址、名稱規則等合成參數。

參數	類型	說明	必填	樣本
NeedExport	Boolean	是否直接匯出片段。取值範圍： true時，結果返回 false時，結果僅返回高光片段的時間區間，不做實際拆條。	否，預設false	false
OutputMediaTarget	String	當NeedExport = true時必填輸出檔案的目標類型 oss-object（客戶在阿里雲 oss bucket 下的 oss object）	否，預設oss-object	oss-object
Endpoint	String	滿足S3協議的Endpoint OSS， region需與接入服務一致預設為同一region的oss endpoint。	否	https://oss-cn-shanghai.aliyuncs.com
Bucket	String	當NeedExport = true時必填滿足S3協議的儲存Bucket 自有oss 儲存 bucket	否	your bucket
ObjectKey	String	當NeedExport = true時必填滿足S3協議的對象名支援的預留位置： {index}: 必須包含在檔案路徑中	否	dir/to/testOutput_{index}.mp4
ExportAsNewMedia	Boolean	當NeedExport = true時選填是否輸出為新媒資僅當OutputMediaTarget = oss-object時支援填寫	否，預設false	false
Width	Integer	當NeedExport = true時選填成片寬，單位：px。不填則和素材視頻相同	否	1280
Height	Integer	當NeedExport = true時選填成片高，單位：px。不填則和素材視頻相同	否	720
Video	JSONObject	當NeedExport = true時選填輸出視頻流相關配置，Crf、Codec等	否	{ "Bitrate": 3000 }

參數樣本

 {
    "NeedExport": true,
    "OutputMediaTarget": "oss-object",
    "Endpoint": "https://oss-cn-shanghai.aliyuncs.com"
    "Bucket": "your-bucket",
    "ObjectKey": "dir/to/testOutput_{index}.mp4",
    "ExportAsNewMedia": false,
    "Width": 1280,
    "Height": 720,
    "Video": {
      "Bitrate": 3000
    }
  }

GetSmartHandleJob

通過GetSmartHandleJob - 擷取智慧工作提示結果擷取高光片段任務的結果，AiResult的參數說明如下：

AiResult 參數說明

{
  "HighlightResults": [
    {
      "Media": "MediaId1", //如果InputConfig裡輸入的是url，那麼這裡也是url
      "TimeRanges": [
        {
          "In": 20,
          "Out": 30,
          "Tags": ["打鬥","哭泣"], //識別出來的動作標籤
          "OutputURL": "http://your bucket.oss-cn-shanghai.aliyuncs.com/output_0.mp4", // needExport = true 時才返回
          "MediaId": "MediaId11", // ExportAsNewMedia=true 時才返回
        }
      ]
    },
    {
      "Media": "MediaId2", //如果InputConfig裡輸入的是url，那麼這裡也是url
      "TimeRanges": [
        {
          "In": 2,
          "Out": 10,
          "Tags": ["奔跑","呼喊"],
          "OutputURL": "http://your bucket.oss-cn-******.aliyuncs.com/output_1.mp4" // needExport = true 時才返回
        },
        {
          "In": 40,
          "Out": 50,
          "OutputURL": "http://your bucket.oss-cn-******.aliyuncs.com/output_2.mp4" // needExport = true 時才返回
        }
      ]
    }
  ]
}