智能高光片段提取_智能媒体服务(IMS)-阿里云帮助中心

本文旨在介绍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 时才返回
        }
      ]
    }
  ]
}