All Products
Search
Document Center

Image Search:AddImage

Last Updated:Aug 21, 2023

Adds an image to an Image Search instance.

Usage notes

You can call this operation to add an image to an Image Search instance.

Note If you want to obtain more information about the service and technical support, click pre-sales online consulting or join the DingTalk group (ID 35035130).

QPS limits

By default, the concurrency limit for adding an image to instances whose image capacity specifications are 0.1 million images is 1. This means that the system can process up to one request of adding an image every second.

By default, the concurrency limit for adding an image to instances of other image capacity specifications is 5. This means that the system can process up to five requests of adding an image every second.

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 AddImage

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

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

Note The instance name is not the instance ID.
ProductId String Yes 2092061_1

The product ID. The ID can be up to 512 characters in length.

Note A product may have multiple images.
PicName String Yes 2092061_1.jpg

The name of the image. The name can be up to 512 characters in length.

Note
  • An image is uniquely identified by the values of ProductId and PicName.
  • If you add an image whose product ID (ProductId) and image name (PicName) are the same as those of an existing image, the newly added image overwrites the existing image.
PicContent String Yes AAAANSUhEUgAAAPcAAAEVCAYAAAA8d3NuAAAAAXNSR0IArs......RK5CYII=

The image file.

  • The file size of the image cannot exceed 4 MB.
  • 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
    • If you use SDKs to call this operation, you do not need to specify PicContent. The SDKs encapsulate this parameter and automatically encode its value in Base64. For more information about how to use Image Search SDK for Java, see SDK for Java.
    • If you use OpenAPI Explorer to call this operation, you can select only the 2019-03-25 version. If you call this operation of other versions, the value of PicContent cannot be encoded in Base64.
CategoryId Integer No 88888888

The category ID of the image. For more information, see Category reference.

Note
  • For product image search, 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 prediction result in the response.

  • For generic image search, only 88888888 may be returned for this parameter in the response 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 subject identification result. Default value: true. Valid values:

  • true: The system identifies the subject in the image, and searches for images based on the subject identification result. The subject identification result is included in the response.
  • false: The system does not identify the subject in the image, and searches for images based on the entire image.
Region String No 280,486,232,351

The subject area of the image, in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left point. x2 and y2 represent the lower-right point.

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

  • The value of Region does not have a unit. The value is generated based on the length and width of the image. If the length and width of the image are scaled, the value of Region must be proportionally adjusted.
CustomContent String No zidingyi

The user-defined content. The value can be up to 4,096 characters in length.

Note If you specify this parameter, the response includes this parameter and its value. You can add text such as an image description.
IntAttr Integer No 22

The attribute, which is an integer. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.

StrAttr String No ss

The attribute, which is a string. The value can be up to 128 characters in length. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.

Note The value cannot contain the following special characters: \ ¥ $ & %
IntAttr2 Integer No 22

The attribute, which is an integer. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.

Note This parameter is applicable only to instances that are created after January 3, 2023.
StrAttr2 String No ss

The attribute, which is a string. The value can be up to 128 characters in length. The attribute can be used to filter images when you search for images. If you specify this parameter, the response includes this parameter and its value.

Note
  • The value cannot contain the following special characters: \ ¥ $ & %
  • This parameter is applicable only to instances that are created after January 3, 2023.

Response parameters

Parameter Type Example Description
Message String success

The returned message.

Note No value is returned if the request was successful, and an error message is returned if the request failed.
RequestId String E0845DE6-52AF-4B50-9F15-51ED4044E6AB

The request ID.

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 94,691,206,650

The result of subject identification. The subject area of the image is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left point. x2 and y2 represent the lower-right point. 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.

Success Boolean true

Indicates whether the request was successful.

Examples

Sample requests

{
        "InstanceName": "demoinstance",
        "PicName": "test",
        "CustomContent": "demo content",
        "PicContent": "${Base64ImageContent}",
        "ProductId": "test",
        "IntAttr": "0",
        "StrAttr": "demo str attr"
    }

Sample success responses

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "PicInfo" : {
    "Region" : "111,697,XX,XX",
    "CategoryId" : 0
  },
  "Message" : "success",
  "RequestId" : "B253A127-DF89-4DDC-A295-618DD22B00B2",
  "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 NoSpecifiedPic The content of an image is not specified in the HTTP POST body. No image is specified.
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 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 a list of error codes, see Service error codes.