Searches for images by image name in an Image Search instance.

Usage notes

You can call this operation to search for images in an Image Search instance based on the values of ProductId and PicName.

QPS limits

You can view the default maximum number of queries per second (QPS) in the Image Search console. The upper limit is specified when you purchase an Image Search instance. You can set the upper limit to 1 QPS, 5 QPS, or 10 QPS.

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
Action	String	Yes	SearchImageByName	The operation that you want to perform. Set the value to SearchImageByName.
InstanceName	String	Yes	demoinstance1	The name of the Image Search instance. The name can be up to 20 characters in length. If an Image Search instance is purchased, you can log on to the Image Search console to view the instance. If no Image Search instance is purchased, you must purchase an instance. For more information, see Activate Image Search and Create an Image Search instance. Note The instance name is not the instance ID.
ProductId	String	Yes	2092061_1	The product ID.
PicName	String	Yes	2092061_1.jpg	The name of the image.
CategoryId	Integer	No	88888888	The ID of the product category. For more information, see Category reference. Product image search: If a category is specified, the specified category prevails. If no category is specified, the system predicts and selects a category. The category selected by the system is included in the response. Generic image search: The category ID is set to 88888888 regardless of whether a category is specified.
Num	Integer	No	10	The number of entries to be returned. Valid values: 1 to 100. Default value: 10.
Start	Integer	No	0	The ordinal number of the first entry to be returned. Valid values: 0 to 499. Default value: 0.
Filter	String	No	int_attr>=100	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" int_attr=1000 AND str_attr="value1" Note The value can be up to 256 characters in length.

Response parameters

Parameter	Type	Example	Description
Msg	String	success	The returned message.
Head	Object		The summary of the search results.
DocsFound	Integer	10	The number of images returned.
DocsReturn	Integer	10000	The number of images that match the search conditions in the Image Search instance.
SearchTime	Integer	95	The duration of the search process. Unit: millisecond.
RequestId	String	36C43E96-8F68-44AA-B1AF-B1F7AB94A6C1	The request ID.
Auctions	Array of Auction		The product descriptions returned.
ProductId	String	2092061_1	The product ID.
PicName	String	2092061_1.jpg	The name of the image.
CategoryId	Integer	20	The category ID of the image.
SortExprValues	String	5.37633353624177e+24;0	The score information of the image. Note This parameter is no longer used. We recommend that you use Score. SortExprValues 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. The value of SortExprValues varies based on different algorithms. If the value of CategoryId ranges from 0 to 2, the value of SortExprValues ranges from 0 to 7.33136443711219e+24. If the value of CategoryId is not within the value range from 0 to 2, the value of SortExprValues ranges 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 image. Valid values: 0 to 1. Note To use this parameter, you must update Image Search SDK to version 3.1.1.
IntAttr	Integer	2	The attribute of the INT type.
IntAttr2	Integer	20	The attribute of the INT type.
StrAttr	String	ss	The attribute of the STRING type. Note This parameter is displayed only for instances that are created after January 3, 2023.
StrAttr2	String	test	The attribute of the STRING type. Note This parameter is displayed only for instances that are created after January 3, 2023.
Code	Integer	0	The response code. A value of 0 indicates that the request was successful. Values other than 0 indicate that the request failed.
PicInfo	Object		The results of category prediction and subject identification.
Region	String	280,486,232,351	The result of subject identification. The value indicates the subject area of the image, in the format of x1,x2,y1,y2. Specifically, x1 and y1 indicate the upper-left pixel, and x2 and y2 indicate the lower-right 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		The identified subjects.
Region	String	280,486,232,351	The result of subject identification. The value indicates the subject area of the image, in the format of x1,x2,y1,y2. Specifically, x1 and y1 indicate the upper-left pixel, and x2 and y2 indicate 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 category ID.
Success	Boolean	true	Indicates whether the request was 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

HTTP status code	Error code	Error message	Description
400	BadRequest	The request has invalid parameters.	One or more parameters are invalid.
400	InvalidInstance	The specified instance name is invalid.	The instance name is invalid.
400	NoCaretSeperator	The body content is missing the ^ separator.	Specific symbols are missing in the request body.
400	EmptyMeta	The body content has an empty meta field.	The request body contains empty meta parameters.
400	InvalidMetaItem	The meta field is invalid.	A meta parameter is set to an invalid value.
400	NoPicList	The body content is missing the pic_list parameter.	The pic_list parameter is set to an invalid value.
400	InvalidPicList	The specified pic_list parameter is invalid.	The pic_list parameter is set to an invalid value.
400	InvalidCategory	The specified category is invalid.	The category ID is invalid.
400	OverflowMaxResultNum	The specified number of total results exceeds the maximum of 500.	The specified total number of entries 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 specified number of entries to return for a single request exceeds the upper limit, which is 100.
400	InvalidNumParameter	The specified parameter num is invalid.	The Num parameter is set to an invalid value.
400	InvalidIntAttr	The specified int_attr field is invalid.	The IntAttr parameter is set to an invalid value.
400	UnsupportedPicFormat	The specified image format is invalid.	The image format is invalid.
400	InvalidFilterClause	The specified filtering condition is invalid.	The filter condition is invalid.
400	InstanceOverQuota	The number of items exceeds the limit.	The number of images in the instance exceeds the upper limit.
400	IncorrectOrientation	The image contains incorrect rotation flags in the meta data.	The image carries rotation settings. Rotation settings are not supported.
400	UnsupportedPicPixels	The specified pixels is not supported.	The specified image pixel value is not supported.
403	NoPermission	You are not authorized to perform this operation.	You do not have the required permissions. Ask the administrator to grant you the permissions.
403	DeniedRequest	Your request was denied due to instance flow control.	Your request was denied due to throttling.
500	NetworkException	A network error occurred.	A network error has occurred.
500	UnsupportedInstanceType	The instance type is not supported.	The instance type is not supported.
500	UnsupportedOperationType	The specified action is not supported.	The specified operation is not supported.
500	AccessEngineFailed	An error occurred while accessing the search engine.	An error has occurred in the search engine.
500	InternalOssError	An internal OAS error occurred.	An internal algorithm error has occurred.
500	InternalSwiftError	An internal SWIFT error occurred.	An internal message queue error has occurred.
500	InternalTableStoreError	An internal Table Store error occurred.	An internal storage error has occurred.

For a list of error codes, see Service error codes.

Error codes

For more information, see Error codes