All Products
Search
Document Center

Image Search:Search for images

Last Updated:Oct 31, 2023

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.

    国际站搜索.png

    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 to 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.

    └Score

    Float

    1

    The similarity score between the query image and result image. Value range: 0~1.

    Note

    It can be used only if the version is upgraded to V3.1.1.

    └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 SearchImageByName.

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.