智能封面分析接口
更新时间：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}