Help Center> Image Recognition> API Reference> Image Recognition APIs> Image Tagging (V2)

Updated on 2022-12-07 GMT+08:00

View PDF

Image Tagging (V2)

Function

Natural images have extensive semantic meanings because one image contains a wide variety of tags. This API can recognize hundreds of scenes and thousands of objects and their properties in natural images, making intelligent album management, picture 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.
By default, the maximum number of concurrent API calls is 10. To increase concurrency, contact Huawei technical support.

URI

URI format

POST /v2/{project_id}/image/tagging

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Specifies the project ID. See Obtaining a Project ID and Name.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Indicates the user token. It is used to obtain the permission to call APIs. For details about how to obtain the token, see Authentication. The value of X-Subject-Token in the response header is the token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
image	No	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 1 pixels, and that of the wide sides cannot exceed 4096 pixels. The supported image formats include JPEG, PNG, BMP, and WEBP.
url	No	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 Access Permissions of 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 image to be detected resides is stable and reliable. OBS is recommended for storing image data. The region of OBS must be consistent with that of Image Recognition.
language	No	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.
threshold	No	Float	Indicates the threshold (0 to 100) of the confidence score. The tags whose confidence score is lower than the threshold will not be returned. Default value: 60. Minimum value: 0 Maximum value: 100 Default value: 0.0
limit	No	Integer	Maximum number of tags that can be returned. The value ranges from 1 to 150.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
result	result object	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.

**Table 5** result parameters
Parameter	Type	Description
tags	Array of ImageTaggingItemBody objects	Indicates the list of tags.

**Table 6** ImageTaggingItemBody parameters
Parameter	Type	Description
confidence	String	Indicates the confidence. The float value is converted into a string and returned. The value ranges from 0 to 100.
type	String	Indicates the tag type. Possible values are as follows: object: entity tag scene: scenario tag concept: concept tag
tag	String	Indicates the tag name.
i18n_tag	i18n_tag object	Indicates the multi-language output of the tag.
i18n_type	i18n_type object	Indicates the multi-language output of the tag type.
instances	Array of ImageTaggingInstance objects	Indicates the object bounding box information. If this parameter is left empty, there is no object bounding box.

**Table 7** i18n_tag parameters
Parameter	Type	Description
zh	String	Indicates the Chinese tag.
en	String	Indicates the English tag.

**Table 8** i18n_type parameters
Parameter	Type	Description
zh	String	Indicates the Chinese tag type.
en	String	Indicates the English tag type.

**Table 9** ImageTaggingInstance parameters
Parameter	Type	Description
bounding_box	Object	Indicates the position of the object bounding box. It contains the following four values: width: width of the bounding box height: height of the bounding box top_left_x: distance from the upper left corner of the bounding box to the vertical axis top_left_y: distance from the upper left corner of the bounding box to the horizontal axis
confidence	String	Indicates the tag confidence. The float value is converted into a string and returned. The float value ranges from 0 to 100.

Status code: 400

**Table 10** Response body parameters
Parameter	Type	Description
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.

Example Requests

endpoint is the request URL for calling an API. Endpoints vary depending on services and regions. For details, see Endpoints.
For example, the endpoint of the service deployed in the CN-Hong Kong region is image.ap-southeast-1.myhuaweicloud.com, the request URL is https://image.ap-southeast-1.myhuaweicloud.com/v2/{project_id}}/image/tagging, and project_id is the project ID. For details, see Obtaining a Project ID and Name.

Method 1: Use a Base64-encoded image.

POST https://{endpoint}/v2/{project_id}/image/tagging

{
  "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...",
  "url" : "",
  "language" : "zh",
  "limit" : 5,
  "threshold" : 70.0
}

Method 2: Use an image URL.

POST https://{endpoint}/v2/{project_id}/image/tagging

{
  "image" : "",
  "url" : "https://BucketName.obs.myhuaweicloud.com/ObjectName",
  "language" : "zh",
  "limit" : 5,
  "threshold" : 70.0
}

Example Responses

Status code: 200

Response for a successful API call:

{
  "result" : {
    "tags" : [ {
      "confidence" : "37.51",
      "instances" : [ {
        "confidence" : "92.38",
        "bounding_box" : {
          "height" : 133.32496056189905,
          "top_left_x" : 53.134917332575874,
          "top_left_y" : 254.21347984900842,
          "width" : 117.5866567171537
        }
      } ],
      "tag": "Person",
      "i18n_tag" : {
        "en" : "person",
        "zh": "Chinese character for person"
      },
      "type": "Human",
      "i18n_type" : {
        "en" : "Human",
        "zh": "Chinese characters for human"
      }
    } ]
  }
}

Status code: 400

Response for a failed API call:

{
  "error_code" : "AIS.0005",
  "error_msg" : "The service does not exist."
}

Status Codes

Status Code	Description
200	Response for a successful API call
400	Response for a failed API call

Error Codes

For details, see Error Codes.

Parent topic: Image Recognition APIs

Previous topic: Image Recognition APIs

Next topic: APIs (Deprecated)

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot