AddImage - Image Search - Alibaba Cloud Documentation Center

This topic describes the syntax of the AddImage operation and provides examples of this operation. You can call this operation to add an image to an Image Search instance.

Usage notes

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

QPS limits

The default concurrency for adding an image to instances with a capacity of 100,000 images is 1. This means that the system can process up to one image upload request per second.

The default concurrency for adding an image to instances with other image capacity specifications is 5. This means that the system can process up to five image upload requests per 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 Image Search instance. Note The instance name is not the instance ID.
ProductId	String	Yes	2092061_1	The ID of the product. The ID can be up to 256 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 256 characters in length. Note An image is uniquely identified by the values of the ProductId and PicName parameters. 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 content. The image size 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 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 the SDK to call the operation: If you use Image Search SDK V3 to call the operation, you can upload an image without the need to specify PicContent. The SDK encapsulates PicContent 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. For more information about the sample code, see SDK for Java. Use OpenAPI Explorer to call the 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 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, 88888888 is 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. You can obtain the subject identification result from 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 scaled.
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.
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: \ ¥ $ & %
IntAttr3	Integer	No	33	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.
StrAttr3	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: \ ¥ $ & %
IntAttr4	Integer	No	44	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.
StrAttr4	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: \ ¥ $ & %

Response parameters

Parameter	Type	Example	Description
Message	String	success	The error 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 error 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 recognition.
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 is successful. Valid values:

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 an empty parameter.
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 not specified.
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 invalid.
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 on the instance exceeds the upper limit.
400	IncorrectOrientation	The image contains incorrect rotation flags in the meta data.	The image carries unsupported rotation settings.
400	UnsupportedPicPixels	The specified pixels is not supported.	The specified image pixel value is not supported.
400	InvalidStrAttr	The specified parameter StrAttr is not valid.	The StrAttr parameter is invalid.
400	InvalidStrAttr2	The specified parameter StrAttr2 is not valid.	The StrAttr2 parameter is invalid.
400	InvalidStrAttr3	The specified parameter StrAttr3 is not valid.	The StrAttr3 parameter is invalid.
400	InvalidStrAttr4	The specified parameter StrAttr4 is not valid.	The StrAttr4 parameter is invalid.
400	InvalidIntAttr2	The specified parameter IntAttr2 is not valid.	The IntAttr2 parameter is invalid.
400	InvalidIntAttr3	The specified parameter IntAttr3 is not valid.	The IntAttr3 parameter is invalid.
400	InvalidIntAttr4	The specified parameter IntAttr4 is not valid.	The IntAttr4 parameter is invalid.
400	PictureError	[download] Img Download Failed.	Failed to download the image. Check the image and try again.
400	UnsupportedInstanceType	The instance type is not supported.	The instance type is not supported.
400	UnsupportedOperationType	The specified action is not supported.	The specified operation is not supported.
400	InvalidIntAttr	The specified parameter IntAttr is not valid.	The IntAttr parameter is invalid.
403	NoPermission	You are not authorized to perform this operation.	You are not authorized to perform this operation.
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	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 Tablestore error has occurred.
500	ConnectionDVException	Failed to obtain collection.	internalError

For more error codes, see Service error codes.

Error codes

For a list of error codes, see Service error codes.