CreateHighLightTask - 创建高光剪辑任务--视频直播-火山引擎

文档中心

导航

CreateHighLightTask - 创建高光剪辑任务

最近更新时间：2025.06.18 10:49:16首次发布时间：2025.03.04 13:55:44

调用 CreateHighLightTask 接口，创建高光智能剪辑任务，对公网可访问的点播视频或直播流进行高光片段提取和混剪，并上传至指定空间，可根据不同的算法模型（如体育足球、电商）自动生成高光片段或高光混剪视频。接口提供丰富的配置选项，包括输出格式、冗余时间、字幕设置等，适用于体育赛事、节目剧集、电商直播等场景的内容智能剪辑需求。

注意事项

前提条件：需要将高光素材存放在点播平台时，请先开通点播服务，参考空间管理创建空间。同时需点击链接，确保完成对点播空间的跨服务授权。
请求频率：单用户请求频率限制为 10 次/秒。
费用和限制：该功能当前处于邀测阶段，暂不计费，仅授权账户可用。若需获取授权，请联系技术支持。
回调消息：调用本接口开启回调通知后，系统将向您发送回调消息。详细参数说明请参见高光剪辑回调消息说明。

请求说明

请求方式：POST
请求地址：https://live.volcengineapi.com?Action=CreateHighLightTask&Version=2023-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateHighLightTask`	接口名称。当前 API 的名称为 `CreateHighLightTask`。
Version	String	是	`2023-01-01`	接口版本。当前 API 的版本为 `2023-01-01`。

Body

参数	类型	是否必选	示例值	描述
Name	String	是	`决赛高光`	任务名称，长度限制 1-256 个字符。
Type	Integer	是	`0`	数据源类型。缺省情况下，取值为 `0`。 `0`：表示直播流。 `1`：表示点播视频。
Model	Integer	是	`0`	算法模型类型，缺省情况下取值为 `0`。 `0`：体育足球。 `1`：文娱短剧，适用于视频源类型为点播视频的场景，即 `"Type":1`。 `2`：电商，支持视频源类型为点播视频的场景，即 `"Type":1`。其他场景的支持情况，请关注文档更新。
SubModel	Integer	否	`0`	算法模型的子类型，根据任务类型和场景进行选择，具体取值如下所示。体育足球：`0` 表示默认类型剪辑，主要适用于含解说赛事的高光提取。文娱短剧：`0` 表示默认类型剪辑。电商：`0` 表示默认类型剪辑，主要适用于即时零售场景的高光提取；`1` 表示按转场分镜剪辑，主要适用于按转场切分视频以获取原始素材的场景。默认值为 `0`。
Sources	Array of Sources	是	`-`	数据源类型和地址。
HLClipsParam	Object of HLClipsParam	否	`-`	高光片段的输出及相关参数设置。说明 `HLClipsParam` 和 `HLMixParam` 至少需配置一个，支持同时启用。
HLMixParam	Object of HLMixParam	否	`-`	高光混剪的输出及相关参数设置。说明 `HLClipsParam` 和 `HLMixParam` 至少需配置一个，支持同时启用。
LiveParam	Object of LiveParam	否	`-`	直播流剪辑任务的配置参数，仅在数据源类型为直播（即 `"Type":0`）时生效。
VodParam	Object of VodParam	否	`-`	高光视频上传至视频点播的相关配置。
CallbackParam	Object of CallbackParam	否	`-`	回调通知参数配置。
SubtitleParam	Object of SubtitleParam	否	`-`	音频生成字幕的相关配置，包括字幕的位置、描边和字体样式。
SellPointParam	Object of SellPointParam	否	`-`	电商场景下使用的卖点效果配置。

Sources

参数类型是否必选示例值描述

SourceType Integer 是 0 视频源类型。支持取值 0，表示在线流媒体源，即直接使用 HTTP/HTTPS/FLV/HLS/RTMP 等协议的视频流地址作为数据源。

参数	类型	是否必选	示例值	描述
SourceType	Integer	是	`0`	视频源类型。支持取值 `0`，表示在线流媒体源，即直接使用 HTTP/HTTPS/FLV/HLS/RTMP 等协议的视频流地址作为数据源。
Path	String	是	`http://example.com/live/stream.flv`	视频源地址，需为有效的直播流 URL 或点播视频 URL。直播流 URL：支持 FLV、HLS、RTMP 、RTM 协议拉流地址。点播视频 URL：支持 MP4、HLS、FLV 格式点播地址。说明需确保地址在任务执行期间始终有效，并且能够被公网访问。

Path

String

是

http://example.com/live/stream.flv

视频源地址，需为有效的直播流 URL 或点播视频 URL。

直播流 URL：支持 FLV、HLS、RTMP 、RTM 协议拉流地址。
点播视频 URL：支持 MP4、HLS、FLV 格式点播地址。

说明

需确保地址在任务执行期间始终有效，并且能够被公网访问。

HLClipsParam

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	`false`	是否启用高光片段提取。默认值为 `false`。 `true`：开启。 `false`：关闭。
OutputHLClips	Boolean	否	`false`	是否生成高光片段视频素材，仅当 `HLClipsParam.Enable` 为 `true` 时生效，默认值为 `false`。说明若 `Enable` 为 `true`，且 `OutputHLClips` 为 `false`，则回调仅包含高光片段信息，您可以根据片段信息，自行剪辑视频素材。
NumLimit	Integer	否	`5`	累计生成高光片段数量上限，仅针对数据源类型为视频时生效。默认值为 `0`，表示不限制数量。
DisableTimestamp	Boolean	否	`false`	是否禁止高光片段时间戳返回，默认为 `false`。 `true`：禁止返回时间戳； `false`：允许返回时间戳。
BufferDuration	Integer	否	`10`	针对算法检测出的高光片段前后分别增加的冗余时间，单位为秒，默认值为 `0`，取值范围为 `[0,60]`。适用于对算法检出的高光片段内容信任度不高，期望获取更多冗余素材，以便自行剪辑的场景。
EncCodec	Integer	否	`1`	高光片段的编码格式，默认值为 `0`。 `0`：H264； `1`：H265。
VideoFormat	Integer	否	`1`	高光片段的视频封装格式，默认值为 `0`。取值如下所示： `0`：MP4 格式； `1`：HLS 流媒体格式（包含 M3U8 索引文件和 TS 分片文件）； `2`：FLV 流媒体格式。

HLMixParam

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	`false`	是否启用高光混剪功能。默认值为 `false`。 `true`：开启。 `false`：关闭。
DurationMax	Integer	否	`210`	高光混剪时长上限，单位为秒，缺省情况下默认值为 `210`。说明该参数仅在算法模型为文娱短剧（即 `"Model":1`）时生效。当 `DurationMax` 和 `DurationMin` 取值相同时，则该时长为高光混剪的固定时长。 `DurationMax` 取值大于等于 `DurationMin` 取值。
DurationMin	Integer	否	`180`	高光混剪时长下限，单位为秒，缺省情况下默认值为 `180`。说明该参数仅在算法模型为文娱短剧（即 `"Model":1`）时生效。当 `DurationMax` 和 `DurationMin` 取值相同时，则该时长为高光混剪的固定时长。 `DurationMin` 取值小于等于 `DurationMax` 取值。
NumLimit	Integer	否	`3`	累计生成高光混剪数量上限，默认值为 `1`，取值范围为 `[1,100]`。说明该参数仅在算法模型为文娱短剧（即 `"Model":1`）时生效。
CreateTimestamps	Array of Integer	否	`[20,40]`	生成并返回高光混剪的时间点，支持设置多个时间节点。该时间相对于任务开始时间 `TaskStartTime` 计算，单位为分钟，取值范围为 [5,1440]。说明该参数仅在数据源类型为直播（即 `"Type":0`）时生效，缺省情况下，默认在任务结束后生成并返回高光混剪。
EncCodec	Integer	否	`1`	高光混剪的编码格式，默认值为 `0`。 `0`：H264； `1`：H265。
VideoFormat	Integer	否	`1`	高光混剪的视频封装格式，默认值为 `0`。取值如下所示： `0`：MP4 格式； `1`：HLS 流媒体格式（包含 M3U8 索引文件和 TS 分片文件）； `2`：FLV 流媒体格式。
SellPointSticker	Boolean	否	`true`	是否开启卖点贴纸功能，默认值为 `false`。 `true`：开启。 `false`：关闭。
Subtitle	Boolean	否	`false`	是否开启声音生成字幕，默认值为 `false`。 `true`：开启； `false`：关闭。

LiveParam

参数	类型	是否必选	示例值	描述
TaskStartTime	String	否	`2023-01-01T08:00:00+08:00`	指定高光提取任务的开始时间，RFC3339 格式的时间戳，精度为秒。默认为空，表示立即开始。
TaskEndTime	String	否	`2023-01-01T09:00:00+08:00`	指定高光提取任务的结束时间，RFC3339 格式的时间戳，精度为秒。默认为空，表示高光提取任务执行到直播流结束。
StreamEndTime	Integer	否	`120`	用于判断直播流的断流时长。当断流时间超过该参数值时，直播流被视为结束。单位为秒，默认值为 `120`，取值范围为 [60,900]。说明该参数仅在 `TaskEndTime` 为空时生效。如果 `TaskEndTime` 设置了具体值，则任务会按照 `TaskEndTime` 结束，而不会因断流提前终止，即使发生断流，任务仍将持续运行直至 `TaskEndTime` 到达。
ClipsDuration	Integer	否	`300`	用于定义直播流剪辑送检的切片时长，即提供给模型进行剪辑的素材时长。单位为秒，默认值为 `300`，取值范围为 [60,10800]。

VodParam

参数	类型	是否必选	示例值	描述
Space	String	是	`highlight`	视频点播空间名称。可登录视频点播控制台查询。
WorkflowID	String	否	`25524a2d*********891d7daf4b9`	视频点播工作流模板 ID，对于存储在点播的高光视频，会使用该工作流模版对视频进行处理，可登录视频点播控制台获取工作流模板 ID，默认为空。

CallbackParam

参数	类型	是否必选	示例值	描述
CallbackType	Integer	否	`0`	回调类型。支持取值 `0`，表示 HTTP 回调。
HttpParams	Object of HttpParams	否	`{"CallbackAdr":"http://example.com/callback"}`	HTTP 回调相关参数配置，包含回调地址 `CallbackAdr`。
CallbackExtra	String	否	`extra_data`	自定义参数，通过回调直接透传，便于您自定义标识，默认为空。

SubtitleParam

参数	类型	是否必选	示例值	描述
Position	Object of Position	否	`{"MarginTb":0.15,"MarginLr":0.05}`	用于设置字幕的位置，通过调整字幕距离画面底部的边距和左右两侧的边距来指定。
Border	Object of Border	否	`{"W":2,"Color":"0x000000"}`	字幕描边的配置，包括描边的宽度和颜色。
Font	Object of Font	否	`{"Font":"songticu","FontSize":55,"FontColor":"0xFFFFFFFF"}`	用于设置字幕的字体样式，包括字体类型、字号和字体颜色。

SellPointParam

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
ECommerceInfo	JSON Map	是	`{"http://test/test.mp4":{"ProductInfo":[{"Desc":"金枕榴莲"}]}}`	电商场景下使用的卖点效果配置，为 JSON Map 格式。 Key：输入视频的链接或索引 Value：对应视频的商品简述，用于辅助生成卖点信息 `ProductInfo`
EffectType	String	否	`default`	使用的卖点效果模版，支持的取值为 `default`。

ECommerceInfo

JSON Map

是

{"http://test/test.mp4":{"ProductInfo":[{"Desc":"金枕榴莲"}]}}

电商场景下使用的卖点效果配置，为 JSON Map 格式。

Key：输入视频的链接或索引
Value：对应视频的商品简述，用于辅助生成卖点信息 ProductInfo

EffectType String 否 default 使用的卖点效果模版，支持的取值为 default。

HttpParams

参数	类型	是否必选	示例值	描述
CallbackAdr	String	是	`http://example.com/callback`	HTTP 回调地址。

Position

参数	类型	是否必选	示例值	描述
MarginTb	Float	否	`0.15`	字幕距离画面底部的边距与画面高度的占比，使用归一化百分表示，取值范围为 [0,0.5]。
MarginLr	Float	否	`0.05`	字幕距离画面两侧的边距与画面宽度的占比，使用归一化百分表示，取值范围为 [0,0.2]。

Border

参数类型是否必选示例值描述

W Integer 否 2 字幕描边的宽度，单位为像素，默认值为 2。

参数	类型	是否必选	示例值	描述
W	Integer	否	`2`	字幕描边的宽度，单位为像素，默认值为 `2`。
Color	String	否	`0x000000`	定义字幕的描边颜色，支持以下几种方法进行定义。默认为黑色。以 `0x` 或 `#` 开头，后面跟着十六进制颜色 RGB 值，再跟着 `@+` 十六进制/百分比来表示的透明度值。使用前端框架 FFmpeg 规定的颜色关键字。

Color

String

否

0x000000

定义字幕的描边颜色，支持以下几种方法进行定义。默认为黑色。

以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+ 十六进制/百分比来表示的透明度值。
使用前端框架 FFmpeg 规定的颜色关键字。

Font

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
Font	String	否	`songticu`	字幕的字体类型，支持多种字体选择，默认值为 `songticu`（宋体粗）。支持的字体如下所示。 `songticu`：宋体粗； `songtixi`：宋体细； `arial`：Arial； `heitifan`：黑体繁； `inter`：Inter； `kaiti`：楷体； `montserrat`：Montserrat； `notosans`：Noto Sans； `notosans_ar`：Noto Sans 阿拉伯文； `notosans_ja`：Noto Sans 日文； `notosans_ko`：Noto Sans 韩文； `notosans_th`：Noto Sans 泰文； `opposans`：Opposans； `roboto`：Roboto； `simhei`：黑体； `siyuanheiti`：思源黑体； `siyuansongti`：思源宋体。
FontSize	Integer	否	`55`	字幕的字号，单位为像素，默认为 `55`，取值范围为 [40,60]。
FontColor	String	否	`0xFFFFFFFF`	定义字幕的字体颜色，支持以下几种方法进行定义。默认为白色。以 `0x` 或 `#` 开头，后面跟着十六进制颜色 RGB 值，再跟着 `@+` 十六进制/百分比来表示的透明度值。例如，设置 RGB 值为 `FF0000`，透明度为 `5%` 的颜色时，可传入 `0xFF0000@0x80`、`0xFF0000@0.5`、`#FF0000@0x80` 或 `#FF0000@0.5`。使用前端框架 FFmpeg 规定的颜色关键字。例如，`AliceBlue` 表示 `0xF0F8FF`、`AntiqueWhite` 表示 `0xFAEBD7`、`Black` 表示 `0x000000` 等。

Font

String

否

songticu

字幕的字体类型，支持多种字体选择，默认值为 songticu（宋体粗）。支持的字体如下所示。

songticu：宋体粗；
songtixi：宋体细；
arial：Arial；
heitifan：黑体繁；
inter：Inter；
kaiti：楷体；
montserrat：Montserrat；
notosans：Noto Sans；
notosans_ar：Noto Sans 阿拉伯文；
notosans_ja：Noto Sans 日文；
notosans_ko：Noto Sans 韩文；
notosans_th：Noto Sans 泰文；
opposans：Opposans；
roboto：Roboto；
simhei：黑体；
siyuanheiti：思源黑体；
siyuansongti：思源宋体。

FontSize Integer 否 55 字幕的字号，单位为像素，默认为 55，取值范围为 [40,60]。

FontColor

String

否

0xFFFFFFFF

定义字幕的字体颜色，支持以下几种方法进行定义。默认为白色。

以 0x 或 # 开头，后面跟着十六进制颜色 RGB 值，再跟着 @+ 十六进制/百分比来表示的透明度值。例如，设置 RGB 值为 FF0000，透明度为 5% 的颜色时，可传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。
使用前端框架 FFmpeg 规定的颜色关键字。例如，AliceBlue 表示 0xF0F8FF、AntiqueWhite 表示 0xFAEBD7、Black 表示 0x000000 等。

ECommerceInfo

参数	类型	是否必选	示例值	描述
ProductInfo	Array of ProductInfo	否	`[{"Desc":"金枕榴莲"}]`	商品简述，用于辅助生成卖点信息。

ProductInfo

参数	类型	是否必选	示例值	描述
Desc	String	是	`金枕榴莲`	商品简述，用于辅助生成卖点信息。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见返回结构。

参数	类型	示例值	描述
Data	Object of Data	`-`	包含任务相关数据的对象，其中 `TaskID` 字段表示任务的唯一标识符。

Data

参数	类型	示例值	描述
TaskID	String	`83d734****d0c077`	任务 ID。

请求示例

创建直播高光剪辑任务实例

POST https://live.volcengineapi.com?Action=CreateHighLightTask&Version=2023-01-01
{
    "Name": "足球高光剪辑",
    "Type": 0,
    "Model": 0,
    "Sources": [
        {
            "Path": "http://example.com/live/stream.flv",
            "SourceType": 0
        }
    ],
    "HLMixParam": {
        "Enable": true,
        "CreateTimestamps": [
            2,
            4,
            6
        ]
    },
    "HLClipsParam": {
        "Enable": true,
        "OutputHLClips": true
    },
    "LiveParam": {
        "TaskStartTime": "2023-01-01T08:40:00+08:00",
        "TaskEndTime": "2023-01-01T10:40:00+08:00"
    },
    "VodParam": {
        "Space": "HighLight"
    },
    "CallbackParam": {
        "CallbackType": 0,
        "HttpParams": {
            "CallbackAdr": "http://example.com/callback"
        },
        "CallbackExtra": "extra data"
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestID": "202502281605280C****E3D60D7A21CEAE"
    },
    "Result": {
        "Code": 0,
        "Message": "success",
        "Data": {
            "TaskID": "dd311d****2d91e3"
        }
    }
}

错误码

下表仅列出本接口特有的错误码。更多信息请参见公共错误码获取详细信息。

状态码	错误码	错误信息	说明
400	InvalidParam.BindError	Request parameter error, please check input data	参数未通过校验，请检查参数类型是否正确。
400	InvalidParam.Length	%s should not be longer than %d	参数长度错误，请检查错误消息中指定参数的长度是否超过限制。
400	InvalidParam.TimeLogic	startTime later than endTime, etc.	传入的时间参数不符合时间逻辑，请检查是否存在以下问题。开始时间晚于结束时间或过期时间早于当前时间。