This topic describes how to search for images.

Background information

You can search for images by calling API operations, using SDKs, and using the console. We recommend that you use SDKs. Use the console if you test the features of Image Search.

Use the console

  1. Log on to the Image Search console.
  2. Select the service type and click the name of your instance.
  3. Click the Search by Image tab. Specify the following parameters.
    Search for images - Step 3
    Parameter Description Required
    Search Type The search type. Valid values:
    • SearchByPic: The system searches for similar images based on a new image. By default, this option is selected.
    • SearchByName: The system searches for similar images based on the name of an existing image.
    Yes
    Upload Image The image file to be uploaded. The image file is encoded in Base64. The image to be uploaded must meet the following requirements:
    • The file size of the image cannot exceed 4 MB.
    • Image Search supports the following image formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, and PPM.
    • The transmission time-out period cannot exceed 5 seconds.
    • 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 information.
    Yes
    Image Subject Recognition Specifies whether to recognize the subject in the image and search for images based on the recognized subject. Valid values:
    • true: The system recognizes the subject in the image and searches for images based on the recognized subject. If you turn on Image Subject Recognition, you can select the automatic recognition method or define the main subject area for recognition. For more information, see the description of the Recognition Method parameter.
    • false: The system does not recognize the subject of the image, and searches for images based on the entire image.
    Yes
    Recognition Method The method to recognize the subject in the image. Valid values:
    • Automatic Recognition: If you select this option, the system recognizes the subject and searches for images based on the recognized subject. You can obtain the recognition result in the response.
    • Define the main subject area: You can specify an area for subject recognition. 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 pixel. After you select this option, you can drag and drop the pointer to determine the subject area in the image. If you do not specify a subject area, the system searches for images based on the entire image.
    Yes
    Image Category The category of the image. The CategoryId parameter indicates the category of the image. You can specify the category for an image when you search for images. For more information, see Category reference.
    Note
    • 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 result of category prediction in the response.
    • For generic image searches, the system sets the category ID to 88888888, regardless of whether you specify a category for an image.
    No
    Number of images in results The maximum number of similar images to be returned. Valid values: 1 to 100. Default value: 10. No
    No. of the first image in result for pagination No. of the first image to be displayed. Valid values: 0 to 499. Default value: 0. No
    Filter Condition The filter condition. When you search for images, you can specify filter conditions to enable the system to return only the images that meet the conditions. For example, you can specify filter conditions to enable the system return only the images for which the owner ID is 1000 or the company name is Alibaba.
    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: int_attr=1000 AND str_attr="value1"
    No
  4. View the return results.
    The following table describes the response parameters.
    Parameter 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.
    • The value 0 indicates a request success.
    • A value that is not 0 indicates a request failure.
    Message String success The returned message.
    Head - - The information about the search results.
    └DocsReturn Integer 10 The number of the returned images.
    └DocsFound Integer 10000 The number of the matched images in the instance.
    └SearchTime Integer 95 The time that the search takes. Unit: milliseconds.
    PicInfo - - The information such as the results of category prediction and subject recognition.
    └CategoryId Integer 88888888 The result of category prediction. If a category is specified in the request, the specified category prevails.
    └Region String 280,486,232,351 The result of subject recognition. The subject area of the image 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 pixel. If a subject area is specified in the request, the specified subject area prevails.
    └AllCategories - - All the categories that are supported by the system.
    └Name String Tops The name of the category.
    └Id Integer 0 The ID of the category.
    Auctions - - All the product descriptions that were 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 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. You need only to focus on the first value.
    └IntAttr Integer 0 The integer attribute.
    └StrAttr String demoStrAttr The string attribute.

Call API operations

In this method, you can send requests over HTTP or HTTPS to access Image Search, and you must be authenticated based on a signature mechanism. The request body must be sent in a specified format. If you call API operations to search for images, queries per second (QPS) are those specified when you purchase the package. For more information, see Search for images.

Use SDKs (recommended)

Image Search provides SDKs of multiple versions. If you use SDKs, you do not need to concern yourself with issues such as signature verification and compliance with the format of the request body. If you use SDKs to search for images, the QPS is the one specified when you purchase the package. For more information, see SDK reference.