All Products
Search
Document Center

Image Search:SearchImageByPic

Last Updated:Sep 25, 2023

Searches for images by image in an Image Search instance.

Usage notes

You can call this operation to search for similar images in an Image Search instance based on an image.

Note To know more about Image Search, submit your questions on the pre-sales online consultation page or contact Alibaba Cloud in the DingTalk group (ID 35035130) for technical support.

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.

SDK version

You must update Image Search SDK to version 3.1.1, which supports multi-subject identification and similarity scores. For more information, see 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

Parameter Type Required Example Description
Action String Yes SearchImageByPic

The operation that you want to perform. Set the value to SearchImageByPic.

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.
PicContent String Yes AAAANSUhEUgAAAPcAAAEVCAYAAAA8d3NuAAAAAXNSR0IArs......RK5CYII=

The image.

  • The image cannot exceed 4 MB in size.
  • The following image formats are supported: PNG, JPG, JPEG, BMP, GIF, WebP, TIFF, and PPM.
  • The transmission timeout period cannot exceed 5 seconds.

  • For trademark image search, the length and width of the image must range from 200 pixels to 4,096 pixels.
  • For fabric image search, the length and width of the image must range from 448 pixels to 4,096 pixels.

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

  • The image cannot contain rotation settings.
Note
  • Use Image Search SDK to call this operation:
    • If you use Image Search SDK V3, you do not need to specify PicContent. The SDK encapsulates this parameter into PicContentObject and automatically encodes its value in Base64. For more information about the sample code, see SDK for Java.
    • If you use Image Search SDK to call this operation, you cannot upload an image by specifying the image URL. If you use Image Search SDK V3, you can upload an image file. For more information about the sample code, see SDK for Java.
  • Use OpenAPI Explorer to call this operation:
    • If the API version is 2019-03-25, enter the Base64-encoded string of an image as the value of PicContent.
    • If the API version is 2020-12-14, upload an image when you specify PicContent.
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.

Crop Boolean No true

Specifies whether to identify the subject in the image and search for images based on the identified subject. Default value: true. Valid values:

  • true: The system identifies the subject in the image, and searches for images based on the identified subject. The response includes the identification result.
  • false: The system searches for images based on the entire image without subject identification.

Region String No 280,486,232,351

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.

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

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=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"
  • 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 B3137727-7D6E-488C-BA21-0E034C38A879

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 8888888

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.

Note This parameter is displayed only for instances that are created after January 3, 2023.
StrAttr String 2

The attribute of the STRING type.

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 88888888

The result of category prediction. If a category is specified in the request, the specified category prevails.

MultiRegion Array of reg

The identified subjects.

Note To use this parameter, you must update Image Search SDK to version 3.1.1.
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",
        "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

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 UnknownException An internal server error occurred. An unknown error has occurred.
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.