You need to enable JavaScript to run this app.
导航
视频直播
  • 文档首页
    • /视频直播/API 参考/高光智剪/DescribeHighLightTaskByAccountID - 查询高光剪辑任务详情
DescribeHighLightTaskByAccountID - 查询高光剪辑任务详情
最近更新时间：2025.06.17 15:16:35首次发布时间：2025.06.17 15:16:35
我的收藏
有用
有用
无用
无用

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

注意事项

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

请求说明

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

调试

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

请求参数

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

Query

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

Body

参数类型是否必选示例值描述
TaskIDString是5252cd****62e3ff创建高光剪辑任务时返回的任务唯一标识符，用于后续查询任务状态或结果。

NeedResult

Boolean

否

false

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

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

返回参数

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

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

Data

参数类型示例值描述
AccountIDString1000****1231高光剪辑任务所属的账号。
RuleString{"Name":"电商","Type":1,"Model":0,"SubModel":0,"Sources":[{"Path":"https://xxxx/test/test_hevc.flv","SourceType":0}],"HLClipsParam":{"Enable":true,"NumLimit":0,"DisableTimestamp":false,"OutputHLClips":true,"BufferDuration":0,"EncCodec":0,"VideoFormat":0},"HLMixParam":{"Enable":true,"DurationMax":0,"DurationMin":0,"NumLimit":1,"EncCodec":0,"VideoFormat":0,"Subtitle":true},"LiveParam":{"TaskStartTime":"2025-04-22T19:33:09+08:00","TaskEndTime":"","StreamEndTime":100,"ClipsDuration":300},"VodParam":{"Space":"test"},"SubtitleParam":null,"CallbackParam":{"CallbackType":0,"HttpParams":{"CallbackAdr":"http://10.37.**.**:10200/callback"},"CallbackExtra":"extra"}}创建高光剪辑任务时使用的参数配置，以 JSON 字符串格式传递。包含任务名称、类型、模型、输入源、高光剪辑参数、高光混剪参数、直播参数、点播参数、字幕参数和回调参数等详细信息。

Status

String

done

高光剪辑任务的状态，可能的取值如下所示。

  • init：任务初始化状态；
  • pending：任务等待启动阶段；
  • prepare：任务启动状态；
  • running：任务生产状态；
  • prestop：任务准备结束状态；
  • done：任务完成状态；
  • error：任务报错状态。
TaskIDString5252cd****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：表示高光剪辑生产失败，任务停止。
exceptionStringreceiver read failed高光剪辑任务生产过程中的异常信息，用于描述生产失败的具体原因。
messageString高光剪辑生产任务已完成高光剪辑任务生产过程中的描述信息。
TaskIDString6878c2c****0029c高光剪辑任务的唯一标识符，用于标识特定的高光剪辑生产任务。
OutputObject of HLOutputInfo-高光剪辑生产结果的详细信息，包含高光剪辑片段和高光混剪结果。
ExtraDataStringextra data高光剪辑任务创建时的自定义其他信息，用于传递额外的任务相关数据。

HLOutputInfo

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

HLSourceClips

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

HLMixCuts

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

HLSourceClip

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

HLMixCut

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

HLClip

参数类型示例值描述
IndexInteger0高光剪辑片段所属原始视频的序号，用于标识该片段在原始视频中的顺序位置。
SourceUrlStringhttp://example.com/original_video.mp4高光剪辑片段所属的原始视频 URL 地址，用于标识该片段是从哪个原始视频中提取的。
ClipUrlStringv02014g10005d0sjdvn****ld3ofge8g高光剪辑片段上传至视频点播（VOD）服务后的视频唯一标识符 vid（Video ID），用于唯一标识该视频文件。
SStartLong0高光剪辑片段相对所属原始视频的起始时间位置，单位为毫秒。
SEndLong10000高光剪辑片段相对所属原始视频的截止时间位置，单位为毫秒。
HLStartLong0高光剪辑片段相对高光片段或者高光混剪的起始时间位置，单位为毫秒。
HLEndLong10000高光剪辑片段相对高光片段或者高光混剪的截止时间位置，单位为毫秒。
DurationLong10000高光剪辑片段时长，单位为毫秒。
ScoreFloat0.5高光剪辑片段的高光分数，用于评估该片段在原始视频中的精彩程度。分数越高表示该片段越精彩，分数区间范围为 [0, 10]。

Label

Integer

2

高光片段的类型标识。当前仅用于体育足球场景，可能的取值如下所示。

  • 0：无标签；
  • 1：背景；
  • 2：进球；
  • 3：角球；
  • 4：点球；
  • 5：黄牌；
  • 6：红牌；
  • 7：犯规；
  • 8：射门；
  • 9：任意球。
ConfidenceFloat0.95高光片段类型标识（即 Label）的置信度，用于表示该类型标识的可靠程度。仅适用于体育足球场景，取值范围为 [0,1]，数值越大表示置信度越高。
DescriptionString奥巴梅扬闪电破门！蝙蝠侠式庆祝点燃威斯特法伦高光片段内容描述。仅适用于体育足球。
SellPointsResArray of SellPointsRes-高光剪辑片段的卖点信息结果。

SellPointsRes

参数类型示例值描述

Status

String

ok

卖点添加的状态，取值如下所示。

  • ok：卖点添加成功；
  • fail：卖点添加失败。
MessageString添加卖点超时卖点添加过程中的错误信息，用于描述添加卖点失败的具体原因。
StartTimeLong0卖点相对于混剪结果的开始时间，单位为毫秒。
EndTimeLong10000卖点相对于混剪结果的结束时间，单位为毫秒。
SellPointsString苹果超甜视频卖点信息，用于描述高光剪辑片段中的关键亮点内容。
EffectTypeStringdefault使用的卖点效果模版，当前仅支持 default 值。

请求示例

POST https://live.volcengineapi.com?Action=DescribeHighLightTaskByAccountID&Version=2023-01-01
{
    "TaskID": "a2a0c5d****6e5ba",
    "NeedResult": true
}

返回示例

{
    "ResponseMetadata": {
        "RequestID": "20250610120109E27F99CDC0AD4C85211E"
    },
    "Result": {
        "Code": 0,
        "Message": "success",
        "Data": {
            "AccountID": "12300****",
            "LastOperationErrCode": 0,
            "LastOperationErrMsg": "",
            "LastOperationIndex": 1,
            "LastSuccessOperationIndex": 1,
            "MesosID": "live_test_****f0fe_000000000104408",
            "ProducedResults": [
                {
                    "ExtraData": "test extra data",
                    "Output": {
                        "HLClipsOutput": {
                            "HLSourceClips": [
                                {
                                    "HLClips": [
                                        {
                                            "ClipUrl": "v02cb9g10004d13****ljhtc4aveg6rg",
                                            "Confidence": 1,
                                            "Description": "禁区外任意球引发第二张黄牌！贝林厄姆危险区域犯规",
                                            "Duration": 43000,
                                            "HLEnd": 43028,
                                            "HLStart": 0,
                                            "Index": 0,
                                            "Label": 5,
                                            "SEnd": 43240,
                                            "SStart": 240,
                                            "Score": 0,
                                            "SellPointsRes": [],
                                            "SourceUrl": "https://test/test.mp4"
                                        }
                                    ],
                                    "SourceUrl": "https://test/test.mp4"
                                }
                            ]
                        },
                        "HLMixOutput": {
                            "HLMixCuts": []
                        }
                    },
                    "TaskID": "a2a0c5d****6e5ba",
                    "code": 200,
                    "exception": "",
                    "message": "",
                    "status": "OK"
                }
            ],
            "Rule": "{\"Name\":\"测试\",\"Type\":1,\"Model\":0,\"SubModel\":0,\"Sources\":[{\"Path\":\"https://test/test.mp4\",\"SourceType\":0}],\"HLClipsParam\":{\"Enable\":true,\"NumLimit\":0,\"DisableTimestamp\":false,\"OutputHLClips\":true,\"BufferDuration\":0,\"EncCodec\":0,\"VideoFormat\":0},\"HLMixParam\":{\"Enable\":false,\"DurationMax\":0,\"DurationMin\":0,\"NumLimit\":0,\"CreateTimestamps\":null,\"EncCodec\":0,\"VideoFormat\":0,\"Subtitle\":false,\"SellPointSticker\":false},\"HLNarrateParam\":null,\"LiveParam\":{\"TaskStartTime\":\"2025-06-10T10:29:33+08:00\",\"TaskEndTime\":\"\",\"StreamEndTime\":0,\"ClipsDuration\":0},\"VodParam\":{\"Space\":\"zzt-test\",\"WorkflowID\":\"b9e09e0f62d4484c928d38de1a26a2e0\"},\"SubtitleParam\":null,\"CallbackParam\":{\"CallbackType\":100,\"MqParams\":{\"Type\":\"kafka\",\"Topic\":\"fcdn_highlight\",\"Cluster\":\"bmq_common4\"},\"HttpParams\":{\"CallbackAdr\":\"http://fdbd:dc02:2b:526::20:10200/callback\"},\"CallbackExtra\":\"test extra data\"},\"SellPointParam\":null,\"NumLimit\":0,\"ExtraData\":\"\"}",
            "Status": "done",
            "TaskErrCode": 2,
            "TaskErrMsg": "",
            "TaskErrSrcIDs": null,
            "TaskID": "a2a0c5d****6e5ba"
        }
    }
}

错误码

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

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