This topic describes the syntax of the SearchByName operation and provides examples. You can call this operation to query images in an Image Search instance based on an image name.

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

Parameter Type Required Example Description
InstanceName String Yes demoinstance1

The name of the Image Search instance.

ProductId String Yes 2092061_1

The ID of the product.

PicName String Yes 2092061_1.jpg

The name of the image.

CategoryId Integer No 88888888

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

  • For product image searches, if you specify a category for an image, the specified category prevails. If you do not specify a category for an image, the system predicts the category, and returns the prediction result in the response.
  • For generic image searches, the parameter value is set to 88888888 regardless of whether a category is set.
Num Integer No 10

The number of images to be returned. Valid values: 1 to 100 Default value: 10.

Start Integer No 0

No. of the first image to be displayed. Valid values: 0 to 499. Default value: 0.

Filter String No int_attr>=100

The filter condition. The int_attr field supports the following operators: >, >=, <, <=, and =. The str_attr field supports the following operators: = and !=. Multiple filter conditions are joined by AND or OR. Examples: int_attr>=100, str_attr!="value1", and int_attr=1000 AND str_attr="value1".

Response parameters

Parameter Type Example Description
Msg String success

The error message.

Head object

The general search results.

DocsFound Integer 10

The number of returned images.

DocsReturn Integer 10000

The number of matched images in the Image Search instance.

SearchTime Integer 95

The time that the search took, in milliseconds.

RequestId String 36C43E96-8F68-44AA-B1AF-B1F7AB94A6C1

The ID of the request.

Auctions Array of Auction

All the product descriptions that were returned.

PicName String 2092061_1.jpg

The name of the image.

IntAttr Integer 2

The attribute of the Integer type.

CategoryId Integer 20

The category of the image.

ProductId String 2092061_1

The ID of the product.

StrAttr String ss

The attribute of the String type.

SortExprValues String 5.37633353624177e+24;0

The score information about the image.

Note
  • The SortExprValues parameter indicates a 2-tuple in which values are separated with a semicolon (;). The first value indicates the correlation score of the searched image. If the first value is high, the searched image is highly correlated to your 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 searched image is identical with your 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.

Code Integer 0

The error code.

The value 0 indicates a request success.

A value that is not 0 indicates a request failure.

PicInfo object

The information such as the results of category prediction and subject recognition.

Region String 280,486,232,351

The result of subject recognition.

The subject area of the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right corner pixel. If a subject area is specified in the request, the specified subject area prevails.

CategoryId Integer 20

The result of category prediction.

If a category is specified in the request, the specified category prevails.

MultiRegion Array of reg

All recognized subjects.

Region String 280,486,232,351

The result of subject recognition.

The subject area of the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right corner pixel. If a subject area is specified in the request, the specified subject area prevails.

AllCategories Array of Category

All the categories that are supported by the system.

Name String 88888888

The name of the category.

Id Integer other

The ID of the category.

Success Boolean true

Indicates whether the request is successful.

Examples

Sample requests

{
        "InstanceName": "demoinstance",
        "ProductId": "ProductId",
        "PicName":"PicName"
}

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" : [ ]
  },
  "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 the specified parameter is invalid.
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 metadata field is invalid.
400 NoPicList The body content is missing the pic_list parameter. The error message returned because the pic_list field is not specified.
400 InvalidPicList The specified pic_list parameter is invalid. The error message returned because the pic_list field is invalid.
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 maximum number (500) of results returned for a sample image has been reached.
400 OverflowMaxReturnNum The specified number of results for each request exceeds the maximum of 100. The error message returned because the maximum number (100) of results returned for a single request has been reached.
400 InvalidNumParameter The specified parameter num is invalid. The error message returned because the num field is invalid.
400 InvalidIntAttr The specified int_attr field is invalid. The error message returned because the int filter field is invalid.
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 in the instance exceeds the limit.
400 IncorrectOrientation The image contains incorrect rotation flags in the meta data. The error message returned because the image contains unsupported rotation parameters.
400 UnsupportedPicPixels The specified pixels is not supported. The error message returned because the 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 InternalError An internal server error occurred. The error message returned because an internal error has occurred.
500 NetworkException A network error occurred. The error message returned because a network error has 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 has occurred.
500 InternalSwiftError An internal SWIFT error occurred. The error message returned because an internal message queue error has occurred.
500 InternalTableStoreError An internal Table Store error occurred. The error message returned because an internal storage error has occurred.

For a list of error codes, visit the API Error Center.

Error codes

For more information, see Error codes.