You need to enable JavaScript to run this app.
导航
调用方式
最近更新时间:2022.09.15 16:31:21首次发布时间:2022.07.21 16:22:01

接口简介

封面封面选取服务,通过分析传入的视频内容,根据图像质量特点(模糊、光线、对比度等)对图像进行打分,选出一张画风质量优、体现主题、吸引用户消费的的图片。

限制条件

名称内容
视频要求1.视频格式:h264编码格式,非该格式会造成服务内部错误
2.视频大小不超过380MB

请求说明

名称内容
接口地址https://visual.volcengineapi.com
请求方式POST
Content-Typeapplication/x-www-form-urlencoded

请求参数

(1)header请求参数

公共请求参数

以下请求参数列表仅列出了接口请求参数和必要公共参数,完整公共参数列表见 公共参数

名称类型是否必填描述
X-DateString使用UTC时间,精确到秒。请使用格式:YYYYMMDD'T'HHMMSS'Z' ,例如:20201103T104027Z

Authorization

String

HMAC-SHA256:签名方法
-Credential为签名凭证,其中:
-AccessKeyId为访问密钥ID,可在 访问密钥(Access Key) 获取;
-ShortDate为请求的短时间,使用UTC时间,精确到日。请使用格式:YYYYMMDD,例如:20180201
-Region为请求地区,国内一般为为cn-north-1
-Service为请求的服务,一般为cv
-SignedHeaders为参与签名计算的头部信息,content-typehost 为必选头部;
-Signature为签名,可在 签名方法 获取。
注:我们提供了SDK及签名示例供您实现服务快速接入,具体可参考 快速接入
例如:HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}

X-Security-TokenString指安全令牌服务(Security Token Service,STS) 颁发的临时安全凭证中的SessionToken,使用长期密钥时无需填写该参数。

(2)Query参数

业务请求参数

参数可选/必选类型说明
Action必选String接口名,取值:VideoCoverSelection
Version必选String版本号,取值:2020-08-26

(3)Body参数

业务请求参数

参数可选/必选类型说明
video_url可选String视频文件链接,视频大小不能超过380M,和video_id二者选一
video_id可选String视频id,当通过video_url调用接口失败并且返回的data中含有video_id这一项时,后续重试可使用video_id,可大大缩短服务处理时长,和video_url二者选一
images_base64可选[binary]候选封面图片,图片base64编码的数组
enable可选Bool是否执行裁剪和打分模块,默认不启用,用于控制流程图中的虚框部分是否生效
cut_method可选String裁剪方案,可选值:{fix_size},默认值:fix_size,目前只支持一种
heights可选Int裁剪后的高,默认值:256
widths可选Int裁剪后的宽,默认值:256
use_ratio可选Bool为true时,上述的高和宽为最终裁剪的比例;否则,则为最终裁剪的宽高的具体值;默认为false
quality_method可选String封面打分方法,可选值:{common,xigua},默认值:common,详细说明见下方备注
poster_valid_checker_threshold可选Float步骤4的阈值,默认值为1.0,即候选封面优先级较低,虽然传入候选封面仍会尝试从视频中分析封面,分数范围[0~1],详细见下方流程图
image_selector_threshold可选Float步骤9的阈值,默认值为0.0,高光帧和原封面公平比较,选个分最高的,详细见下方流程图

整体流程说明
image

如果没有很多特殊需求,可以只传入video_id,其余的都按照默认。

封面打分方法

  1. common:通用打分方案
  2. xigua:广泛应用于xigua场景的打分方案

可自定义参数

  1. 步骤2、6:智能裁剪比例(尺寸)
  2. 步骤3、5、7:图像质量评分所使用服务
  3. 步骤4:“得分较低”阈值,当 原始封面分数 > 阈值 时,返回原封面
  4. 步骤9:“明显优于”阈值,当 高光帧分数 - 原始封面分数 > 阈值 时,返回高光帧
  5. 是否启用步骤2、6、7图像裁剪与质量评分

输出说明

(1)通用输出参数

通用输出参数具体见通用返回字段及错误码

(2)业务输出参数

data字段说明

字段类型说明
results[ImageInfo]封面结果,通常只会返回一张

ImageInfo字段

字段类型说明
databinary封面图片的base64编码
scoreFloat封面得分

注:data字段包含在通用返回字段中,具体见通用返回字段及错误码

(3)输出示例

{
    "status": 10000,
    "code": 10000,
    "time_elapsed": "570.835792ms",
    "request_id": "69048264100455403521607655177",
    "message": "Success",
    "data": {
        "results": [
            {
                "score": "0.993",
                "data": "图片base64",
            }
        ]
    }
}

错误码

(1)通用错误码

请参考通用返回字段及错误码

(2)业务错误码

http code错误码错误信息说明
20010000Success成功
40050201Missing Input Parameters: video_id or video_url缺少输入参数video_id或者video_url
40050200Invalid Input Parameters: {param}输入参数param不合规
40050211Video Size Exceeds Maximum Limit: please compress the video输入视频过大,超过限制
50050500Internal Error服务内部错误