5. 直播封面

5.1 直播截图

5.1.1 设置截图配置

5.1.1.1 接口说明

该接口用于:针对直播截图功能,设置频道下的截图相关配置。

该接口不建议频繁调用,因为配置只在下次推流时才会生效。

5.1.1.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/updateconfig HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.1.3 参数说明
参数 类型 说明 必须
cid String 频道ID
timeInterval Integer 截图周期,取值范围[5,3600],单位秒,默认5
imageFormat String 图片格式:jpg、png,默认jpg
imageWidth Integer 图片宽度,默认0
imageHeight Integer 图片高度,默认0

注:imageWidth和imageHeight不能大于4096不能小于-1,为0则表示与流的宽高信息等同,其中一个为-1则表示保持宽高比的情况下自动计算,两个都为-1则等同于都是0。

5.1.1.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"cid": "cidxxxxxxxxx","timeInterval": 5,"imageFormat": "jpg"}' https://vcloud.163.com/app/channel/snapshot/updateconfig
5.1.1.5 返回说明

http 响应:json

参数 类型 说明
code Int 状态码
requestId String 请求id
msg String 错误信息, 非200状态码下返回
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx"
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.1.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务

5.1.2 获取截图配置

5.1.2.1 接口说明

该接口用于:针对直播截图功能,获取频道下的截图相关配置。当开始截图时,如果尚未设置截图配置,会自动生成默认配置。

5.1.2.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/getconfig HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.2.3 参数说明
参数 类型 说明 必须
cid String 频道ID
5.1.2.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"cid": "cidxxxxxxxxx"}' https://vcloud.163.com/app/channel/snapshot/getconfig
5.1.2.5 返回说明

http 响应:json

参数 类型 说明
code int 状态码
requestId String 请求id
ret JSON 返回信息, 200状态码下返回
msg String 错误信息, 非200状态码下返回

其中,ret格式如下:

参数 类型 说明
cid String 频道ID
timeInterval Integer 截图周期,单位秒
imageFormat String 图片格式
imageWidth Integer 图片宽度
imageHeight Integer 图片高度
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx",
        "ret":{
            "cid": "xxx",
            "timeInterval": 5,
            "imageFormat": "jpg",
            "imageWidth": 0,
            "imageHeight": 0
        }
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.2.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务

5.1.3 发起直播截图

5.1.3.1 接口说明

该接口用于发起频道下的直播截图。

返回结果状态码为200,表明截图任务成功发起。非200状态码,请根据错误码进行重试等相应操作。

截图任务成功发起后,如果推流中止而导致拉不到流,超时后任务会自动停止。重新推流直播后,需要用户自己重新请求发起。

5.1.3.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/start HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.3.3 参数说明
参数 类型 说明 必须
cid String 频道ID
5.1.3.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"cid": "cidxxxxxxxxx"}' https://vcloud.163.com/app/channel/snapshot/start
5.1.3.5 返回说明

http 响应:json

参数 类型 说明
code int 状态码
requestId String 请求id
msg String 错误信息, 非200状态码下返回
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx"
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.3.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务

5.1.4 停止直播截图

5.1.4.1 接口说明

该接口用于发起频道下的直播截图。

在截图任务运行后,如果系统未收到该接口请求,那么在推流行为结束后拉流超时,任务会自动停止。重新推流直播后,需要用户自己重新请求发起直播截图。

5.1.4.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/stop HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.4.3 参数说明
参数 类型 说明 必须
cid String 频道ID
5.1.4.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"cid": "cidxxxxxxxxx"}' https://vcloud.163.com/app/channel/snapshot/stop
5.1.4.5 返回说明

http 响应:json

参数 类型 说明
code int 状态码
requestId String 请求id
msg String 错误信息, 非200状态码下返回
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx"
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.4.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务

5.1.5 获取截图列表

5.1.5.1 接口说明

分页获取某频道下的截图列表

5.1.5.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/list HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.5.3 参数说明
参数 类型 说明 必须
cid String 频道ID
beginTime Long 查询开始时间(秒)
endTime Long 查询结束时间(秒),beginTime和endTime间隔不能超过1天
curPage Integer 分页索引,不填默认是1
pageSize Integer 限定每页返回的数量,返回的数量小于或等于该值,范围[1,500],默认100
sort String 按截图生成时间排序,asc表示升序,desc表示降序,默认为desc
5.1.5.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"cid": "cidxxxxxxxxx", "beginTime": 1578315807, "endTime": 1578315897}' https://vcloud.163.com/app/channel/snapshot/list
5.1.5.5 返回说明

http 响应:json

参数 类型 说明
code int 状态码
requestId String 请求id
ret JSON 返回信息, 200状态码下返回
msg String 错误信息, 非200状态码下返回

其中,ret格式如下:

参数 类型 说明
list List 列表
- snapshotId Long 截图id
- objectName String 截图对象名
- createTime Long 截图生成时间(毫秒)
curPage Integer 当前页数
pageSize Integer 每页大小
totalPageNum Integer 总页数
totalSize Integer 总记录数
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx",
        "ret":{
            "curPage":1,
            "pageSize":100,
            "totalPageNum:1,
            "totalSize":9,
            "list":[
                {
                    "snapshotId":1001,
                    "objectName":"livesnapshot_cidxxx-0.jpg",
                    "createTime":1578315807000
                }
            ]
        }
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.5.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务

5.1.6 批量删除截图

5.1.6.1 接口说明

根据截图ID列表批量删除截图

5.1.6.2 请求说明
POST https://vcloud.163.com/app/channel/snapshot/delList HTTP/1.1
Content-Type: application/json;charset=utf-8
5.1.6.3 参数说明
参数 类型 说明 必须
snapshotIdList List 截图ID列表,大小不超过500
5.1.6.4 curl请求示例
    curl -X POST -H "Content-Type: application/json" -H "AppKey: 29781bbc4db54742a3ebcxxxxxxxxxxx" -H "Nonce: 12345" -H "CurTime: 1469171950571" -H "CheckSum: 4ba6ca70c685eb900917e423eadaxxxxxxxxxxxxx" -d '{"snapshotIdList": [1,2,3]}' https://vcloud.163.com/app/channel/snapshot/delList
5.1.6.5 返回说明

http 响应:json

参数 类型 说明
code int 状态码
requestId String 请求id
msg String 错误信息, 非200状态码下返回
    //成功结果示例
    "Content-Type": "application/json; charset=utf-8"
    {        
        "code":200,
        "requestId": "xxx"
    }

    //错误返回示例
    "Content-Type": "application/json; charset=utf-8"
    {
        "code":723,
        "msg":"使用直播截图功能需开通云点播服务",
        "requestId": "xxx"
    }
5.1.6.6 响应状态码
状态码 含义
200 操作成功
409 认证失败
501 内部错误
607 用户信息不存在
613 CheckSum为空
614 AppKey为空
615 CurTime为空
617 频道信息与当前用户不匹配
618 查询数据信息不存在
631 请求参数错误
647 频道不存在
723 使用直播截图功能需开通云点播服务