文档中心

视频直播

高光剪辑

DescribeHighLightTaskByAccountID - 查询高光剪辑任务详情

调用 DescribeHighLightTaskByAccountID 接口，查询高光剪辑任务的详细信息，获取任务的生产结果，适用于任务管理和结果获取场景。

使用说明

您可通过返回参数 ClipUrl 或 HighlightUrl 获取高光视频对应的 vid，并在视频点播中通过 vid 查看对应视频。如果未返回 vid，通常表示视频源未匹配到算法所描述的高光场景，因此未生成对应的高光视频。

ClipUrl：获取高光片段的 vid，即从原始视频中提取的独立精彩片段的 vid。
HighlightUrl：获取高光混剪的 vid，即从多个高光片段中混剪生成的视频的 vid。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。

请求说明

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

调试

API Explorer

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

去调试

请求参数

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

Query

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

Body

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

TaskID String 是 5252cd****62e3ff 创建高光剪辑任务时返回的任务唯一标识符，用于后续查询任务状态或结果。

参数	类型	是否必选	示例值	描述
TaskID	String	是	`5252cd****62e3ff`	创建高光剪辑任务时返回的任务唯一标识符，用于后续查询任务状态或结果。
NeedResult	Boolean	否	`true`	是否返回高光剪辑生产结果，默认值为 `false`。支持的取值如下所示。 `true`：返回高光剪辑生产结果； `false`：不返回高光剪辑生产结果。

NeedResult

Boolean

否

true

是否返回高光剪辑生产结果，默认值为 false。支持的取值如下所示。

true：返回高光剪辑生产结果；
false：不返回高光剪辑生产结果。

返回参数

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

参数	类型	示例值	描述
Data	Object of Data	`-`	高光剪辑任务的详情数据，包含任务所属账号、任务参数配置、任务状态、任务唯一标识符以及生产结果列表等信息。

Data

参数	类型	示例值	描述
AccountID	String	`1000****1231`	高光剪辑任务所属的账号。
Rule	String	{"Name":"足球高光剪辑","Type":0,"Model":0,"SubModel":0,"Sources":[{"Path":"https://example.com/live/football.flv","SourceType":0}],"HLClipsParam":{"Enable":true,"OutputHLClips":true,"DisableTimestamp":false,"BufferDuration":0,"EncCodec":0,"VideoFormat":0},"HLMixParam":{"Enable":true,"CreateTimestamps":[20,40],"EncCodec":0,"VideoFormat":0},"LiveParam":{"TaskStartTime":"2023-01-01T08:40:00+08:00","TaskEndTime":"2023-01-01T10:40:00+08:00","StreamEndTime":120,"ClipsDuration":300},"VodParam":{"Space":"highlight","WorkflowID":"25524a2d*********891d7daf4b9"},"CallbackParam":{"CallbackType":0,"HttpParams":{"CallbackAdr":"http://example.com/callback"},"CallbackExtra":"extra"}}	创建高光剪辑任务时使用的参数配置，以 JSON 字符串格式传递。包含任务名称、类型、模型、输入源、高光剪辑参数、高光混剪参数、直播参数、点播参数和回调参数等详细信息。
Status	String	`done`	高光剪辑任务的状态，可能的取值如下所示。 `init`：任务初始化状态； `pending`：任务等待启动阶段； `prepare`：任务启动状态； `running`：任务生产状态； `prestop`：任务准备结束状态； `done`：任务完成状态； `error`：任务报错状态。
TaskID	String	`5252cd****62e3ff`	高光剪辑任务的唯一标识符，用于查询特定任务的详情信息。该标识符在创建任务时生成，通过此标识符可获取任务状态、生产结果等详细信息。
ProducedResults	Array of HighlightCallbackInfo	`-`	高光剪辑任务的生产结果列表，包含多个生产回调结果。每个结果包含以下信息： `code`：生产回调的状态码； `status`：生产状态码； `message`：生产描述信息； `exception`：异常信息； `TaskID`：高光剪辑任务的唯一标识符； `Output`：高光剪辑生产结果的详细信息； `ExtraData`：自定义的其他信息。

HighlightCallbackInfo

参数	类型	示例值	描述
code	Long	`200`	高光剪辑任务生产回调的状态码，用于标识生产过程的当前状态。 `100`：表示生产成功，任务将持续生产； `200`：表示生产完成，任务退出； `500`：表示当前生产回调失败，但任务仍会持续生产； `1000`：表示高光剪辑生产失败，任务停止。
status	String	`OK`	高光剪辑任务生产状态码，可能的取值如下所示。 `Continue`：表示生产成功，持续生产； `OK`：表示生产完成，任务退出； `Error`：表示当前生产回调失败，并且任务还会持续生产； `Fatal`：表示高光剪辑生产失败，任务停止。
exception	String	`receiver read failed`	高光剪辑任务生产过程中的异常信息，用于描述生产失败的具体原因。
message	String	`高光剪辑生产任务已完成`	高光剪辑任务生产过程中的描述信息。
TaskID	String	`6878c2c****0029c`	高光剪辑任务的唯一标识符，用于标识特定的高光剪辑生产任务。
Output	Object of HLOutputInfo	`-`	高光剪辑生产结果的详细信息，包含高光剪辑片段和高光混剪结果。
ExtraData	String	`extra data`	高光剪辑任务创建时的自定义其他信息，用于传递额外的任务相关数据。

HLOutputInfo

参数	类型	示例值	描述
HLClipsOutput	Object of HLSourceClips	`-`	高光剪辑任务生产结果中的高光片段结果，包含从原始视频中提取的高光片段信息。
HLMixOutput	Object of HLMixCuts	`-`	高光混剪结果，包含从多个高光片段中混剪生成的最终视频信息。

HLSourceClips

参数	类型	示例值	描述
HLSourceClips	Array of HLSourceClip	`-`	高光片段结果数组。

HLMixCuts

参数	类型	示例值	描述
HLMixCuts	Array of HLMixCut	`-`	高光混剪结果信息，包含从多个高光片段中混剪生成的最终视频的详细信息。

HLSourceClip

参数	类型	示例值	描述
SourceUrl	String	`http://example.com/original_video.mp4`	高光剪辑片段所属的原始视频 URL 地址，用于标识该片段是从哪个原始视频中提取的。
HLClips	Array of HLClip	`-`	高光剪辑所属视频 `SourceUrl` 的片段结果数组，包含从原始视频中提取的高光片段信息。

HLMixCut

参数	类型	示例值	描述
Index	Integer	`0`	高光剪辑混剪结果序号，用于标识混剪结果在结果列表中的顺序位置。
HighlightUrl	String	`v02014g10005d0****nog65ld3ofge8g`	高光剪辑混剪结果上传至视频点播（VOD）服务后的视频唯一标识符 `vid`（Video ID），用于唯一标识该视频文件。
Duration	Long	`10000`	高光剪辑混剪结果视频的时长，单位为毫秒。
HLClips	Array of HLClip	`-`	高光剪辑混剪结果视频对应的片段详情信息，包含从原始视频中提取的高光片段信息。

HLClip

参数	类型	示例值	描述
Index	Integer	`0`	高光剪辑片段所属原始视频的序号，用于标识该片段在原始视频中的顺序位置。
SourceUrl	String	`http://example.com/original_video.mp4`	高光剪辑片段所属的原始视频 URL 地址，用于标识该片段是从哪个原始视频中提取的。
ClipUrl	String	`v02014g10005d0sjdvn****ld3ofge8g`	高光剪辑片段上传至视频点播（VOD）服务后的视频唯一标识符 `vid`（Video ID），用于唯一标识该视频文件。
SStart	Long	`0`	高光剪辑片段相对所属原始视频的起始时间位置，单位为毫秒。
SEnd	Long	`10000`	高光剪辑片段相对所属原始视频的截止时间位置，单位为毫秒。
HLStart	Long	`0`	高光剪辑片段相对高光片段或者高光混剪的起始时间位置，单位为毫秒。
HLEnd	Long	`10000`	高光剪辑片段相对高光片段或者高光混剪的截止时间位置，单位为毫秒。
Duration	Long	`10000`	高光剪辑片段时长，单位为毫秒。
Score	Float	`0.5`	高光剪辑片段的高光分数，用于评估该片段在原始视频中的精彩程度。分数越高表示该片段越精彩，分数区间范围为 [0, 10]。
Label	Integer	`2`	高光片段的类型标识。当前仅用于体育足球场景，可能的取值如下所示。 `0`：无标签； `1`：背景； `2`：进球； `3`：角球； `4`：点球； `5`：黄牌； `6`：红牌； `7`：犯规； `8`：射门； `9`：任意球。
Confidence	Float	`0.95`	高光片段类型标识（即 `Label`）的置信度，用于表示该类型标识的可靠程度。仅适用于体育足球场景，取值范围为 [0,1]，数值越大表示置信度越高。
Description	String	`奥巴梅扬闪电破门！蝙蝠侠式庆祝点燃威斯特法伦`	高光片段内容描述。仅适用于体育足球。

请求示例

POST https://live.volcengineapi.com?Action=DescribeHighLightTaskByAccountID&Version=2023-01-01
{
    "TaskID": "5252cd****62e3ff",
    "NeedResult": true
}

返回示例

{
    "ResponseMetadata": {
        "Action": "DescribeHighLightTaskByAccountID",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "Data": {
            "ProducedResults": [
                {
                    "code": 200,
                    "Output": {
                        "HLMixOutput": {
                            "HLMixCuts": [
                                {
                                    "Index": 0,
                                    "HLClips": [
                                        {
                                            "SEnd": 43240,
                                            "HLEnd": 43000,
                                            "Index": 0,
                                            "Label": 2,
                                            "Score": 8.6,
                                            "SStart": 240,
                                            "ClipUrl": "v02014g10005d0sjdvn****ld3ofge8g",
                                            "HLStart": 0,
                                            "Duration": 43000,
                                            "SourceUrl": "https://example.com/live/football.flv",
                                            "Confidence": 0.95,
                                            "Description": "禁区内补射破门，主队率先取得进球"
                                        },
                                        {
                                            "SEnd": 92120,
                                            "HLEnd": 88080,
                                            "Index": 0,
                                            "Label": 8,
                                            "Score": 7.8,
                                            "SStart": 47040,
                                            "ClipUrl": "v02014g10005d0sjdvn****ld3ofge9h",
                                            "HLStart": 43000,
                                            "Duration": 45080,
                                            "SourceUrl": "https://example.com/live/football.flv",
                                            "Confidence": 0.88,
                                            "Description": "禁区外远射制造威胁，门将飞身扑救"
                                        }
                                    ],
                                    "Duration": 88080,
                                    "HighlightUrl": "v02014g10005d0****nog65ld3ofge8g"
                                }
                            ]
                        },
                        "HLClipsOutput": {
                            "HLSourceClips": [
                                {
                                    "HLClips": [
                                        {
                                            "SEnd": 43240,
                                            "HLEnd": 43000,
                                            "Index": 0,
                                            "Label": 2,
                                            "Score": 8.6,
                                            "SStart": 240,
                                            "ClipUrl": "v02014g10005d0sjdvn****ld3ofge8g",
                                            "HLStart": 0,
                                            "Duration": 43000,
                                            "SourceUrl": "https://example.com/live/football.flv",
                                            "Confidence": 0.95,
                                            "Description": "禁区内补射破门，主队率先取得进球"
                                        },
                                        {
                                            "SEnd": 92120,
                                            "HLEnd": 45080,
                                            "Index": 0,
                                            "Label": 8,
                                            "Score": 7.8,
                                            "SStart": 47040,
                                            "ClipUrl": "v02014g10005d0sjdvn****ld3ofge9h",
                                            "HLStart": 0,
                                            "Duration": 45080,
                                            "SourceUrl": "https://example.com/live/football.flv",
                                            "Confidence": 0.88,
                                            "Description": "禁区外远射制造威胁，门将飞身扑救"
                                        }
                                    ],
                                    "SourceUrl": "https://example.com/live/football.flv"
                                }
                            ]
                        }
                    },
                    "TaskID": "6878c2c****0029c",
                    "status": "OK",
                    "message": "高光剪辑生产任务已完成",
                    "ExtraData": "extra data",
                    "exception": ""
                }
            ],
            "AccountID": "1000****1231",
            "Rule": "{\"Name\":\"足球高光剪辑\",\"Type\":0,\"Model\":0,\"SubModel\":0,\"Sources\":[{\"Path\":\"https://example.com/live/football.flv\",\"SourceType\":0}],\"HLClipsParam\":{\"Enable\":true,\"OutputHLClips\":true,\"DisableTimestamp\":false,\"BufferDuration\":0,\"EncCodec\":0,\"VideoFormat\":0},\"HLMixParam\":{\"Enable\":true,\"CreateTimestamps\":[20,40],\"EncCodec\":0,\"VideoFormat\":0},\"LiveParam\":{\"TaskStartTime\":\"2023-01-01T08:40:00+08:00\",\"TaskEndTime\":\"2023-01-01T10:40:00+08:00\",\"StreamEndTime\":120,\"ClipsDuration\":300},\"VodParam\":{\"Space\":\"highlight\",\"WorkflowID\":\"25524a2d*********891d7daf4b9\"},\"CallbackParam\":{\"CallbackType\":0,\"HttpParams\":{\"CallbackAdr\":\"http://example.com/callback\"},\"CallbackExtra\":\"extra\"}}",
            "Status": "done",
            "TaskID": "5252cd****62e3ff"
        }
    }
}

错误码

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

状态码	错误码	错误信息	说明
500	InternalError	an internal error occurred, please contact the administrator.	出现内部错误，请联系技术支持。

最近更新时间：2026.09.11 12:00:32

这个页面对您有帮助吗？

有用

无用

视频直播

使用说明 #

注意事项 #

请求说明 #

调试 #

请求参数 #

Query #

Body #

返回参数 #

Data #

HighlightCallbackInfo #

HLOutputInfo #

HLSourceClips #

HLMixCuts #

HLSourceClip #

HLMixCut #

HLClip #

请求示例 #

返回示例 #

错误码 #