logologo
logo
活动资讯
NEW
产品
解决方案
客户价值
文档
支持与帮助
控制台
登录
售前咨询
点播云
产品简介
购买指南
快速入门
控制台指南
服务端API
API概览
调用方式
媒资上传
媒资管理
媒体处理
事件通知
回调概述
点播CDN
数据统计
空间管理
回调配置
错误码
SDK文档
相关协议
文档中心
服务端API事件通知回调概述

回调概述

更新时间：2023-12-01 21:29:15

消息通过 HTTP（含HTTPS） POST 的方式投递，当被调用服务的 HTTP 响应返回 200 时，快手会判断该消息投递成功。如果遇到非 200 的响应，则认为消息投递失败。

1. 回调内容公共字段

参数名称

类型

描述

RequestId

String

请求Id

EventType

String

事件类型，系统规定参数

MediaId

String

快手点播媒资Id

CallbackArgs

String

客户额外信息。回调时会透传返回，最大长度512字节

ErrorCode

String

作业错误码，任务执行正常时，该字段为空，执行失败时表示具体的错误code

ErrorMessage

String

作业错误信息，任务执行正常时，该字段为空，执行失败时表示具体的错误信息


2. 事件列表

客户需要部署回调事件的接收服务，主要处理：URL拉取上传完成事件、转码完成事件、源文件分析完成事件、任务流完成事件

  • 对于URL拉取上传完成事件，成功则可以忽略，失败时需要做相应处理（比如源片URL过期无法下载则需要重新签名和发起上传）
  • 转码完成事件，相关信息需要入库，为后续播放做准备。


2.1 URL拉取上传完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为：FetchUploadEvent

SourceURL

String

源片URL地址


回调示例

拉取上传成功
{
   "EventType":"FetchUploadEvent",
   "RequestId":"CixgpmANmJgAAAAAAAAAAA",
   "MediaId":"bfffea373bdbff1c",
   "SourceURL":"http://xxx.com/423839716c7238fe-6e56abefe0f4ef25fe8e1e1b5d9d0a58.mp4",
   "MediaKey": "1441787166381158400/33122341166381158112.mp4",
   "CallbackArgs": "",
   "ErrorMessage":"",
   "ErrorCode":""
}
拉取上传失败
{
   "EventType":"FetchUploadEvent",
   "RequestId":"CixgpmANmJgAAAAAAAAAAA",
   "MediaId":"bfffea373bdbff1c",
   "SourceURL":"http://xxx.com/423839716c7238fe-6e56abefe0f4ef25fe8e1e1b5d9d0a58.mp4",
   "MediaKey":"1441787166381158400/33122341166381158112.mp4",
   "CallbackArgs": "",
   "ErrorMessage":"Fetch upload failed, please check URL",
   "ErrorCode":"InvalidArgument"
}


2.2 转码完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为VideoTranscodeEvent

HdrType

String

Hdr类型。枚举值：

SDR

HDR10

HDR10+

Dolby Vision

HLG

SDR+

URLPath

String

转码生成的相对路径（不包含CDN域名）格式为{PrimaryKey}/{JobId}-{Definition}，客户根据{Domain}/{URLPath}拼接完整的URL

FileSize

Long

文件大小，单位：Byte

Height

Integer

视频高度，单位：px

Width

Integer

视频宽度，单位：px

Bitrate

Integer

视频流码率，单位：Kbps

Duration

Double

视频时长，单位：s

Fps

Double

视频流帧率，每秒包含帧数

TranscodeTemplateId

String

转码模板Id

Format

String

视频流格式

mp4

m3u8

VideoMaxBitrate

Integer

视频码率峰值，单位：Kbps

VideoStreams

Array of VideoStream

详见VideoStream

AudioStreams

Array of AudioStream

详见AudioStream


VideoStream

参数名称

类型

描述

Duration

Double

视频流长度，单位：s

Width

Integer

视频流宽度，单位：px

Height

Integer

视频流高度，单位：px

Fps

Double

视频流帧率，每秒包含帧数

Bitrate

Integer

视频流码率，单位：Kbps


AudioStream

参数名称

类型

描述

Duration

Double

音频流长度，单位：s

Bitrate

Integer

音频流码率，单位：Kbps

Channels

Integer

声道数

SampleRate

Integer

采样率，单位：Hz


回调示例

{
   "EventType":"VideoTranscodeEvent",
   "HdrType":"sdr",
   "URLPath":"1441787166381158400/33122341166381158112-hd.mp4",
   "FileSize":61747,
   "Height":852,
   "Bitrate":443,
   "Fps":25.0,
   "TranscodeTemplateId":"mp4_480p",
   "Format":"mp4",
   "Duration":1.1,
   "JobId": "1441787166381158400-312312124-1234124213"
   "Width":480,
   "VideoMaxBitrate":900,
   "VideoStreams":[
       {
           "Duration":1.1,
           "Width":480,
           "Height":852,
           "Fps":25,
           "Bitrate":419
       }
   ],
   "AudioStreams":[
       {
           "Duration":1.1,
           "Bitrate":50,
           "Channels":2,
           "SampleRate":44100
       }
   ]
   "RequestId":"CixgpmANnTwAAAAAAAAAAA",
   "CallbackArgs": "",
   "MediaId":"649c40c50660f1dd",
   "ErrorCode":"",
   "ErrorMessage":""
}


2.3 源文件分析完成事件

上传完成后会对源文件进行meta解析并发送回调消息

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为VideoMetaEvent

FileSize

Long

文件大小，单位：Byte

Height

Integer

视频高度，单位：px

Width

Integer

视频宽度，单位：px

Bitrate

Integer

视频流码率，单位：Kbps

Fps

Double

视频流帧率，每秒包含帧数

Duration

Double

视频时长，单位：s

Format

String

视频流格式

mp4

m3u8


回调示例

{
   "EventType":"VideoMetaEvent",
   "Duration":9.2,
   "Format":"mp4",
   "Width":960,
   "Height":540,
   "Bitrate":888,
   "FileSize":1021342,
   "Fps":30.0,
   "RequestId":"CixgpmANmJgAAAAAAAAAAA",
   "MediaId":"bfffea373bdbff1c",
   "CallbackArgs": "",
   "ErrorMessage":"",
   "ErrorCode":""
}



2.4 任务流完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为ProcessingFlowEvent

WorkflowId

String

任务流模板Id


回调示例

成功回调
{
   "EventType":"ProcessingFlowEvent",
   "RequestId":"CixgpmANnhsAAAAAAAAAAA",
   "WorkflowId":"demo_flow_audio",
   "MediaId":"a34aef9d0505843c",
   "CallbackArgs": "",
   "ErrorMessage":"",
   "ErrorCode":""
}
失败回调
{
   "EventType":"ProcessingFlowEvent",
   "RequestId":"CixgpmANnhsAAAAAAAAAAA",
   "WorkflowId":"xxx",
   "MediaId":"a34aef9d0505843c",
   "CallbackArgs": "",
   "ErrorCode":"InvalidArgument",
   "ErrorMessage":"Workflow: xxx not exist"
}



2.5 指定时间点截图完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为SnapshotByTimeOffsetEvent

FileSize

Long

文件大小，单位：Byte

Height

Integer

视频封面高度，单位：px

Width

Integer

视频封面宽度，单位：px

Format

String

封面文件格式

SnapshotByTimeOffsetTemplateId

String

封面模板Id

URLPath

String

封面文件相对路径

TaskId

String

任务Id

回调示例

{
    "Format":"webp",
    "FileSize":6348,
    "URLPath":"98c9eddde0698c7e-eb131139d2ceb5a4d0a98e66f4618a9b-cover-intelligent1.webp",
    "SnapshotByTimeOffsetTemplateId":"xxx",
    "CallbackArgs":"test1001",
    "Height":600,
    "Width":1280,
    "MediaId":"98c9eddde0698c7e",
    "RequestId":"ChzojWQ96RUAAAAAAYqe-g",
    "PrimaryKey":"test1001",
    "EventType":"SnapshotByTimeOffsetEvent",
    "ErrorMessage":"",
    "ErrorCode":"",
  	"TaskId": "xxx"
}



2.6 雪碧图完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为ImageSpriteEvent

URLPath

String

雪碧图生成的vtt文件

ImageSpriteTemplateId

String

雪碧图模板Id

TaskId

String

任务Id

回调示例

{
    "URLPath":"98c9eddde0698c7e-41e80c5bf1792c60551be5f5d7444993-video-sprite1.vtt",
    "CallbackArgs":"test1001",
    "MediaId":"98c9eddde0698c7e",
    "RequestId":"ChzojWQ96RUAAAAAAYqe-g",
    "PrimaryKey":"test1001",
    "EventType":"ImageSpriteEvent",
    "ImageSpriteTemplateId":"xxx",
    "ErrorMessage":"",
    "ErrorCode":"",
  	"TaskId": "xxx"
}



2.7 采样截图完成事件

事件内容

参数名称

类型

描述

EventType

String

事件类型，系统规定参数。固定为

SampleSnapshotEvent

SampleSnapshotTemplateId

String

采样截图模板Id

SampleSnapshotInfos

Array of SampleSnapshotInfo

采样截图详细信息

TaskId

String

任务Id

SampleSnapshotInfo

参数名称

类型

描述

URLPath

String

采样截图相对位置

TimeStamp

Double

截图所在时间戳

Width

Integer

截图宽度

Height

Integer

截图高度


回调示例

{
    "URLPath":"98c9eddde0698c7e-41e80c5bf1792c60551be5f5d7444993-video-sprite1.vtt",
    "CallbackArgs":"test1001",
    "MediaId":"98c9eddde0698c7e",
    "RequestId":"ChzojWQ96RUAAAAAAYqe-g",
    "PrimaryKey":"test1001",
    "EventType":"SampleSnapshot",
    "SampleSnapshotTemplateId":"xxx",
  	"SampleSnapshotInfos": [
      {
      	"URLPath": "video1-sample-0001.jpeg",
        "TimeStamp": 1.0,
        "Width": 1920,
        "Height": 1080
      },
      {
      	"URLPath": "video1-sample-0002.jpeg",
        "TimeStamp": 2.0,
        "Width": 1920,
        "Height": 1080
      },
      {
      	"URLPath": "video1-sample-0003.jpeg",
        "TimeStamp": 3.0,
        "Width": 1920,
        "Height": 1080
      }
    ]
    "ErrorMessage":"",
    "ErrorCode":"",
  	"TaskId": "xxx"
}



3. 回调鉴权

为增强消息回调的安全性，快手点播云支持回调鉴权，用户可选择是否在其消息接收服务中做鉴权和处理。

快手在发送回调时间时，会在回调消息请求的 Header 中添加字段，接收消息的服务器需要对这些字段进行验签，来验证请求真实来自于快手，避免请求伪造。


鉴权参数

参数名称

示例

描述

VOD-TIMESTAMP

1611501482

UNIX时间戳

VOD-SIGNATURE

523dsf94239fsdfew2314

服务端回调时产生的签名

VOD-RANDOM

31238412

发送回调时生成的随机数


SDK 验签示例

headers = {
"VOD-TIMESTAMP": "1611501482", # UNIX时间戳
"VOD-RANDOM": "31238412", # 服务方在发送回调时生成一个随机数
"VOD-URL": "http://my_server/callback" #回调url路径
}
signature = Sign.sign(headers, '<分配给客户的密钥>')

在通过header获取到这几个字段以后将"VOD-TIMESTAMP"、"VOD-RANDOM"以及"VOD-URL"(CallbackURL)使用SDK中的签名方法生成signature，如果与header中的VOD-SIGNATURE相同则说明校验成功，如果不一致，则请求非法。


上一篇：获取媒体处理作业结果列表下一篇：点播CDN功能概览
该篇文档内容是否对您有帮助？
有帮助没帮助
关于我们
了解我们文档中心
支持与服务
服务咨询意见与反馈
法律支持
服务协议隐私政策
联系我们
业务咨询市场合作电话与邮箱
友情链接
快手Acfun快手云剪AI开放平台
京ICP备19034532号-192通信电信许可证 京B2-20202468. B1-20202319 版权所有 @北京溪流湖科技有限公司 2022 版权所有
京ICP备19034532号-192通信电信许可证 京B2-20202468. B1-20202319版权所有 @北京溪流湖科技有限公司 2022 版权所有