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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

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.

  • The file size of the image cannot exceed 4 MB.
  • The following image formats are supported: PNG, JPG, JPEG, BMP, GIF, WebP, TIFF, and PPM.

  • The transmission timeout period cannot exceed 5 seconds.

  • For brand image searches, the length and the width of the image must range from 200 pixels to 4,096 pixels.

  • For cloth image searches, the length and the width of the image must range from 448 pixels to 4,096 pixels.

  • For product and generic image searches, the length and the width of the image must range from 100 pixels to 4,096 pixels.

  • The image cannot contain rotation settings.
CategoryId Integer No 88888888

The category of the product. For more information, see Category references.

  • For product search: If a category is specified, the specified category prevails. If no category is specified, the system estimates and selects a category. The category selected by the system is included in the response.

  • For generic search: The parameter value is set to 88888888 regardless of whether a category is specified.

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.

  • true: The system recognizes the subject in the image, and searches for images based on the recognized subject. The recognition result is included in the response.

  • false: The system does not recognize the subject of the image, and searches for images based on the entire image.

Region String No 280,486,232,351

The subject area of the image. Specify the subject area in the following format: x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right corner pixel.

Note

  • If you set the Region parameter, the system searches for images based on the value of Region regardless of the value of the Crop parameter.

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:

  • int_attr>=100
  • str_attr!="value1"
  • Example: int_attr=1000 AND str_attr="value1"

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
  • This parameter is not supported. We recommend that you use the Score parameter.
  • The SortExprValues parameter indicates a 2-tuple in which values are separated by a semicolon (;). The first value indicates the correlation score of the returned image. A greater value indicates a higher correlation with the sample image. Different algorithms are used.
  • If the value of CategoryId is within the value range from 0 to 2, the value range of SortExprValues is from 0 to 7.33136443711219e+24.
  • If the value of CategoryId is not within the value range from 0 to 2, the value range of SortExprValues is from 0 to 5.37633353624177e+24. If the returned image is identical with the sample image, the highest correlation score is generated.
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.

  • A value of 0 indicates that the operation is successful.
  • Values other than 0 indicate errors.
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.