Image Tagging (v1.0)

Function

Image Tagging can accurately identify hundreds of scenes and thousands of common objects and their attributes in natural images. It makes intelligent album management, photo retrieval and classification, and scene- or object-based advertising more intuitive. After you upload the image to be processed, Image Tagging returns tags and confidence scores to you.

Prerequisites

Before using Image Tagging, you need to apply for the service and complete authentication. For details, see Applying for a Service and Authentication.

URI

URI format

POST /v1.0/image/tagging

Request Message

Table 1 describes the request parameters.

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
image	false	String	Configure either this parameter or url. Indicates the Base64 character string converted from the image. The size cannot exceed 10 MB. The image resolution of the narrow sides must be greater than 15 pixels, and that of the wide sides cannot exceed 4096 pixels. The supported image formats include JPG, PNG, and BMP.
url	false	String	Configure either this parameter or image. Indicates the URL of an image. The options are as follows: HTTP/HTTPS URLs on the public network OBS URLs. To use OBS data, authorization is required, including service authorization, temporary authorization, and anonymous public authorization. For details, see Configuring the Access Permission for OBSConfiguring the Access Permission for OBS. NOTE: The API response time depends on the image download time. If the image download takes a long time, the API call will fail. Ensure that the storage service where the images to be detected reside is stable and reliable. OBS is recommended for storing image data. The region of OBS must be consistent with that of Image Recognition.
language	false	String	zh: indicates that the language of the returned tag is Chinese. en: indicates that the language of the returned tag is English. The default value is zh.
limit	false	Integer	Indicates the maximum number of tags that can be returned. The default value is 30.
threshold	false	Float	Indicates the threshold of the confidence score. The value ranges from 0 to 100. If you input a value beyond the value range, the default value is used. The default value is 0.

Response Message

Table 2 describes the response parameters.

**Table 2** Parameter description
Parameter	Type	Description
result	JSON	Indicates the content of the image tag when the API is successfully called. This parameter is not included when the API fails to be called.
tags	List	Indicates the list of tags.
confidence	Float	Indicates the confidence score. The value ranges from 0 to 100.
tag	String	Indicates the tag name.
type	String	Indicates the tag type. Possible values are as follows: object: entity tag scene: scenario tag concept: concept tag
i18n_tag	JSON	Indicates the internationalization field of the tag. (i18n is only an internationalization flag and has no special meaning.) zh: Chinese en: English
error_code	String	Indicates the error code of a failed API call. For details, see Error Codes. This parameter is not included when the API is successfully called.
error_msg	String	Indicates the error message of a failed API call. This parameter is not included when the API is successfully called.

Examples

Example request (Method 1: Use a Base64-encoded image.)

POST https://{{Endpoint of Image Recognition}}/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
}

Example request (Method 2: Use the URL redirecting to an image file.)

POST https://{{Endpoint of Image Recognition}}/v1.0/image/tagging
   
Request Header:  
Content-Type:application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...   

Request Body:
{
  "image":"",
  "url":"https://{{OBS path for storing images}}",
  "language": "en",
  "limit": 5,
  "threshold": 60.0
}

Example successful response

{
  "result":{
      "tags":[
        {
            "confidence": 38.51,
            "tag":"sky",
            "i18n_tag": 
            {  
                 "en": "sky",  
                 "zh": "Tag added to the image"
            },
            "type": "object"
        },
        {
            "confidence": 25.75,
            "tag":"landscape",
            "i18n_tag": 
            {  
                 "en": "landscape",
                 "zh": "Tag added to the image"
             },
            "type": "scene"
        }
        ]
    }
}

Example failed response

{
    "error_code": "AIS.0014",
    "error_msg": "The JSON format of the input data is incorrect."
}

Return Value

Normal
200

Abnormal

Return Value	Description
400	The request cannot be understood by the server due to malformed syntax. The client should not repeat the request without modifications. The request parameter is incorrect.
401	The request requires user authentication.
403	No operation permission.
404	The server has not found anything matching the Request-URI.
500	The server encountered an unexpected condition which prevented it from fulfilling the request.