# 图像标签
#### 功能介绍
图像标签服务准确识别自然图片中数百种场景、上千种通用物体及其属性。让智能相册管理、照片检索和分类、基于场景内容或者物体的广告推荐等功能更加直观。使用时用户发送待处理图片，返回图片标签内容及相应置信度。
#### URI
URI格式
POST /v1.0/image/tagging
#### 请求消息
表1请求参数说明 
| 名称        | 是否必选  | 类型      | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|:---|:---|:---|:---|
| image     | false | String  | 与url二选一。 图像数据，base64编码，要求base64编码后大小不超过10MB，最短边至少15px，最长边最大4096px，支持JPEG、PNG、BMP、WEBP格式。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| url       | false | String  | 与image二选一。 图片的URL路径，目前支持： - 公网HTTP/HTTPS URL  - OBS提供的URL，使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权。详情参见[配置OBS服务的访问权限](https://support.huaweicloud.com/api-image/image_03_0037.html)。   说明： - 接口响应时间依赖于图片的下载时间，如果图片下载时间过长，会返回接口调用失败。    - 请保证被检测图片所在的存储服务稳定可靠，推荐使用OBS服务存储图片数据。  - lmage不支持跨区域OBS，OBS的区域需要和服务保持一致。   |
| language  | false | String  | zh：返回标签的语言类型为中文。 en：返回标签的语言类型为英文。 默认值为zh。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| limit     | false | Integer | 最多返回的标签数，默认值：30。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| threshold | false | Float   | 置信度的阈值（0\~100），输入非该范围内值算法即取默认值。 默认值：0。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
   
#### 响应消息
响应参数请参见[表2]。
 表2响应参数说明 
| 名称         | 类型     | 说明                                                                                                                                                                                                                                                                                                                                        |
|:---|:---|:---|
| result     | JSON   | 调用成功时为图像标签内容。 调用失败时无此字段。                                                                                                                                                                                                                                     |
| tags       | List   | 标签列表集合。                                                                                                                                                                                                                                                                                                                                   |
| confidence | Float  | 置信度，取值范围（0\~100）。                                                                                                                                                                                                                                                                                                                         |
| tag        | String | 标签名称。                                                                                                                                                                                                                                                                                                                                     |
| type       | String | 标签的类别。有以下三种类别： - object：实体标签  - scene：场景标签  - concept：概念标签   |
| i18n_tag   | JSON   | 标签的国际化字段。（i18n只是个国际化标志，无特殊含义）。 - zh：中文  - en：英文                                                                                        |
| error_code | String | 调用失败时的错误码，具体请参见[错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。 调用成功时无此字段。                                                                                                                                                                                     |
| error_msg  | String | 调用失败时的错误信息。 调用成功时无此字段。                                                                                                                                                                                                                                       |
   
#### 示例
- 请求示例（方式一：使用图片的BASE64编码）
  ```
  POST https://image.cn-north-1.myhuaweicloud.com/v1.0/image/tagging
  Request Header:  
  Content-Type:application/json
  X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...   
  Request Body:
  {
   "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAcAAAAcgEyAAIAAAAUAAAAjodpAAQAAAABAAAApAAAANAACvyAAAAnEAAK/IAAACcQQWRvYmUgUGhvdG9zaG9wIENTMyBXaW5kb3dzADIwMTc6MTA6MjAgMTA6NDU6MzYAAAAAA6ABAAMAAAAB//8AAKACAAQAAAABAAALIKADAAQAAAABAAAGQAAAAAAAAAAGAQMAAwAAAAEABgAAARoABQAAAAEAAAEeARsABQAAAAEAAAEmASgAAwAAAAEAAgAAAgEABAAAAAEAAAEuAgIABAAAAAEAABAj...",
    "url": "",
    "language": "en",
    "limit": 5,
    "threshold": 60.0
  }
  ```
  
- 请求示例（方式二：使用图片URL）
  ```
  POST https://image.cn-north-1.myhuaweicloud.com/v1.0/image/tagging
     
  Request Header:  
  Content-Type:application/json
  X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...   
  Request Body:
  {
    "image":"",
    "url":"https://<bucketName>.obs.<region>.myhuaweicloud.com/<objectName>",
    "language": "en",
    "limit": 5,
    "threshold": 60.0
  }
  ```
  
- 成功响应示例
  ```
  {
    "result":{
        "tags":[
          {
              "confidence": 38.51,
              "tag":"sky",
              "i18n_tag": 
              {  
                   "en": "sky",  
                   "zh": "天空"       
              },
              "type": "object"
          },
          {
              "confidence": 25.75,
              "tag":"landscape",
              "i18n_tag": 
              {  
                   "en": "landscape",
                   "zh": "风景"
               },
              "type": "scene"
          }
          ]
      }
  }
  ```
  
- 失败响应示例
  ```
  {
      "error_code": "AIS.0014",
      "error_msg": "The JSON format of the input data is incorrect."
  }
  ```
  
 
#### 返回值
- 正常 200
  
- 失败
  
  | 返回值 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  |:---|:---|
  | 400 | - 语义有误，当前请求无法被服务器解析。除非进行修改，否则客户端不应重复提交这个请求。  - 请求参数有误。   |
  | 401 | 当前请求需要用户验证。                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | 403 | 没有操作权限。                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | 404 | 请求失败，在服务器上未找到请求所希望得到的资源。                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | 500 | 服务器遇到了一个未曾预料的状况，导致无法完成对请求的处理。                                                                                                                                                                                                                                                                                                                                                                                                              |
     
  
 
#### 错误码
错误码请参见 [错误码](https://support.huaweicloud.com/api-image/image_03_0010.html)。