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

文档中心

立即注册

导航

创建高光剪辑任务

最近更新时间：2025.03.04 13:55:44首次发布时间：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`。
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	是	`-`	回调通知参数。

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`，则回调仅包含高光片段信息，您可以根据片段信息，自行剪辑视频素材。

Enable

Boolean

否

false

是否启用高光片段提取。默认值为 false。

true：开启。
false：关闭。

OutputHLClips

Boolean

否

false

是否生成高光片段视频素材，仅当 HLClipsParam.Enable 为 true 时生效，默认值为 false。

说明

若 Enable 为 true，且 OutputHLClips 为 false，则回调仅包含高光片段信息，您可以根据片段信息，自行剪辑视频素材。

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	否	`1`	累计生成高光混剪数量上限，默认值为 `1`，取值范围为 [1,100]。说明该参数仅在算法模型为文娱短剧（即 `"Model":1`）时生效。
CreateTimestamps	Array of Integer	否	`[20,40]`	生成并返回高光混剪的时间点，支持设置多个时间节点。该时间相对于任务开始时间 `TaskStartTime` 计算，单位为分钟，取值范围为 [5,1440]。说明该参数仅在数据源类型为直播（即 `"Type":0`）时生效，缺省情况下，默认在任务结束后生成并返回高光混剪。

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`	视频点播（VOD）空间名称。可登录视频点播控制台查询。

CallbackParam

参数	类型	是否必选	示例值	描述
CallbackType	Integer	是	`1`	回调类型。当前仅支持 `1`，表示 HTTP 回调。
HttpParams	Object of HttpParams	是	`-`	HTTP 回调参数。
CallbackExtra	String	否	`extra_data`	自定义参数，通过回调直接透传，便于您自定义标识，默认为空。

HttpParams

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

返回参数

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

参数	类型	示例值	描述
Data	Object of Data	`-`	参数数据。

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.	传入的时间参数不符合时间逻辑，请检查是否存在以下问题。开始时间晚于结束时间或过期时间早于当前时间。