All Products
Search
Document Center

Search for an image

Last Updated: Jul 24, 2019

Description

You can call this operation to query the image information in an Image Search instance.

Request URL

Protocol URL Method Parameter
HTTPS ${HOST}/v2/image/search POST JSON

For more information about ${HOST}, see Request structure.

Request parameters

Name Type Required Description
InstanceName String Yes The name of the Image Search instance.
Type String No The search type. Valid values:
1. (Default) SearchByPic: search for similar images based on an image.
2. SearchByName: search for similar images based on an added image.
PicContent String The image content, which is encoded by using Base64. A maximum image of 2 MB and a 5s transmission wait time are supported. Currently, only JPG and PNG images are supported. The image length and width must be greater than or equal to 200 pixels and smaller than or equal to 1,024 pixels. The image cannot contain rotation information.
Notes:
1. This parameter is required when the value of Type is SearchByPic.
2. This parameter is optional and does not take effect when the value of Type is SearchByName.
ProductId String The ID of the product.
Notes:
1. This parameter is optional and does not take effect when the value of Type is SearchByPic.
2. The product ID of the added image is required when the value of Type is SearchByName.
PicName String The name of the image.
Notes:
1. This parameter is optional and does not take effect when the value of Type is SearchByPic.
2. The name of the added image is required when the value of Type is SearchByPic.
CategoryId Integer No The product category. For more information, see Category reference.
Notes:
1. This parameter is optional when the value of Type is SearchByPic. (1) For product search: If a category is configured, the configured category prevails. If no category is configured, a category prediction is performed. The predicted category results can be obtained in the response. (2) For generic search: The parameter value is set to 88888888 regardless of whether a category is set.
2. This parameter is optional and does not take effect when the value of Type is SearchByName.
Crop Boolean No Indicates whether subject recognition is required. Default value: true.
Notes:
1. This parameter is optional when the value of Type is SearchByPic. (1) If the parameter is set to true, the system identifies the subject and searches for the identified subject. The subject recognition result is included in the response. (2) If this parameter is set to false, the entire image is searched without subject recognition.
2. This parameter is optional and does not take effect when the value of Type is SearchByName.
Region String No The subject area of the image, in the format of x1,x2,y1,y2. Specifically, x1 and y1 determine the point in the upper-left corner, and x2 and y2 determine the point in the lower-right corner.
Notes:
1. This parameter is optional when the value of Type is SearchByPic. If you set the Region parameter, the search is conducted based on this parameter regardless of the value of the Crop parameter.
2. This parameter is optional and does not take effect when the value of Type is SearchByName.
Num Integer No The total number of the returned records. Valid values: 1 to 100 Default value: 10
Start Integer No The number of the first record that is returned. Valid values: 0 to 499 Default value: 0
Filter String No The filter condition.
Note: 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.
Example:
1. Filter results based on IntAttr: int_attr>=100
2. Filter results based on StrAttr: str_attr! =”value1”
3. Filter results based on IntAttr and StrAttr: int_attr=1000 AND str_attr=”value1”

Response parameters

Name Type Example Description
Success Boolean true Indicates whether the request is successful.
RequestId String 36C43E96-8F68-44AA-B1AF-B1F7AB94A6C1 The ID of the request.
Code Integer 0 The error code. A value of 0 indicates that the call is successful. Other values indicate that the call has failed.
Message String success The error message.
Head The general search result.
└ DocsReturn Integer 10 The total number of the returned records.
└ DocsFound Integer 10000 The number of matched records in the instance.
└ SearchTime Integer 95 The time that the search takes, in milliseconds.
PicInfo Information including category prediction and subject recognition result.
└ CategoryId Integer 88888888 The result of category prediction. If a category is specified in the request, the specified category takes effect.
└ 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 determine the point in the upper-left corner, and x2 and y2 determine the point in the lower-right corner. If the subject area is specified in the request, the specified subject area takes effect.
└ AllCategories All the categories supported by the system.
└ Name String Tops The name of the category.
└ Id Integer 0 The ID of the category.
Auctions All product descriptions that are returned.
└ CustomContent String Demo Custom Content The user-defined content.
└ PicName String DemoPic The name of the image.
└ CategoryId Integer 0 The category of the image.
└ ProductId String test The ID of the product.
└ SortExprValues String 7.33136443711219e+24;0 Score information about the image.
Notes: The SortExprValues parameter is a tuple whose values are separated by a semicolon (;). The first value is the relevance score of the image. A larger value indicates that the image is more relevant to the image that you are searching for. Due to different algorithmic models, the value range of SortExprValues is [0, 7.33136443711219e+24] when the number of categories is 0 to 2. The value range of SortExprValues is [0,5.37633353624177e+24] when the number of categories is of other values. When the image is the same as the image that you are searching for, the score has the largest value. The second value is the hamming distance of the image feature descriptors. A larger value indicates that the image is less similar to the image that you are searching for. Currently, the images are sequenced based on the first value. No specific value is available for determining whether the image is similar to the one that you are searching for.
└ IntAttr Integer 0 The integer attribute.
└ StrAttr String demoStrAttr The string attribute.

Examples

Sample requests

  1. URL: ${HOST}/v2/image/search
  2. POST Body:
  3. {
  4. "InstanceName": "demoinstance",
  5. "PicContent": "${Base64ImageContent}",
  6. }

Sample responses

  1. {
  2. "Auctions": [{
  3. "CategoryId": 0,
  4. "PicName": "demo",
  5. "SortExprValues": "7.33136443711219e+24;0",
  6. "ProductId": "demo"
  7. }],
  8. "Head": {
  9. "DocsReturn": 1,
  10. "DocsFound": 1,
  11. "SearchTime": 155
  12. },
  13. "PicInfo": {
  14. "CategoryId": 0,
  15. "Region": "111,697,113,774",
  16. "AllCategories": [{
  17. "Name": "Tops",
  18. "Id": 0
  19. }, {
  20. "Name": "Dress",
  21. "Id": 1
  22. }, {
  23. "Name": "Bottoms",
  24. "Id": 2
  25. }, {
  26. "Name": "Bag",
  27. "Id": 3
  28. }, {
  29. "Name": "Shoes",
  30. "Id": 4
  31. }, {
  32. "Name": "Accessories",
  33. "Id": 5
  34. }, {
  35. "Name": "Snack",
  36. "Id": 6
  37. }, {
  38. "Name": "Makeup",
  39. "Id": 7
  40. }, {
  41. "Name": "Bottle",
  42. "Id": 8
  43. }, {
  44. "Name": "Furniture",
  45. "Id": 9
  46. }, {
  47. "Name": "Toy",
  48. "Id": 20
  49. }, {
  50. "Name": "Underwear",
  51. "Id": 21
  52. }, {
  53. "Name": "Digital device",
  54. "Id": 22
  55. }, {
  56. "Name": "Other",
  57. "Id": 88888888
  58. }]
  59. },
  60. "RequestId": "D61D869E-E92A-447F-AD67-9234F999E516",
  61. "Msg": "success",
  62. "Success": true,
  63. "Code": 0
  64. }

Error codes

For more information, see Error codes.