Updated on 2024-04-02 GMT+08:00

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.