人脸识别REST API帮助文档_v1.04

媒体云人脸识别 REST API帮助文档

V1.04

发布日期：2013年12月30日

百度开发者中心

(版权所有,翻版必究)

百度在线网络技术（北京）有限公司

- 1 -

媒体云人脸识别REST API帮助文档

修订记录

2013.09.29 2013.10.11 2013.10.12 2013.12.19 2013.12.30 V1.00版 V1.01版 统一对外请求地址 V1.02版 调整错误码 V1.03版 修改通用SDK跳转链接 V1.04版本 修改检测API描述明显错误

百度在线网络技术（北京）有限公司 - 2 -

媒体云人脸识别REST API帮助文档

目录

一、概述........................................................................................................................ 4 二、媒体云人脸识别REST API使用说明 ................................................................... 4

2.1 开启人脸识别服务 ......................................................................................... 4 2.2 开通媒体云人脸识别 API权限 ..................................................................... 7 2.3 获取access_token步骤 .................................................................................. 7 2.4 API请求方式说明 ............................................................................................ 9 三、媒体云人脸识别API列表 .................................................................................. 10

3.1人脸检测 ........................................................................................................ 10

3.1.1参数说明 .............................................................................................. 10 3.1.2具体示例 .............................................................................................. 11

四、媒体云人脸识别API错误码总表 ...................................................................... 12

百度在线网络技术（北京）有限公司 - 3 -

媒体云人脸识别REST API帮助文档

一、概述

百度媒体云人脸识别服务依托百度世界领先的人脸识别算法，提供了（1）人脸及五官几何位置定位功能；（2）人脸图像的性别、表情等人脸属性分析功能。 人脸识别服务提供通过REST API的方式来使用人脸识别服务，本文档描述了使用人脸识别服务REST API的方法。

除了原生的REST（Representational State Transfer，即“表述性状态转移”） API之外，人脸识别服务还提供了ANDROID、IOS、WP7、JAVA及PHP多种平台的SDK来帮助开发者缩短开发周期，具体请参考“SDK”部分相关内容(开发者中心通用SDK)。

二、媒体云人脸识别REST API使用说明

说明：开发者中心管理控制台可以通过开发者中心首页右上角“消息”旁边的已标记选项进入，如图1红框所示。

图 1管理控制台入口

2.1 开启人脸识别服务

使用媒体云人脸服务之前，您须按照本节描述的步骤来完成服务的开启，后台服务的注册。 通过开发者中心“管理控制台”，进入“我的应用列表”，创建应用。 （1） 进入“管理控制台”

百度在线网络技术（北京）有限公司 - 4 -

媒体云人脸识别REST API帮助文档

图 2进入管理控制台

（2） 创建应用test,点击“创建应用”

图 3 创建应用

（3） 填写应用名称”test”以及应用类型

图 4填写创建应用信息

百度在线网络技术（北京）有限公司

- 5 -

媒体云人脸识别REST API帮助文档

（4） 创建应用成功，点击左侧“媒体云”开启媒体云人脸识别服务

图 5 申请使用人脸识别服务

（5） 填写使用场景和申请理由

图 6 人脸服务申请信息填写

（6） 开启服务成功后，可以在控制台来使用人脸服务的统计分析功能。

图7 人脸服务统计功能界面

百度在线网络技术（北京）有限公司 - 6 -

媒体云人脸识别REST API帮助文档

2.2 开通媒体云人脸识别 API权限

媒体云人脸识别 API所有REST API都首先需要获取Access Token。Access Token是用户身份验证和授权的凭证。详细信息请参考百度开发者中心帮助文档的OAuth介绍部分。媒体云人脸识别采用的是Client Credentials授权方式，即采用应用公钥、密钥获取Access Token，适用于任何带server类型应用，通过此授权方式获取Access Token仅可访问平台授权类的接口，详见Client Credentials授权说明。

2.3 获取access_token步骤

（1） 如果您已是百度用户，请您访问百度开发者中心并使用百度账号直接登录。如果您

还不是百度用户，请您先访问百度Passport，填写注册邮箱和密码并激活成为百度用户，然后访问百度开发者中心使用百度账号登录。

（2） 您需要创建一个应用以获取API Key（client_id）和Secret Key（client_secret），

申请方式见创建应用。

说明：目前创建应用入口如下截图红框所示：

图 8进入控制台 （3） 创建应用之后，您可以从管理中心进入相应应用得到API Key（client_id）和Secret

Key（client_secret）。  基本信息页

从管理控制台进入创建的应用，如下图所示，API Key（client_id）和Secret Key（client_secret）即显示于其中, ID即为应用id（appid）。

百度在线网络技术（北京）有限公司 - 7 -

媒体云人脸识别REST API帮助文档

图 9 应用基本信息

（4） 根据百度OAuth的Client Credentials授权方式获取access_token。百度OAuth的Client

Credentials和其他授权方式的说明见百度OAuth介绍的“百度支持的OAuth授权”部分。

https://openapi.baidu.com/oauth/2.0/token?

grant_type=client_credentials&

client_id=xxxxx

client_secret=yyyyyy

其中，grant_type的值固定为client_credentials，client_id即为（3）中截图所示的 API Key的值，client_secret即为（3）中截图所示的Secret Key的值。更为详细的介 绍请参见Client Credentials授权说明。

响应如下所示，其中access_token字段即为请求REST API所需的令牌, access_token有效期一般为一个月，开发者需要对access_token，进行有效性判断，过期需重新申请access_token。

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { \"access_token\": \"1.a6b7dbd428f731035f771b8d15063f61.800.1292922000-2346678-124328\ \"expires_in\": 800, \"session_key\": \"ANXxSNjwQDugf8615OnqeikRMu2bKaXCdlLxn\ \"session_secret\": \"248APxvxjCZ0VEC43EYrvxqaK4oZExMB\} 百度在线网络技术（北京）有限公司 - 8 -

媒体云人脸识别REST API帮助文档

2.4 API请求方式说明

 目前人脸检测接口支持POST和GET方式。

 媒体云人脸识别 REST API的所有参数在传入时应当使用：UTF-8编码。  URL格式

https://openapi.baidu.com/rest/2.0/media/v1/face/{request_type}?{query_string}  参

数说明 参数名称 request_type query_string  HTTP GET和POST方式使用说明 https://openapi.baidu.com/rest/2.0/media/v1/face/{request_type}?{query_strinURL g} 描述 MEDIA REST API操作方法名称，对应操作说明：detect为人脸检测。 放在HTTP头部传入的参数，必须经过UrlEncode编码。 请求方式 请求参数 GET 全部携带在HTTP请求头部的query_string中。 POST 既可携带在query_string中，也可携带在HTTP Body中  携带在 query_string 中的参数的值，必须进行 UrlEncode 编码；  携带在HTTPBody中的参数，需要进行UrlEncode编码。 注:HTTP URL长度有限，若参数值长度过长，建议将参数放在HTTP Body中进行传输。 application/x-www-form-urlencoded HTTP BODY 注意 不携带HTTP BODY 如果HTTP BODY和query_string存在相同的参数，则以query_string中的参数为准。  使用示例 1. GET请求：

说明：用HTTP GET 请求方式发送两个参数：access_token =xxxx和url =xxxx。

https://openapi.baidu.com/rest/2.0/media/v1/face/detect?access_token=urlencode(xxxxx)& url =urlencode(xxxxxx)

2. POST请求：

说明：用HTTP POST方式发送两个参数：access_token =xxxx和url= xxxx。

百度在线网络技术（北京）有限公司

- 9 -

媒体云人脸识别REST API帮助文档

POST /rest/2.0/media/v1/face User-Agent: curl/7.12.1 (x86_-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6 Pragma: no-cache Accept: */* Host:openapi.baidu.com Content-Type:application/x-www-form-urlencoded Content-Length:123 access_token =urlencode(xxxx)&url =urlencode(xxxx)

 API响应格式说明 返回 HTTP状态码 HTTP BODY 正常请求 200 API响应内容(json) 异常请求 200 异常请求的返回值为json字符串。 例如： { “error_code”:80001, “error_msg”:” Invalid Parameter!” } 说明： -error_code:错误码； -error_msg:错误描述信息； 三、媒体云人脸识别API列表

3.1人脸检测 3.1.1参数说明

功能 Http请求方式 Url 输入参数 https://openapi.baidu.com/rest/2.0/media/api/v1/face/detect http/1.1 参数名称 access_token 参数类型 string string string 是否必须 是 是 否 描述 访问令牌，开发者准入标识，HTTPS调用时必须使用（见2.1节说明） 要处理的图片地址(需要经过urlencode) 离线请求回调地址，人脸服务收到离线请求后，将立即返回一个session_id，处理完成后将检测百度在线网络技术（北京）有限公司

- 10 -

对用户提交的图片数据进行人脸检测 Get/Post url callback_url 媒体云人脸识别REST API帮助文档

结果通知callback_url 返回参数 成功 失败 参数名称 error_code error_msg 参数类型 int string Json数组 是否必须 否 否 是 否 否 否 描述 错误码, 如果不出错, 则返回值没有该字段。

错误提示, 如果不出错, 则返回值没有该字段。 在原图片中检测到的人脸数组 检测到人脸属性：性别和笑脸 检测到的人脸id 人脸位置：中心点坐标，宽和高 Face attribute face_id position json string json img_id string 是 当前图片id url string 是 图片url session_id string 是 人脸服务生成的请求id，可通过该id查询处理结果 img_width string 是 图片宽度 img_height string 是 图片高度 3.1.2具体示例

请求示例 注意：query string 需要先进行urlencode。 curl-v\"https://openapi.baidu.com/rest/2.0/media/v1/face/detect?access_token=3.ad2ee1e9b351cd800fd62bddc8bef016.2592000.1377163536.4212382003-260146&url=http://c.hiphotos.bdimg.com/album/s%3D800/sign=6bd70c1da044ad342abf8a87e0a00c08/8d94eef01f3a29d7017b3e9825bc315d607c71.jp” 返回示例 成功 { \"face\": //在原图片中检测到的人脸数组 [{ “attribute”{ \"gender\": { //检测到的人脸的性别 \"value\": \"male\" //人脸性别结果 \"confidence\":”1.0” , //性别的置信度 }， \" smiling \": { //检测到的笑脸 \"confidence\":”1.0” //笑脸的置信度 }， }, \"face_id\": \"ffffff32c1f3813f0944f52427ed060b\检测到的人脸的id - 11 -

百度在线网络技术（北京）有限公司

媒体云人脸识别REST API帮助文档

\"position\": { //检测到的人脸的位置，坐标均进行了归一化，值在0~1之间 \"center\": { \"x\":” 0.591000” , //人脸区域中心x坐标, \"y\": “0.267000”}, //人脸区域中心y坐标 \"width\":”0.181290” ,//人脸区域宽度 \"height\": “0.120600”, //人脸区域高度 \"eye_left\": { \"x\":” 0.556230”,//左眼x坐标 \"y\": “0.230250”//左眼y坐标 }, \"eye_right\": { \"x\": “0.638620”,//右眼x坐标 \"y\": “0.244190”//右眼y坐标 }, \"mouth\": { \"x\":”0.574910”,//嘴巴中心x坐标 \"y\":” 0.301350”,//嘴巴中心y坐标 }, } }], \"img_id\": \"966f0f32c1f3813f0944f52427ed060b\图片id \"url\":”” //请求中的图片url “session_id”:” 966f0f32c1f3813f0944f52427jjjkkk” //唯一标识请求 “img_width”:”320” //图片宽度 “img_height”:”240” //图片高度 } 失败 {\"error_code\":xxx, \" error_msg\":\"yyyy\四、媒体云人脸识别API错误码总表

说明：所属接口列，表明该错误码会在哪些接口中出现，1：检测。 错误码 无 70001 70503 70131 70132 70133 错误信息 无 Invalid Parameter! Service Unavailable! Internal Error! Can not access image! Quota not enough! 备注 没有错误 请求参数错误 人脸服务不可用 内部处理错误 不能访问图片url 人脸识别API配额不足 所属接口 1 1 1 1 1 百度在线网络技术（北京）有限公司 - 12 -