This topic describes the syntax of the SearchByPic operation and provides examples of this operation. You can call this operation to search for images by image on an Image Search Instance.
Description
This operation searches for images by image name on an Image Search instance.
QPS limits
The maximum number of queries per second is displayed in the Image Search console. The upper limit is specified when you purchase the instance. You can set the upper limit to 5 QPS or 10 QPS.
SDK release notes
The Image Search SDK has been upgraded to version 3.1.1, which supports multi-subject recognition and similarity scores. For more information, see Image Search SDK for Java.
Debugging
Request parameters
Name | Type | Required | Example | Description |
---|---|---|---|---|
InstanceName | String | Yes | demoinstance1 |
The name of the Image Search instance. The name can be up to 20 characters in length. |
PicContent | String | Yes | xxxx |
The image file. The image file is encoded in Base64.
|
CategoryId | Integer | No | 88888888 |
The category of the product. For more information, see Category references.
|
Crop | Boolean | No | true |
Specifies whether to recognize the subject in the image and search for images based on the recognized subject. Valid values: true and false. Default value: true.
|
Region | String | No | 280,486,232,351 |
The subject area of the image. Specify the subject area in the following format: Note
|
Num | Integer | No | 10 |
The number of images to return on each page. Valid values: 1 to 100. Default value: 10. |
Start | Integer | No | 0 |
The number of the image to return. Valid values: 0 to 499. Default value: 0. |
Filter | String | No | int_attr=1000 AND str_attr="value1" |
The filter conditions. int_attr supports the following operators: >, >=, <, <=, and =. str_attr supports the following operators: = and !=. You can set the logical operator between conditions to AND or OR. Examples:
|
Response parameters
Name | Type | Example | Description |
---|---|---|---|
Msg | String | success |
The error message returned. |
Head | Object |
The summary of the search result. |
|
DocsFound | Integer | 10 |
The number of images returned. |
DocsReturn | Integer | 10000 |
The number of images that match the search conditions on the Image Search instance. |
SearchTime | Integer | 95 |
The time it takes to complete the search process. Unit: milliseconds. |
RequestId | String | B3137727-7D6E-488C-BA21-0E034C38A879 |
The ID of the request. |
Auctions | Array of Auction |
The product descriptions returned. |
|
PicName | String | 2092061_1.jpg |
The name of the image. |
IntAttr | Integer | 2 |
The attribute, which is an integer. |
CategoryId | Integer | 8888888 |
The category of the image. |
ProductId | String | 2092061_1 |
The ID of the product. |
StrAttr | String | 2 |
The attribute, which is a string. |
SortExprValues | String | 5.37633353624177e+24;0 |
The score information about the image. Note
|
CustomContent | String | zidingyi |
The user-defined content. |
Score | Float | 1 |
The similarity score of the searched image. Valid values: 0 to 1. Note To use this feature, you must upgrade the SDK to version 3.1.1.
|
Code | Integer | 0 |
The error code returned.
|
PicInfo | Object |
The information such as the system-selected category and result of subject recognition. |
|
Region | String | 280,486,232,351 |
The result of subject recognition. The subject area of the image, in the format of x1,x2,y1,y2. Specifically, x1 and y1 specify the upper-left pixel, and x2 and y2 specify the lower-right pixel. If a subject area is specified in the request, the specified subject area prevails. |
CategoryId | Integer | 88888888 |
The category selected by the system. If a category is specified in the request, the specified category prevails. |
MultiRegion | Array of reg |
The recognized subjects. Note To use this feature, you must upgrade the SDK to version 3.1.1.
|
|
Region | String | 280,486,232,351 |
The result of subject recognition. The subject area of the image, in the format of x1,x2,y1,y2. Specifically, x1 and y1 specify the upper-left pixel, and x2 and y2 specify the lower-right pixel. If a subject area is specified in the request, the specified subject area prevails. |
AllCategories | Array of Category |
The categories that are supported by the system. |
|
Name | String | other |
The name of the category. |
Id | Integer | 88888888 |
The ID of the category. |
Success | Boolean | true |
Indicates whether the request is successful. |
Examples
Sample requests
{
"InstanceName": "demoinstance",
"PicContent": "${Base64ImageContent}"
}
Sample success responses
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"Auctions" : [ {
"CategoryId" : 0,
"PicName" : "demo",
"SortExprValues" : "7.33136443711219e+24;0",
"Score" : 1.0,
"ProductId" : "demo"
} ],
"Head" : {
"DocsReturn" : 1,
"DocsFound" : 1,
"SearchTime" : 155
},
"PicInfo" : {
"CategoryId" : 0,
"Region" : "111,697,113,774",
"AllCategories" : [ {
"Name" : "Tops",
"Id" : 0
}, {
"Name" : "Dress",
"Id" : 1
}, {
"Name" : "Bottoms",
"Id" : 2
}, {
"Name" : "Bag",
"Id" : 3
}, {
"Name" : "Shoes",
"Id" : 4
}, {
"Name" : "Accessories",
"Id" : 5
}, {
"Name" : "Snack",
"Id" : 6
}, {
"Name" : "Makeup",
"Id" : 7
}, {
"Name" : "Bottle",
"Id" : 8
}, {
"Name" : "Furniture",
"Id" : 9
}, {
"Name" : "Toy",
"Id" : 20
}, {
"Name" : "Underwear",
"Id" : 21
}, {
"Name" : "Digital device",
"Id" : 22
}, {
"Name" : "Other",
"Id" : 88888888
} ],
"MultiRegion" : [ {
"Region" : "604,1814,451,1358"
}, {
"Region" : "843,1615,687,1138"
} ]
},
"RequestId" : "D61D869E-E92A-447F-AD67-9234F999E516",
"Msg" : "success",
"Success" : true,
"Code" : 0
}
Error codes
HttpCode | Error code | Error message | Description |
---|---|---|---|
400 | BadRequest | The request has invalid parameters. | The error message returned because a parameter is set to an invalid value. |
400 | InstanceStatusError | Your instance is unavailable. | The error message returned because the instance is unavailable. |
400 | InvalidInstance | The specified instance name is invalid. | The error message returned because the instance name is invalid. |
400 | NoCaretSeperator | The body content is missing the ^ separator. | The error message returned because specific symbols are missing in the request body. |
400 | EmptyMeta | The body content has an empty meta field. | The error message returned because the request body contains empty fields. |
400 | InvalidMetaItem | The meta field is invalid. | The error message returned because the meta field is set to an invalid value. |
400 | NoPicList | The body content is missing the pic_list parameter. | The error message returned because the pic_list field is empty. |
400 | InvalidPicList | The specified pic_list parameter is invalid. | The error message returned because the pic_list field is set to an invalid value. |
400 | InvalidCategory | The specified category is invalid. | The error message returned because the category ID is invalid. |
400 | OverflowMaxResultNum | The specified number of total results exceeds the maximum of 500. | The error message returned because the specified number of images to return exceeds the upper limit, which is 500. |
400 | OverflowMaxReturnNum | The specified number of results for each request exceeds the maximum of 100. | The error message returned because the specified number of images to return in a single call exceeds the upper limit, which is 100. |
400 | InvalidNumParameter | The specified parameter num is invalid. | The error message returned because the num field is set to an invalid value. |
400 | InvalidIntAttr | The specified int_attr field is invalid. | The error message returned because the int filter field is set to an invalid value. |
400 | UnsupportedPicFormat | The specified image format is invalid. | The error message returned because the image format is invalid. |
400 | InvalidFilterClause | The specified filtering condition is invalid. | The error message returned because the filter condition is invalid. |
400 | InstanceOverQuota | The number of items exceeds the limit. | The error message returned because the number of images on the instance exceeds the upper limit. |
400 | IncorrectOrientation | The image contains incorrect rotation flags in the meta data. | The error message returned because the image carries rotation settings. Rotation settings are not supported. |
400 | UnsupportedPicPixels | The specified pixels is not supported. | The error message returned because the specified image pixel is not supported. |
403 | NoPermission | You are not authorized to perform this operation. | The error message returned because you are not authorized to perform this operation. |
403 | DeniedRequest | Your request was denied due to instance flow control. | The error message returned because your request has been denied due to throttling. |
500 | UnknownException | An internal server error occurred. | An unknown error occurred. |
500 | NetworkException | A network error occurred. | The error message returned because a network error occurred. |
500 | UnsupportedInstanceType | The instance type is not supported. | The error message returned because the instance type is not supported. |
500 | UnsupportedOperationType | The specified action is not supported. | The error message returned because the specified action is not supported. |
500 | AccessEngineFailed | An error occurred while accessing the search engine. | The error message returned because an error occurred while accessing the search engine. |
500 | InternalOssError | An internal OAS error occurred. | The error message returned because an internal algorithm error occurred. |
500 | InternalSwiftError | An internal SWIFT error occurred. | The error message returned because an internal message queue error occurred. |
500 | InternalTableStoreError | An internal Table Store error occurred. | The error message returned because an internal storage error occurred. |
For a list of error codes, visit the API Error Center.
Error codes
For a list of error codes, visit the API Error Center.