# 名人识别-RunCelebrityRecognition
#### 功能介绍
分析并识别图片中包含的敏感人物、明星及网红人物，返回人物信息及人脸坐标。
#### 前提条件
- 使用名人识别服务之前需要您完成[服务申请](https://support.huaweicloud.com/api-image/image_03_0018.html)和[认证鉴权](https://support.huaweicloud.com/api-image/image_03_0003.html)。
- 图像识别服务属于公有云服务，线上用户资源共享，如果需要多并发请求，请提前[联系我们](https://www.huaweicloud.com/service/contact.html)。
 
#### 调试
您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=Image&api=RunCelebrityRecognition)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
#### URI
POST /v2/{project_id}/image/celebrity-recognition
表1路径参数 
| 参数         | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|:---|
| project_id | 是    | String | **参数解释：** 用户的项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母和数字组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 |
   
#### 请求参数
表2请求Header参数 
| 参数           | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                              |
|:---|:---|:---|:---|
| X-Auth-Token | 是    | String | **参数解释：** 用户Token。用于获取操作API的权限。获取方法请参见[获取Token接口](https://support.huaweicloud.com/api-image/image_03_0003.html)，响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 |
   
表3请求Body参数 
| 参数        | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|:---|
| image     | 否    | String | **参数解释：** 与url二选一。 图像数据，base64编码。 **约束限制：** 不涉及。 **取值范围：** 要求base64编码后大小不超过10M，最短边至少1px，最长边最大10000px，支持JPEG/PNG/BMP/WEBP格式。 **默认取值：** 不涉及。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| url       | 否    | String | **参数解释：** 与image二选一。 图片的URL路径，目前支持： - 公网HTTP/HTTPS URL  - OBS提供的URL，使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权。详情参见[配置OBS服务的访问权限](https://support.huaweicloud.com/api-image/image_03_0037.html)。   **约束限制：** - 接口响应时间依赖于图片的下载时间，如果图片下载时间过长，会返回接口调用失败。    - 请保证被检测图片所在的存储服务稳定可靠，推荐使用OBS服务存储图片数据。  - lmage不支持跨区域OBS，OBS的区域需要和服务保持一致。   **取值范围：** 不涉及。 **默认取值：** 不涉及。 |
| threshold | 否    | Float  | **参数解释：** 置信度的阈值（0\~1），低于此置信数的标签，将不会返回。 **约束限制：** 不涉及。 **取值范围：** 0-1。 **默认取值：** 0.9。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
   
#### 响应参数
**状态码： 200**
表4响应Body参数 
| 参数     | 参数类型                                                                                                       | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|:---|:---|:---|
| result | Array of [CelebrityRecognitionResultBody] objects | **参数解释：** 用户Token。用于获取操作API的权限。获取方法请参见[获取Token接口](https://support.huaweicloud.com/api-image/image_03_0003.html)，响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 调用成功时表示调用结果。 调用失败时无此字段。 |
   
 表5CelebrityRecognitionResultBody 
| 参数          | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|:---|:---|:---|
| confidence  | Float  | **参数解释：** 置信度。 **约束限制：** 不涉及。 **取值范围：** 0-1。 **默认取值：** 不涉及。                                                                                                                                                                                              |
| face_detail | Object | **参数解释：** 名人的面部信息，包括4个值： h：人脸区域高度 w：人脸区域宽度 x：人脸区域左上角到y轴距离 y：人脸区域左上角到x轴距离 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 |
| label       | String | **参数解释：** label为对应的名人信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。                                                                                                                                                                                  |
   
**状态码： 400**
表6响应Body参数 
| 参数         | 参数类型   | 描述                                                                                                                                                                                                                                                      |
|:---|:---|:---|
| error_code | String | **参数解释：** 调用失败时的错误码，具体请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。 调用成功时无此字段。 **取值范围：** 不涉及。 |
| error_msg  | String | **参数解释：** 调用失败时的错误信息。 调用成功时无此字段。 **取值范围：** 不涉及。                                                                          |
   
#### 请求示例
![](https://support.huaweicloud.com/api-image/public_sys-resources/note_3.0-zh-cn.png)
- "endpoint"即调用API的请求地址，不同服务不同区域的"endpoint"不同，具体请参见[终端节点](https://support.huaweicloud.com/api-image/image_03_0032.html)。
  例如，服务部署在"华北-北京四"区域的"endpoint"为"image.cn-north-4.myhuaweicloud.com"，请求URL为"https://image.cn-north-4.myhuaweicloud.com/v2/{project_id}}/image/celebrity-recognition"，"project_id"为项目ID，获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-image/image_03_0035.html)。
  
 
- 方式一：使用图片的BASE64编码，识别图中人物，返回人物信息及人脸坐标，置信度的阈值为0.48。
  ```
  POST https://{endpoint}/v2/{project_id}/image/celebrity-recognition
  {
    "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...",
    "url" : "",
    "threshold" : 0.48
  }
  ```
  
- 方式二：使用图片URL，识别图中人物，返回人物信息及人脸坐标，置信度的阈值为0.48。
  ```
  POST https://{endpoint}/v2/{project_id}/image/celebrity-recognition
  {
    "image" : "",
    "url" : "https://BucketName.obs.myhuaweicloud.com/ObjectName",
    "threshold" : 0.48
  }
  ```
  
 
#### 响应示例
**状态码： 200**
成功响应结果
```
{
  "result" : [ {
    "confidence" : 0.44977834820747375,
    "face_detail" : {
      "h" : 280,
      "w" : 186,
      "x" : 163,
      "y" : 117
    },
    "label" : "xxx"
  } ]
}
```
**状态码： 400**
失败响应结果
```
{
  "error_code" : "AIS.0005",
  "error_msg" : "The service does not exist."
}
```
#### 状态码
| 状态码 | 描述      |
|:---|:---|
| 200 | 成功响应结果。 |
| 400 | 失败响应结果。 |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。