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

Updated on 2024-04-02 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 recognizes 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.

URI

URI format

POST /v2/{project_id}/image/tagging

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	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	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 4,096 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
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	BoundingBoxFloat Object	Indicates the location of the object bounding box.
confidence	String	Indicates the tag confidence. The float value is converted into a string and returned. The float value ranges from 0 to 100.

**Table 10** BoundingBoxFloat
Parameter	Type	Description
width	Double	Width of the bounding box
height	Double	Height of the bounding box
top_left_x	Double	Distance from the upper left corner of the bounding box to the vertical axis
top_left_y	Double	Distance from the upper left corner of the bounding box to the horizontal axis

Status code: 400

**Table 11** 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 the Base64 encoded value of the image. The image tags in Chinese and their confidence scores are returned. The confidence threshold is 70.

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

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

Method 2: Use the URL of the image. The image tags in Chinese and their confidence scores are returned. The confidence threshold is 70.

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: Recapture Detection

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