智能封面分析接口
更新时间:2024-11-19
提交智能封面分析
用户提供视频路径,创建一次视频分析。
- 视频路径支持BOS、VOD、HTTP(S) URL路径;
- 正在分析中的视频无法再次进行分析;判断相同视频的依据是视频路径source,和视频内容无关;
- 已经分析过的视频(FINISHED/ERROR)可以重新进行分析;
- 视频重新分析会覆盖上次分析结果;
- 智能封面分析任务为异步处理模式,如果想要获取分析结果:可以设置回调参数notification,则分析完成之后会将分析结果自动回调通知notification关联的地址;也可以通过接口查询智能封面分析结果来实时获取。
请求语法
Plain Text
1PUT /v{version}/cover HTTP/1.1
2host: vca.bj.baidubce.com
3authorization: <bce-authorization-string>
4content-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类型媒资
Plain Text
1PUT /v1/cover HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "source": "bos://samplebucket/sample.mp4", // 也支持图片bos://demobucket/demo.jpg
8 "preset": "customer_preset_name",
9 "notification": "customer_notification_name"
10}
示例二:分析 VOD 媒资原视频
Plain Text
1PUT /v1/cover HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "source": "vod://mda-fhepatsnpn4rk9z",
8 "preset": "customer_preset_name",
9 "notification": "customer_notification_name"
10}
示例三:分析 VOD 媒资转码后视频
Plain Text
1PUT /v1/cover HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5{
6 "source": "vod://mda-fhepatsnpn4rk9z-mp4",
7 "preset": "customer_preset_name",
8 "notification": "customer_notification_name"
9}
示例四:分析 URL 视频
Plain Text
1PUT /v1/cover HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "source": "https://vca-customer.baidu.com/media.mp4",
8 "preset": "customer_preset_name",
9 "notification": "customer_notification_name"
10}
示例五:分析包含鉴权参数的 URL 视频
Plain Text
1PUT /v1/cover HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
5
6{
7 "source": "https://vca-customer.baidu.com/media.mp4",
8 "auth": "authorization=some_authorization_info"
9 "preset": "customer_preset_name",
10 "notification": "customer_notification_name"
11}
响应体
参数 | 类型 | 描述 |
---|---|---|
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 类型视频响应
Plain Text
1HTTP/1.1 200 OK
2{
3 "source": "bos://samplebucket/sample.mp4",
4 "preset": "customer_preset_name",
5 "status": "PROVISIONING",
6 "percent": 0,
7 "createTime": "2018-10-09T08:05:58Z",
8}
示例二:分析 VOD 媒资原视频响应
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "source": "vod://mda-fhepatsnpn4rk9z",
5 "mediaId": "mda-fhepatsnpn4rk9z",
6 "title": "media title",
7 "preset": "customer_preset_name",
8 "status": "PROVISIONING",
9 "percent": 0,
10 "notification": "customer_notification_name",
11 "createTime": "2018-10-09T08:05:58Z"
12}
示例三:分析 VOD 媒资转码后视频响应
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "source": "vod://mda-fhepatsnpn4rk9z-mp4",
5 "mediaId": "mda-fhepatsnpn4rk9z",
6 "title": "media title",
7 "preset": "customer_preset_name",
8 "status": "PROVISIONING",
9 "percent": 0,
10 "notification": "customer_notification_name",
11 "createTime": "2018-10-09T08:05:58Z"
12}
示例四:分析 URL 视频响应
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "source": "https://vca-customer.baidu.com/media.mp4",
5 "preset": "customer_preset_name",
6 "status": "PROVISIONING",
7 "percent": 0,
8 "notification": "customer_notification_name",
9 "createTime": "2018-10-09T08:05:58Z"
10}
示例五:分析包含鉴权参数的 URL 视频响应
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "source": "https://vca-customer.baidu.com/media.mp4",
5 "preset": "customer_preset_name",
6 "status": "PROVISIONING",
7 "percent": 0,
8 "notification": "customer_notification_name",
9 "createTime": "2018-10-09T08:05:58Z"
10}
查询智能封面分析结果
根据视频路径查询分析结果。如果有重复分析,则返回最近一次分析的结果。
- 智能封面分析结果最长暂存30天,超过30天后会自动删除,无法查询;
- 智能封面分析结果涉及的“http(s)地址”字段(例如静态封面结果字段staticCoverResults && 动态封面结果字段clipCoverResults && gif返回结果字段gifCoverResult)均带有鉴权,且鉴权有效时间为从发起请求开始1小时范围内;如果要对封面文件等进行转储,需要在鉴权有效时间内完成;超过该时间段则建议重新获取智能封面分析结果,从而可以重新获取鉴权有效的“http(s)地址”。
请求语法
Plain Text
1GET /v{version}/cover HTTP/1.1
2host: vca.bj.baidubce.com
3authorization: <bce-authorization-string>
4content-type: application/json
支持v1
、v2
请求参数
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
source | String | 视频路径,需要对source进行urlEncode。 | 是 |
请求体
无
请求示例
示例一:查询 BOS 视频分析结果
Plain Text
1GET /v1/cover?source=bos%3a%2f%2ftestbucket%2fdir%2fvideo.mp4 HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
示例二:查询 VOD 媒资原视频分析结果
Plain Text
1GET /v1/cover?source=vod%3a%2f%2fmda-fhepatsnpn4rk9z HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
示例三:查询 VOD 媒资转码后视频分析结果
Plain Text
1GET /v1/cover?source=vod%3a%2f%2fmda-fhepatsnpn4rk9z-mp4 HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
示例四:查询 URL 视频分析结果
Plain Text
1GET /v1/cover?source=http%3a%2f%2ftest.domain.com%2fdir%2fvideo.mp4 HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <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小时 + 原始视频时长的一半 |
响应示例
示例一:智能封面分析成功
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "taskId": "mk8tbsb0n8aerix0sy9",
5 "source": "http://bj.bcebos.com/videoai-vio/wangzheng/test.mp4",
6 "description": "",
7 "preset": "default",
8 "status": "FINISHED",
9 "percent": 100,
10 "results": [
11 {
12 "type": "cover",
13 "coverResult": {
14 "staticCoverResults": {
15 "urls": [
16 "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",
17 "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"
18 ],
19 "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"
20 },
21 "clipCoverResults": {
22 "urls": [
23 "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",
24 "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"
25 ],
26 "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"
27 },
28 "gifCoverResult": [
29 "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"
30 ]
31 }
32 }
33 ],
34 "createTime": "2021-11-09T11:18:12Z",
35 "startTime": "2021-11-09T11:18:21Z",
36 "durationInSecond": 22,
37 "publishTime": "2021-11-09T11:23:31Z"
38}
示例二:智能封面分析失败
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "taskId": "mk8tbsb0n8aerix0sy9",
5 "source": "http://bj.bcebos.com/videoai-vio/wangzheng/test.mp4",
6 "description": "",
7 "preset": "default",
8 "status": "FINISHED",
9 "percent": 100,
10 "error":{
11 "code":"TimeOut",
12 "message":"analyze time out, please retry"
13 },
14 "createTime": "2021-11-09T11:18:12Z",
15 "startTime": "2021-11-09T11:18:21Z",
16 "durationInSecond": 22,
17 "publishTime": "2021-11-09T11:23:31Z"
18}
取消智能封面分析
只有状态处于预处理的视频可以进行取消。
请求语法
Plain Text
1PUT /v{version}/cover?source={url}&cancel HTTP/1.1
2host: vca.bj.baidubce.com
3authorization: <bce-authorization-string>
4content-type: application/json
支持v1
、v2
请求参数
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
source | String | 视频路径,需要对source进行urlEncode。 | 是 |
cancel | String | 标志参数,不需要取值 | 是 |
请求体
无
请求示例
Plain Text
1PUT /v1/cover?source=http://bj.bcebos.com/hh.mp4&cancel= HTTP/1.1
2host: vca.bj.baidubce.com
3content-type: application/json
4authorization: <bce-authorization-string>
响应头域
无
响应体
无
响应示例
示例一:智能封面分析任务处于排队中,成功取消
Plain Text
1HTTP/1.1 200 OK
示例二:智能封面分析任务不处于排队中,取消报错
Plain Text
1HTTP/1.1 200 OK
2
3{
4 "code": "InvalidMedia",
5 "message": "invalid media: http://bj.bcebos.com/hh.mp4",
6 "requestId": "fake-request-id"
7}