视频分析接口

提交视频分析

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

  • 视频路径支持BOS、VOD、HTTP(S) URL路径;
  • 正在分析中的视频无法再次进行分析;
  • 已经分析过的视频(FINISHED/ERROR)可以重新进行分析;
  • 视频重新分析会覆盖上次分析结果。

请求语法

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

v1v2均支持

请求参数

请求体

参数 类型 描述 是否必须
source String 视频路径,不超过1024字符
auth String 视频路径鉴权参数,仅URL视频使用
title String 视频标题,默认不设置,不超过256字符 否,如果没有设置title,对于VOD媒资,VCA会主动去VOD查询标题
description String 视频描述,默认空字符串,不超过256字符
preset String 分析模板名称,若为空会使用默认模板
notification String 通知名称

说明:

  1. 对于 BOS 视频,source="bos://<bos-bucket>/<bos-object>", 例如"bos://testbucket/dir/video.mp4",由客户保证 BOS 路径可访问。
  2. 对于 VOD 媒资,source="vod://<vod-media-id>",例如"vod://mda-fhepatsnpn4rk9z",VCA 会内部请求VOD获取源视频地址,需要确保媒资在VOD状态为PUBLISHED。
  3. 对于 VOD 媒资转码后的视频,source="vod://<vod-media-id>-<vod-preset>", 例如"vod://mda-abc-default",注意这里使用“-”作为分隔符。(补充知识:VOD中媒资ID由系统生成,形如mda-xxx,共计20个字符;VOD模板名由数字、字母和下划线组成,不超过40字符)
  4. 对于HTTP/HTTPS视频,source="<http(s)-url>", 例如"http://domain/dir/video.mp4",url中可以包含参数,例如"http://domain/dir/video?id=abc"。另外,为了优化客户使用体验,VCA 支持将HTTP/HTTPS视频URL中的临时参数(主要是鉴权参数)通过auth="<key1>=<value1>&<key2>=<value2>"和其它参数进行区分,auth中可以包含多个参数,用&进行分割,例如"token=abcxyz&timestamp=1514993900", VCA内部会使用?&将source和auth拼接,得到完整的原视频URL并拉取进行分析。客户需保证实际拉取的URL可访问。客户仅需通过source即可查询视频分析结果,同时分析回调中也仅返回source

请求示例

示例一:分析BOS类型媒资

PUT /v1/media 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/media 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/media 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/media HTTP/1.1
host: vca.bj.baidubce.com
content-type: application/json
authorization: <bce-authorization-string>

{
    "source": "https://vca-customer.baidu.com/media.mp4", // 也支持图片https://vca-customer.baidu.com/media.jpg
    "preset": "customer_preset_name",
    "notification": "customer_notification_name"
}

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

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

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

响应体

参数 类型 描述
source String 视频路径
mediaId String VOD媒资id,source为VOD路径时存在
title String 视频标题
description String 视频描述
preset String 分析模板名称
status String 分析状态
percent Number 分析进度,0 ~ 100整数
notification String 通知名称
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"
}

查询视频分析结果

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

请求语法

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

v1v2均支持

请求参数

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

请求体

请求示例

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

GET /v1/media?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/media?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/media?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/media?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 视频路径
mediaId String VOD媒资id,source为VOD路径时存在
title String 视频标题
description String 视频描述
duration Number 视频时长,仅当status!=PROVISIONING时存在
preset String 分析模板名称
status String 分析状态
percent Number 分析进度,0 ~ 100整数
notification String 通知名称
createTime Date 分析创建时间
startTime Date 分析开始时间,仅当status!=RPOVISIONING/CANCELLED时存在
publishTime Date 分析结束时间,仅当status=FINISHED/ERROR/CANCELLED时存在
results Array 分析结果,仅当status=PROCESSING/FINISHED时存在
error Object 分析失败信息,仅当status=ERROR时存在
+ code String 错误码
+ message String 错误信息

响应示例

HTTP/1.1 200 OK

{
    "source": "vod://mda-fhepatsnpn4rk9z",
    "mediaId": "mda-fhepatsnpn4rk9z",
    "title": "media title",
    "description": "",
    "preset": "customer_preset_name",
    "status": "FINISHED",
    "percent": 100,
    "notification": "customer_notification_name",
    "createTime": "2018-10-09T12:00:00Z",
    "publishTime": "2018-10-09T12:06:48",
    "results": [{
        "type": "scenario",
        "result": [{
            "attribute": "新闻",
            "source": "scenario_classify",
            "confidence": 68,
        }]
    }]
}

查询视频分析中间任务结果

VCA 对视频的分析过程,会涉及很多中间任务的执行。发起视频分析时选用的分析模板定义了需要执行的中间任务集合。

根据视频路径查询指定类型的中间任务分析结果。

请求语法

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

v1v2均支持

请求参数

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

请求体

请求示例

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

响应头域

响应体

参数 类型 描述
source String 视频路径
status String 中间任务状态
type String 中间任务类型
result String 中间任务结果

status肯定为FINISHED,因为当视频分析失败或者中间任务不存在时会返回400。

响应示例

HTTP/1.1 200 OK

{
    "source": "vod://mda-fhepatsnpn4rk9z",
    "type": "scenario_classify"
    "status": "FINISHED",
    "result": "{\"results\":[{\"scenario\":\"女神\",\"probability\":0.7180786728858948}],\"featureUrl\":\"http://bj.bcebos.com/vca-persistence/subtask/ikbp378443mii55pafp_middle.json\"}"
}

分析结果说明

视频分析状态和进度

分析状态 状态名称 描述
PROVISIONING 预处理 视频分析排队中
PROCESSING 分析中 视频分析进行中
FINISHED 分析结束 分析结束,可以查询分析结果
ERROR 分析失败 分析失败,可以查询失败错误原因
CANCELLED 分析取消 分析取消,视频排队时可以取消分析
  • 每一次提交分析后,智能内容分析服务会根据其使用的分析模板在内部进行多项”中间任务”。
  • 若任一中间任务失败,本次分析就会失败。
  • 当每项子分析完成时,VCA 都会更新本次分析的分析进度。

分析结果

每个视频的分析结果格式为:

参数 类型 描述
results Array 分析结果
+ type String 分析场景
+ result Array 分析结果项列表

分析场景

VCA 目前之前的分析场景包括:

分析场景 描述
figure 人脸
logo logo
keyword 关键字
scenario 场景
entity 实体
merge 融合
knowledge_graph 知识图谱

分析结果项

在分析结果中,每个分析场景都对应一个result,表示该场景下的结果。数组中的元素称为分析结果项,其具体格式为:

参数 类型 描述
attribute String 分析结果标签
confidence Double 分析结果项的置信度,0~100的浮点数
source String 标签来源
time Array 标签对应时间段,空数组表示标签来自对整个视频的分析
+ start Integer 起始时间
+ end Integer 结束时间

中间任务结果说明

在中间任务结果中,都有一个result字段。每种分析场景对应的分析结果项列表,可能是来源于不同的中间任务分析结果。目前 VCA 中支持的中间任务类型、结果result取值样例以及和分析场景的映射关系如下:

中间任务类型 中间任务描述 中间任务结果result示例 对应分析场景 对应分析结果项中标签来源
video 视频转码结果 "{\"videoUrl\":\"http://bj.bcebos.com/bucket-0/-0a6d8a381e500b89c54b9c1708377927/video/video.mp4\"}" - -
cover 视频智能封面 "{\"coverUrl\":\"http://bj.bcebos.com/bucket-0/-0a6d8a381e500b89c54b9c1708377927/cover/cover.jpg\"}" - -
thumbnail 以一定策略从视频截取的缩略图集合 "{\"thumbnailUrls\":[\"http://bj.bcebos.com/bucket-0/-0a6d8a381e500b89c54b9c1708377927/thumbnail/thumbnail_1s00000.jpg\"]}" - -
character 视频缩略图通过OCR技术获取的文字识别结果 "[{\"image\":\"http://bj.bcebos.com/bucket-0/-0a6d8a381e500b89c54b9c1708377927/thumbnail/thumbnail_1s00002.jpg\",\"words\":[{\"word\":\"今天要下雨",\"rect\":{\"leftOffsetInPixel\":220,\"topOffsetInPixel\":112,\"widthInPixel\":198,\"heightInPixel\":42},\"confidence\":0.99}]}]" - -
audio 视频音频 "{\"audioUrl\":\"http://bj.bcebos.com/bucket-0/-0a6d8a381e500b89c54b9c1708377927/audio/audio_16000_mix.pcm\"}"
speech 视频音频通过ASR技术获取的语音识别结果 "[{\"startTimestampInSecond\":0,\"endTimestampInSecond\":14,\"statement\":\"在五四青年节来临之际在中国政法大学建校六十五周年前夕中共中央总书记国家主席中央军委主席习近平三日上午来到中国政法大学考察,\"},{\"startTimestampInSecond\":14,\"endTimestampInSecond\":20,\"statement\":\"习近平代表党中央向全国各族青年致以节日的问候,向全国广大教育,\"}]" - -
title 视频标题 "{\"title\":\"这是标题\"}" - -
face_tracking 人脸追踪特征 "{\"faces\":[{\"faceUrl\":\"http://bj.bcebos.com/bucket-0/2796bfc78d45121c10fecfabfae59323/faceTrackingV2/faceTrackingV2/0-0\_face.jpg\",\"image\":\"http://bj.bcebos.com/bucket-0/2796bfc78d45121c10fecfabfae59323/thumbnail/thumbnail\_1s00001.jpg\",\"frame\_num\":2,\"start\_frame\":1}]}" - -
face_recognition_tracking tracking版本的公有人脸识别模型 "{\"faces\":[{\"data\":{\"name\":\"吕行",\"radio\":0.78144413232803},\"frame_num\":1,\"start_frame\":10}]}" figure face_recognition
face_recognition_image 非tracking版本的公有人脸识别模型 "{\"result\":[{\"image\":\"http://bj.bcebos.com/bucket-0/a054d1d4a9a86ad0001ba695fdf79f51/thumbnail/thumbnail\_1s00009.jpg\",\"faces\":[{\"stars\":[{\"name\":\"吕行\",\"probability\":0.6474741101265},{\"name\":\"陈浩民\",\"probability\":0.62125766277313}]}]}]}" figure face_recognition
private_face_tracking tracking版本的私有人脸识别模型 "{\"faces\":[{\"faceUrl\":\"http://bj.bcebos.com/bucket-0/2796bfc78d45121c10fecfabfae59323/faceTrackingV2/faceTrackingV2/0-0\_face.jpg\",\"image\":\"http://bj.bcebos.com/bucket-0/2796bfc78d45121c10fecfabfae59323/thumbnail/thumbnail\_1s00001.jpg\",\"data\":{\"name\":\"吕行\",\"score\":96.0718765258789},\"frame\_num\":2,\"start\_frame\":1}]}" figure private_face
private_face_image 非tracking版本的私有人脸识别模型 "[{\"image\":\"http://bj.bcebos.com/bucket-0/e7e96761805128f1c11ca8eb808b9dc7/thumbnail/thumbnail\_1s00000.jpg\",\"result\":[{\"brief\":\"陈浩民\",\"score\":96.81122589111328}]}]" figure private_face
logo 公有logo识别模型 "[{\"image\":\"http://bj.bcebos.com/bucket-0/thumbnail\_00001.jpg\",\"timestamp\":1,\"result\":[{\"name\":\"oppo\",\"probability\":0.8}]},{\"image\":\"http://bj.bcebos.com/bucket-0/thumbnail\_00002.jpg\",\"timestamp\":2,\"result\":[{\"name\":\"小米\",\"probability\":0.8}]}]" logo logo
private_logo 私有logo识别模型 "[{\"image\":\"http://bj.bcebos.com/bucket-0/thumbnail\_00001.jpg\",\"timestamp\":1,\"result\":[{\"name\":\"oppo\",\"probability\":0.8}]},{\"image\":\"http://bj.bcebos.com/bucket-0/thumbnail\_00002.jpg\",\"timestamp\":2,\"result\":[{\"name\":\"小米\",\"probability\":0.8}]}]" logo private_logo
textrank_character 对文字识别结果textrank "[{\"keyword\":\"法治\",\"weight\":97.22912879954922},{\"keyword\":\"习近平\",\"weight\":81.47645459300355}]" keyword character
textrank_speech 对语音识别结果textrank "[{\"keyword\":\"主席\",\"weight\":97.35868703342575},{\"keyword\":\"习近平\",\"weight\":95.6200808466852}]" keyword speech
scenario_classify 视频场景分类模型 "{\"results\":[{\"scenario\":\"新闻节目\", \"probability\":\"0.991113007068634\"}]}" scenario scenario_classify
image_classify 图像分类模型 "[{\"image\":\"http://bj.bcebos.com/bucket-0/50cbdc5a5cbe24c840f33bb8256c4168/thumbnail/thumbnail\_1s00000.jpg\",\"timestamp\":0,\"blurScore\":0.89,\"classifyResult\":[{\"probability\":0.9964,\"class_name\":\"人物-主持人\"},{\"probability\":0.8213,\"class\_name\":\"穿戴-领带\"}]}]" entity image_classify
object_detect 物体检测模型 "[{\"image\":\"http://bj.bcebos.com/bucket-0/thumbnail\_1s00000.jpg\",\"timestamp\":0,\"classifyResult\":[{\"keyword\":\"郭志坚\",\"score\":0.698679,\"root\":\"公众人物\"},{\"keyword\":\"人物特写\",\"score\":0.547329,\"root\":\"公众人物\"},{\"keyword\":\"电视屏幕\",\"score\":0.375952,\"root\":\"商品-数码\"}]},{\"image\":\"http://http://bj.bcebos.com/bucket-0/thumbnail\_1s00001.jpg\",\"timestamp\":1,\"classifyResult\":[{\"keyword\":\"人物特写\",\"score\":0.78124,\"root\":\"人物-人物特写\"},{\"keyword\":\"电视屏幕\",\"score\":0.580812,\"root\":\"商品-数码\"}]}]" entity object_detect
face_merge 基于人脸信息的融合模型 "{\"people\":{\"陈赫\":{\"name\":\"陈赫\",\"confidence\":0.78572416305542}},\"zps\":{\"爱情自有天意\":[\"娄艺潇\"]}}" merge face_recognition
video_classify_kg 基于video、title的场景分类 {"result":{"labelNew":[{"subtitle":[{"score":"0.5183947086334229","value":"明星"}],"title":{"score":"0.8902057409286499","value":"娱乐"}}]}} - -
knowledge_graph 知识图谱 {"feedCategory":[{"value":"tvshow","meta":{"type":"level2"}}],"sourceName":[{"type":"kgs:TVShow","value":"奔跑吧兄弟","meta":{"source":["reason","title_mention"]}}],"series":[{"type":"kgs:TVShow","value":"奔跑吧兄弟","meta":{}}],"entity":[{"type":"kgs:EntertainmentPerson","value":"陈赫","meta":{"source":["face"]}},{"type":"kgs:EntertainmentPerson","value":"郑恺","meta":{"source":["face"]}},{"type":"kgs:EntertainmentPerson","value":"王祖蓝","meta":{"source":["face"]}},{"type":"kgs:TVShow","value":"奔跑吧兄弟","meta":{"source":["reason","title_mention"]}}],"starring":[{"actor":{"type":"actor","value":"王祖蓝"}},{"actor":{"type":"actor","value":"陈赫"}},{"actor":{"type":"actor","value":"郑恺"}}]} knowledge_graph knowledge_graph

随着智能内容分析服务的迭代升级,会不断扩展分析场景中间任务类型

分析错误码列表

视频分析失败时,查询视频分析结果会返回分析失败错误信息。目前VCA支持如下错误码:

错误码 错误信息 备注
InvalidMedia media duration/resolution exceeds limit 视频时长/分辨率不满足VCA系统限制,请检查原视频
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 视频分析超时,请先检查原视频,如视频正常则可以重试

其中根据视频时长不同,超时上限也不同:

视频时长 超时上限
<3min 15min
<10min 30min
<30min 1Hour
其它 2Hour

分析结果示例

分析结果:

{
    "results":[
        {
            "type":"figure",
            "result":[
                {
                    "attribute":"艾宝俊",
                    "confidence":75.11,
                    "source":"face_recognition",
                    "time":[
                        {
                            "start":1,
                            "end":4
                        }
                    ]
                },
                {
                    "attribute":"艾宝俊",
                    "confidence":75.11,
                    "source":"private_face",
                    "time":[
                        {
                            "start":1,
                            "end":4
                        }
                    ]
                },
                {
                    "attribute":"艾宝俊",
                    "confidence":100,
                    "source":"knowledge_graph",
                    "time":[
                        {
                            "start":1,
                            "end":4
                        }
                    ]
                }
            ]
        },
        {
            "type":"logo",
            "result":[
                {
                    "attribute":"美拍",
                    "confidence":58.73,
                    "source":"logo",
                    "time":[
                        {
                            "start":4,
                            "end":6
                        }
                    ]
                },
                {
                    "attribute":"美拍",
                    "confidence":58.73,
                    "source":"pivate_logo",
                    "time":[
                        {
                            "start":4,
                            "end":6
                        }
                    ]
                }
            ]
        },
        {
            "type":"keyword",
            "result":[
                {
                    "attribute":"办案",
                    "confidence":64.34,
                    "source":"character",
                    "time":[
                        {
                            "start":4,
                            "end":5
                        }
                    ]
                },
                {
                    "attribute":"新闻",
                    "confidence":26.63,
                    "source":"speech",
                    "time":[
                        {
                            "start":6,
                            "end":6
                        }
                    ]
                },
                {
                    "attribute":"新闻",
                    "confidence":26.63,
                    "source":"title",
                    "time":[
                        {
                            "start":6,
                            "end":6
                        }
                    ]
                }
            ]
        },
        {
            "type":"scenario",
            "result":[
                {
                    "attribute":"新闻节目",
                    "confidence":28.7,
                    "source":"scenario_classify"
                },
                {
                    "attribute":"新闻",
                    "confidence":100,
                    "source":"knowledge_graph"
                }
            ]
        },
        {
            "type":"entity",
            "result":[
                {
                    "attribute":"人物特写",
                    "confidence":58.73,
                    "source":"image_classify",
                    "time":[
                        {
                            "start":4,
                            "end":6
                        }
                    ]
                },
                {
                    "attribute":"人物特写",
                    "confidence":58.73,
                    "source":"object_detect",
                    "time":[
                        {
                            "start":4,
                            "end":6
                        }
                    ]
                }
            ]
        },
        {
            "type":"merge",
            "result":[
                {
                    "attribute":"美拍",
                    "confidence":58.73,
                    "source":"face_recognition",
                    "time":[
                        {
                            "start":4,
                            "end":6
                        }
                    ]
                }
            ]
        },
        {
            "type":"knowledge_graph",
            "result":[
                {
                    "attribute":"林子大(夏雨)",
                    "confidence":100,
                    "source":"knowledge_graph"
                }
            ]
        }
    ]
}