Help Center/ ImageSearch/ API Reference/ APIs/ Adding an Image
Updated on 2023-12-13 GMT+08:00
View PDF
Share

Adding an Image

Function

You can use the API to import an image to the image library. The image can be stored in an OBS bucket in the same region or in the request body. Only the images in the image library can be searched for.

  • To add or search for an image stored in an OBS bucket, authorize the OBS bucket first. The specific steps are as follows:

    On the Instance Management page, click Offline Import in the Operation column. The Offline Import page is displayed. Select the OBS bucket where data is stored and click Authorize. When Authorize becomes unavailable, OBS authorization is completed. For details about offline import, see Getting Started > Offline Import.

URI

POST /v1/{project_id}/{instance_name}/image

Table 1 Path parameters

Name

Mandatory

Type

Description

project_id

Yes

String

Project ID. See Obtaining a Project ID and Name.

instance_name

Yes

String

Instance name

Request Message

Table 2 Request header parameters

Name

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

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

Name

Mandatory

Type

Description

file

No

String

Base64 character string converted from the image. Only the JPEG, JPG, PNG, and BMP formats are supported. The image resolution of the narrow sides of an image must be greater than or equal to 100 pixels, and that of the wide sides cannot exceed 2048 pixels.

path

Yes

String

Image URL. This parameter is mandatory and is used as the ID of an image in the image library.

NOTE:
  • If the file field is specified, the image is obtained from file and path is used as the image index ID. If the file field does not exist or is unspecified, the image needs to be downloaded. In this case, path is the address for downloading the image (currently, images can be downloaded only from OBS in the same region as Image Search). path is also used as the image index ID.

tags

No

Object

Custom image tag. The total number of keys of each image cannot exceed 10, but the number of values corresponding to each key is not limited. For example, if a key is animal, the corresponding values can be cat, dog, and bird.

To add a tag name (key), do as follows:

  1. Log in to the ImageSearch management console, click Create Instance, and configure Customize Tag.
  2. On the instance management tab page, click an instance name. On the displayed basic information page, add a custom tag.

Response Parameters

Status code: 200

Table 4 Response body parameter

Name

Type

Description

result

String

Calling result when the API call succeeds. This parameter is not included when the API fails to be called.

Status code: 400

Table 5 Response body parameter

Name

Type

Description

error_code

String

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

Error message when the API call fails.

This parameter is not included when the API is successfully called.

Example Requests

  • Method 1: Use the Base64 code and URL of an image to import the image index library. The image URL is /../image.jpg. 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image

{
  "path" : "/../image.jpg",
  "file" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAA..."
}
  • Method 2: Use the URL to import an image to the image index library. The image URL is https://bucketName.obs.myhuaweicloud.com/image/test1.jpg. 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image

{
  "path" : "https://bucketName.obs.myhuaweicloud.com/image/test1.jpg"
}
  • Method 3: Use the image Base64 code and tags to import the image to the image index library. The URL of the image is https://bucketName.obs.myhuaweicloud.com/image/test1.jpg. 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image

{
  "path" : "https://bucketName.obs.myhuaweicloud.com/image/test1.jpg",
  "file" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAA...",
  "tags" : {
    "test-tags" : "test-image"
  }
}
  • Method 4: Use the image URL and tags to import the image to the image index library. The image URL is https://bucketName.obs.myhuaweicloud.com/image/test1.jpg. 
    POST https://{endpoint}/v1/{project_id}/{instance_name}/image

{
  "path" : "https://bucketName.obs.myhuaweicloud.com/image/test1.jpg",
  "tags" : {
    "test-tags" : "test-image"
  }
}

Example Response

Status code: 200

Example of a successful response

{
  "result" : "Success"
}

Status code: 400

Example of a failed response

{
  "error_code" : "IS.0003",
  "error_msg" : "Arguments of path can not be null."
}

Status Code

Status Code

Description

200

Successful response

400

Failed response

Error Code

For details, see Error Codes.

Parent topic: APIs