调用方式--视频技术-火山引擎

文档中心

导航

调用方式

最近更新时间：2022.09.15 16:31:21首次发布时间：2022.07.21 16:22:01

接口简介

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

限制条件

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

请求说明

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

请求参数

（1）header请求参数

公共请求参数

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

名称	类型	是否必填	描述
X-Date	String	是	使用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-type` 和 `host` 为必选头部； -Signature为签名，可在签名方法获取。注：我们提供了SDK及签名示例供您实现服务快速接入，具体可参考快速接入例如：`HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}`
X-Security-Token	String	否	指安全令牌服务（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，高光帧和原封面公平比较，选个分最高的，详细见下方流程图

整体流程说明

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

封面打分方法

common：通用打分方案
xigua：广泛应用于xigua场景的打分方案

可自定义参数

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

输出说明

（1）通用输出参数

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

（2）业务输出参数

data字段说明

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

ImageInfo字段

字段	类型	说明
`data`	`binary`	封面图片的base64编码
`score`	`Float`	封面得分

注：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	错误码	错误信息	说明
200	10000	Success	成功
400	50201	Missing Input Parameters: video_id or video_url	缺少输入参数video_id或者video_url
400	50200	Invalid Input Parameters: {param}	输入参数param不合规
400	50211	Video Size Exceeds Maximum Limit: please compress the video	输入视频过大，超过限制
500	50500	Internal Error	服务内部错误