智能封面分析接口

更新时间：2024-11-18

提交封面分析

用户提供视频路径，创建一次视频分析。

视频路径支持BOS、VOD、HTTP(S) URL路径；
正在分析中的视频无法再次进行分析；判断相同视频的依据是视频路径source，和视频内容无关；
已经分析过的视频（FINISHED/ERROR）可以重新进行分析；
视频重新分析会覆盖上次分析结果；
封面分析任务为异步处理模式，如果想要获取分析结果：可以设置回调参数notification，则分析完成之后会将分析结果自动回调通知notification关联的地址；也可以通过接口查询封面分析结果来实时获取。

请求语法

PUT /v{version}/cover HTTP/1.1
host: vca.bj.baidubce.com
authorization: <bce-authorization-string>
content-type: application/json

支持v1、v2

请求参数

无

请求体

参数	类型	描述	是否必须
source	String	视频路径，不超过1024字符（分辨率需大于等于30*30且时长在6小时内）	是
auth	String	视频路径鉴权参数，仅URL视频使用	否
description	String	视频描述，默认空字符串，不超过256字符	否
preset	String	分析模板名称，若为空会使用默认模板	否
notification	String	通知名称，使用方式见通知接口	否
priority	Integer	优先级，取值范围是1～100，缺省值是0，值越大优先级越高；默认排队中的视频分析会按照创建时间顺序进行处理，如果有热点视频需要高优得到处理，则可以为其设置较大的优先级参数。	否

说明：

对于 BOS 视频，source="bos://<bos-bucket>/<bos-object>", 例如"bos://testbucket/dir/video.mp4"，由客户保证 BOS 路径可访问。

对于 VOD 媒资，source="vod://<vod-media-id>"，例如"vod://mda-fhepatsnpn4rk9z"，MCA 会内部请求VOD获取源视频地址，需要确保媒资在VOD状态为PUBLISHED。

对于 VOD 媒资转码后的视频，source="vod://<vod-media-id>-<vod-preset>", 例如"vod://mda-abc-default"，注意这里使用“-”作为分隔符。（补充知识：VOD中媒资ID由系统生成，形如mda-xxx，共计20个字符；VOD模板名由数字、字母和下划线组成，不超过40字符）

对于HTTP/HTTPS视频，source="<http(s)-url>", 例如"http://domain/dir/video.mp4"，url中可以包含参数，例如"http://domain/dir/video?id=abc"。另外，为了优化客户使用体验，MCA 支持将HTTP/HTTPS视频URL中的临时参数（主要是鉴权参数）通过auth="<key1>=<value1>&<key2>=<value2>"和其它参数进行区分，auth中可以包含多个参数，用&进行分割，例如"token=abcxyz×tamp=1514993900", MCA内部会使用?或&将source和auth拼接，得到完整的原视频URL并拉取进行分析。客户需保证实际拉取的URL可访问。客户仅需通过source即可查询视频分析结果，同时分析回调中也仅返回source。

请求示例

示例一：分析BOS类型媒资

PUT /v1/cover HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
    "source": "bos://samplebucket/sample.mp4", // 也支持图片bos://demobucket/demo.jpg
    "preset": "customer_preset_name",
    "notification": "customer_notification_name"
}

示例二：分析 VOD 媒资原视频

PUT /v1/cover HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
  "source": "vod://mda-fhepatsnpn4rk9z",
  "preset": "customer_preset_name",
  "notification": "customer_notification_name"
}

示例三：分析 VOD 媒资转码后视频

PUT /v1/cover HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>
{
  "source": "vod://mda-fhepatsnpn4rk9z-mp4",
  "preset": "customer_preset_name",
  "notification": "customer_notification_name"
}

示例四：分析 URL 视频

PUT /v1/cover HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
    "source": "https://vca-customer.baidu.com/media.mp4", 
    "preset": "customer_preset_name",
    "notification": "customer_notification_name"
}

示例五：分析包含鉴权参数的 URL 视频

PUT /v1/cover HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
    "source": "https://vca-customer.baidu.com/media.mp4", 
    "auth": "authorization=some_authorization_info"
    "preset": "customer_preset_name",
    "notification": "customer_notification_name"
}

响应体

参数	类型	描述
source	String	视频路径
mediaId	String	VOD媒资ID，source为VOD路径时存在
description	String	视频描述
preset	String	分析模板名称
status	String	分析状态
percent	Number	0 ~ 100整数，单位%
notification	String	通知名称
priority	Integer	任务优先级
createTime	Date	分析创建时间

响应示例

示例一：分析 BOS 类型视频响应

HTTP/1.1 200 OK
{
    "source": "bos://samplebucket/sample.mp4",
    "preset": "customer_preset_name",
    "status": "PROVISIONING",
    "percent": 0,
    "createTime": "2018-10-09T08:05:58Z",
}

示例二：分析 VOD 媒资原视频响应

HTTP/1.1 200 OK

{
    "source": "vod://mda-fhepatsnpn4rk9z",
    "mediaId": "mda-fhepatsnpn4rk9z",
    "title": "media title",
    "preset": "customer_preset_name",
    "status": "PROVISIONING",
    "percent": 0,
    "notification": "customer_notification_name",
    "createTime": "2018-10-09T08:05:58Z"
}

示例三：分析 VOD 媒资转码后视频响应

HTTP/1.1 200 OK

{
	"source": "vod://mda-fhepatsnpn4rk9z-mp4",
	"mediaId": "mda-fhepatsnpn4rk9z",
	"title": "media title",
	"preset": "customer_preset_name",
	"status": "PROVISIONING",
	"percent": 0,
	"notification": "customer_notification_name",
	"createTime": "2018-10-09T08:05:58Z"
}

示例四：分析 URL 视频响应

HTTP/1.1 200 OK
	
{
    "source": "https://vca-customer.baidu.com/media.mp4",
    "preset": "customer_preset_name",
    "status": "PROVISIONING",
    "percent": 0,
    "notification": "customer_notification_name",
    "createTime": "2018-10-09T08:05:58Z"
}

示例五：分析包含鉴权参数的 URL 视频响应

HTTP/1.1 200 OK
	
{
    "source": "https://vca-customer.baidu.com/media.mp4",
    "preset": "customer_preset_name",
    "status": "PROVISIONING",
    "percent": 0,
    "notification": "customer_notification_name",
    "createTime": "2018-10-09T08:05:58Z"
}

查询封面分析结果

根据视频路径查询分析结果。如果有重复分析，则返回最近一次分析的结果。

封面分析结果最长暂存30天，超过30天后会自动删除，无法查询；
封面分析结果涉及的“http(s)地址”字段（例如静态封面结果字段staticCoverResults && 动态封面结果字段clipCoverResults && gif返回结果字段gifCoverResult）均带有鉴权，且鉴权有效时间为从发起请求开始1小时范围内；如果要对封面文件等进行转储，需要在鉴权有效时间内完成；超过该时间段则建议重新获取封面分析结果，从而可以重新获取鉴权有效的“http(s)地址”。

请求语法

GET /v{version}/cover HTTP/1.1
host: vca.bj.baidubce.com
authorization: <bce-authorization-string>
content-type: application/json

支持v1、v2

请求参数

参数	类型	描述	是否必须
source	String	视频路径，需要对source进行urlEncode。	是

请求体

无

请求示例

示例一：查询 BOS 视频分析结果

GET /v1/cover?source=bos%3a%2f%2ftestbucket%2fdir%2fvideo.mp4 HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

示例二：查询 VOD 媒资原视频分析结果

GET /v1/cover?source=vod%3a%2f%2fmda-fhepatsnpn4rk9z HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

示例三：查询 VOD 媒资转码后视频分析结果

GET /v1/cover?source=vod%3a%2f%2fmda-fhepatsnpn4rk9z-mp4 HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

示例四：查询 URL 视频分析结果

GET /v1/cover?source=http%3a%2f%2ftest.domain.com%2fdir%2fvideo.mp4 HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

说明：

注意：如前所述，对于 URL 视频，如果在提交分析时指定了auth参数，在查询分析结果时是不需要指定的。

响应头域

无

响应参数

参数	类型	描述
source	String	视频路径
description	String	视频描述
durationInSecond	Number	视频时长，仅当status不为PROVISIONING时存在
preset	String	分析模板名称
status	String	分析状态
percent	Number	0 ~ 100整数，单位%
createTime	Date	分析创建时间
startTime	Date	分析开始时间，仅当status不为PROVISIONING/CANCELLED时存在
publishTime	Date	分析结束时间，仅当status=FINISHED/ERROR/CANCELLED时存在
results	Array	分析结果，仅当status=FINISHED时存在
+ type	String	标记结果类型为cover
+ coverResult	Object	cover返回结果结构体
++ staticCoverResults	Object	静态封面结果
++ clipCoverResults	Object	动态封面结果
++ gifCoverResult	List	gif返回结果
error	Object	分析失败信息，仅当status=ERROR时存在
+ code	String	错误码
+ message	String	错误信息

分析状态枚举如下：

分析状态	状态名称	描述
PROVISIONING	预处理	视频分析排队中
PROCESSING	分析中	视频分析进行中
FINISHED	分析结束	分析结束，可以查询分析结果
ERROR	分析失败	分析失败，可以查询失败错误原因
CANCELLED	分析取消	分析取消，视频排队时可以取消分析

错误码枚举如下：

错误码	错误信息	备注
InvalidMedia	media duration/resolution exceeds limit	视频时长/分辨率不满足MCA系统限制，请检查原视频
InvalidMedia	invalid audio or video	视频元信息中音频或视频信息不合预期，请检查原视频
InvalidMedia	get media info failure	无法获取视频元信息，请检查原视频
InvalidMedia	media is not published	VOD视频专属错误消息，VOD视频状态不为PUBLISHED，请检查原视频
InvalidMedia	media does not exist	VOD视频专属错误消息，VOD视频不存在，请检查原视频
InternalError	service internal error, please retry	系统内部错误，建议重试
TimeOut	analyze time out, please retry	视频分析超时，请先检查原视频，如视频正常则可以重试

其中当错误码为TimeOut时，根据视频时长不同，超时上限也不同：

视频时长	超时上限
<3min	15分钟
<10min	30分钟
<30min	1小时
其它	2小时 + 原始视频时长的一半

响应示例

示例一：封面分析成功

HTTP/1.1 200 OK

{
    "taskId": "mk8tbsb0n8aerix0sy9",
    "source": "http://bj.bcebos.com/videoai-vio/wangzheng/test.mp4",
    "description": "",
    "preset": "default",
    "status": "FINISHED",
    "percent": 100,
    "results": [
        {
            "type": "cover",
            "coverResult": {
                "staticCoverResults": {
                    "urls": [
                        "http://bj-bos-sandbox.baidu-int.com/vaas-common-bucket-0/43be75f6cd2fb541a9e7e9cb21197033/thumbnailV2/thumbnailV2_true_1280_1.0_0_30000_1s00018.jpg?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab",
                        "http://bj-bos-sandbox.baidu-int.com/vaas-common-bucket-0/43be75f6cd2fb541a9e7e9cb21197033/thumbnailV2/thumbnailV2_true_1280_1.0_0_30000_1s00020.jpg?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab"
                    ],
                    "zipUrl": "http://bj-bos-sandbox.baidu-int.com/vca-persistence/subtask/mk8tbxepp6s075gu858/video_cover/output_20211109191851.tar.gz?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab"
                },
                "clipCoverResults": {
                    "urls": [
                        "http://bj-bos-sandbox.baidu-int.com/vca-persistence/subtask/mk8tbxep51kb6863caa/highlight/0.5_10.0.mp4?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab",
                        "http://bj-bos-sandbox.baidu-int.com/vca-persistence/subtask/mk8tbxep51kb6863caa/highlight/11.5_10.0.mp4?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab"
                    ],
                    "zipUrl": "http://bj-bos-sandbox.baidu-int.com/vca-persistence/subtask/mk8tbxep51kb6863caa/highlight/output_20211109192253.tar.gz?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab"
                },
                "gifCoverResult": [
                    "http://bj-bos-sandbox.baidu-int.com/vca-persistence/subtask/mk8tbxep51kb6863caa/highlight/3_5.gif?authorization=bce-auth-v1%2F16f624e4866c485d9b06cb20549edbc2%2F2023-02-15T02%3A51%3A50Z%2F21600%2Fhost%2F059dae5b67328a5d411bc0dfe019350ccc560f3f8c96e04813a0c3005367e9ab"
                ]
            }
        }
    ],
    "createTime": "2021-11-09T11:18:12Z",
    "startTime": "2021-11-09T11:18:21Z",
    "durationInSecond": 22,
    "publishTime": "2021-11-09T11:23:31Z"
}

示例二：封面分析失败

HTTP/1.1 200 OK

{
    "taskId": "mk8tbsb0n8aerix0sy9",
    "source": "http://bj.bcebos.com/videoai-vio/wangzheng/test.mp4",
    "description": "",
    "preset": "default",
    "status": "FINISHED",
    "percent": 100,
    "error":{
        "code":"TimeOut",
        "message":"analyze time out, please retry"
    },
    "createTime": "2021-11-09T11:18:12Z",
    "startTime": "2021-11-09T11:18:21Z",
    "durationInSecond": 22,
    "publishTime": "2021-11-09T11:23:31Z"
}

取消封面分析

只有状态处于预处理的视频可以进行取消。

请求语法

PUT /v{version}/cover?source={url}&cancel HTTP/1.1
host: vca.bj.baidubce.com
authorization: <bce-authorization-string>
content-type: application/json

支持v1、v2

请求参数

参数	类型	描述	是否必须
source	String	视频路径，需要对source进行urlEncode。	是
cancel	String	标志参数，不需要取值	是

请求体

无

请求示例

PUT /v1/cover?source=http://bj.bcebos.com/hh.mp4&cancel= HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

响应头域

无

响应体

无

响应示例

示例一：封面分析任务处于排队中，成功取消

HTTP/1.1 200 OK

示例二：封面分析任务不处于排队中，取消报错

HTTP/1.1 200 OK

{
    "code": "InvalidMedia",
    "message": "invalid media: http://bj.bcebos.com/hh.mp4",
    "requestId": "fake-request-id"
}

图片内容分析接口

精彩视频分析接口

百度智能云

内容分析 MCA

内容分析 MCA

智能封面分析接口

提交封面分析

查询封面分析结果

取消封面分析