Searching for Images

Function

You can use the API to search for similar images from the image library.

URI

URI format
POST /v1/{project_id}/{instance_name}/image/search

Parameter description

Parameter	Mandatory	Description
instance_name	Yes	Instance name
project_id	Yes	Project ID

Request Body

Table 1 describes the request parameters.

**Table 1** Request parameter description
Parameter	Mandatory	Type	Description
file	Configure either file or path, or both.	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. Configure either this parameter or path. If both parameters exist, file prevails.
path	Configure either file or path, or both.	String	Image URL, which is the index ID of an image in the image library. Configure either this parameter or file. If both parameters exist, file prevails.
limit	No	Integer	Number of retrieved images. The value is an integer ranging from 1 to 100. The default value is 10.
offset	No	Integer	Offset, which specifies the start position of the search result. The value is an integer greater than or equal to 0. The default value is 0.
tags	No	JSON	Custom image tag. A maximum of 10 tags can be customized. The tags are key-value pairs. To add a tag name (key), do as follows: Log in to the Image Search management console, click Create Instance, and configure Customize Tag. Log in to the Image Search management console. Go to the Instance Management page, and click an instance name. On the Instance Details page that is displayed, configure Customize Tag. This parameter is mandatory when the image tag is used for search.
isCrop	No	Boolean	Whether to specify an area (parameter box) in an image for search. The default value is false. This parameter is valid only for certain models. true: Specify an area (parameter box) in an image for search. false: Use the entire image to search.
box	No	JSON	This parameter is mandatory when isCrop is set to true, indicating that an area is specified for search.
x	No	Integer	Minimum value of the horizontal (x) coordinate in an area, in pixels
y	No	Integer	Minimum value of the vertical (y) coordinate in an area, in pixels
width	No	Integer	Width of an area, in pixels
height	No	Integer	Height of an area, in pixels

Response Body

Table 2 describes the response parameters.

**Table 2** Response parameter description
Parameter	Type	Description
count	Integer	Total number of search records
result	List	Search result details
path	String	Path of the searched image
sim	Float	Similarity between the original image and the searched image. The closer the value reaches 1, the more similar the images are.
tags	JSON	Custom tag name and content
error_code	String	Error code when the API call fails. This parameter is not included when the API call succeeds.
error_msg	String	Error message when the API call fails. This parameter is not included when the API call succeeds.

Samples

Sample request

Method 1: Use a Base64-encoded image.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json 
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body: 
{ 
"limit":10,
"offset":0,
"file":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAcAAAAcgEyAAIAAAAUAAAAjodpAAQAAAABAAAApAAAANAACvyAAAAnEAAK/IAAACcQQWRvYmUgUGhvdG9zaG9wIENTMyBXaW5kb3dzADIwMTc6MTA6MjAgMTA6NDU6MzYAAAAAA6ABAAMAAAAB//8AAKACAAQAAAABAAALIKADAAQAAAABAAAGQAAAAAAAAAAGAQMAAwAAAAEABgAAARoABQAAAAEAAAEeARsABQAAAAEAAAEmASgAAwAAAAEAAgAAAgEABAAAAAEAAAEuAgIABAAAAAEAABAj..."
}

Method 2: Use an image URL.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json 
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body: 
{
 "limit":10,
 "offset":0,
 "path":"https://BucketName.obs.myhuaweicloud.com/image/test1.jpg"
}

Method 3: Use an image tag.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json 
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body: 
{
 "limit":10,
 "offset":0,
  "tags":{
         "test-tags":"test-image"
  }
}

Method 4: Use a Base64-encoded image and its tag.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json 
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body: 
{ 
"limit":10,
"offset":0,
"file":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAcAAAAcgEyAAIAAAAUAAAAjodpAAQAAAABAAAApAAAANAACvyAAAAnEAAK/IAAACcQQWRvYmUgUGhvdG9zaG9wIENTMyBXaW5kb3dzADIwMTc6MTA6MjAgMTA6NDU6MzYAAAAAA6ABAAMAAAAB//8AAKACAAQAAAABAAALIKADAAQAAAABAAAGQAAAAAAAAAAGAQMAAwAAAAEABgAAARoABQAAAAEAAAEeARsABQAAAAEAAAEmASgAAwAAAAEAAgAAAgEABAAAAAEAAAEuAgIABAAAAAEAABAj...",
"tags":{
         "test-tags":"test-image"
}
}

Method 5: Use an image URL and tag.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body:
{
 "limit":10,
 "offset":0,
 "path":"https://BucketName.obs.myhuaweicloud.com/image/test1.jpg",
 "tags":{
         "test-tags":"test-image"
 }
}

Method 6: Specify an area for search.

POST https://{endpoint}/v1/{project_id}/{instance_name}/image/search

Request Header:
Content-Type:application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body:
{
 "limit":10,
 "offset":0,
 "path":"https://BucketName.obs.myhuaweicloud.com/image/test1.jpg",
 "box": {
    "x": 100,
    "y": 200,
    "height": 20,
    "width": 50
 },
}

Successful sample response

{
    "count":2,
    "result":[
        {
            "tags":{
                "test-tags":"test-image"
            },
            "path":"https://BucketName.obs.myhuaweicloud.com /CBL025106G/CBL025106G_2.JPG",
            "sim":0.51263
        },
        {
            "path":"https://BucketName.obs.myhuaweicloud.com /CBL025106G/CBL025106G_3.JPG",
            "sim":0.49531
        }
    ]
}

Failed sample response

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

Status Codes

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. Incorrect request parameters.
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.