AddImage-Image Search(Image Search)-阿里云帮助中心

Adds image information to an Image Search instance.

Operation description

Usage notes

This operation adds image information to an Image Search instance.

QPS limits

For an instance with a maximum image capacity of 100,000, the default concurrency is 1. This means the instance can process up to 1 image addition request per second. For instances with other image capacities, the default concurrency is 5. This means the instance can process up to 5 image addition requests per second.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imagesearch:AddImage

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceName	string	Yes	The name of the Image Search instance. The name can be up to 20 characters in length. If you have already purchased an Image Search instance, you can log on to the Image Search console to view the instance name. If you have not purchased an Image Search instance, refer to Activate the service and Create an instance. Note The instance name is different from the instance ID. Make sure to distinguish between them.	demoinstance1
ProductId	string	Yes	The product ID. The ID can be up to 256 characters in length. Note A product can have multiple images.	2092061_1
PicName	string	Yes	The image name. The name can be up to 256 characters in length. Note The combination of ProductId and PicName uniquely identifies an image. If you add images with the same ProductId and PicName multiple times, the last added image overwrites the previously added images.	2092061_1.jpg
PicContent	string	Yes	The image content. The image size cannot exceed 4 MB. Supported image formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, and PPM. The transmission timeout period cannot exceed 5 seconds. If the service type is product image search, generic image search, furniture and home decor image search, or industrial hardware image search, the width and height of the image must be greater than or equal to 100 pixels and less than or equal to 4,096 pixels. If the service type is trademark image search, the width and height of the image must be greater than or equal to 200 pixels and less than 4,096 pixels. If the service type is fabric image search, the width and height of the image must be greater than or equal to 448 pixels and less than or equal to 4,096 pixels. The image cannot contain rotation information. Note Call the operation by using an SDK: If you use SDK V3, you do not need to specify the PicContent parameter. The SDK encapsulates this parameter into the PicContentObject parameter and automatically converts it to Base64 encoding. For specific examples, refer to SDK for Java. The SDK does not support passing an image URL directly. SDK V3 provides an alternative method to upload an image by URL. For specific examples, refer to SDK for Java. Call the operation by using the Alibaba Cloud OpenAPI portal: If you use the 2019-03-25 version, specify the Base64 encoding of the image in the PicContent parameter. If you use the 2020-12-14 version, click Upload in the PicContent parameter to upload the image directly.	AAAANSUhEUgAAAPcAAAEVCAYAAAA8d3NuAAAAAXNSR0IArs......RK5CYII=
CategoryId	integer	No	The image category. For more information, see Category reference. Note For product image search, if you specify a category, the specified category is used. If you do not specify a category, the system predicts the category. You can obtain the predicted category from the response. For fabric, trademark, generic, furniture and home decor, and industrial hardware image search, the system sets the category to 88888888 regardless of whether you specify a category. For generic image search, the system sets the category to 88888888 regardless of whether you specify a category.	88888888
Crop	boolean	No	Specifies whether to perform subject identification. Default value: true. true: The system performs subject identification and searches based on the identified subject. You can obtain the subject identification result from the response. false: The system does not perform subject identification and searches based on the entire image. For fabric image search, this parameter is ignored and the system searches based on the entire image.	true
Region	string	No	The subject area of the image. The format is `x1,x2,y1,y2`, where `x1,y1` specifies the upper-left corner and `x2,y2` specifies the lower-right corner. Note If you specify the Region parameter, the system searches based on the specified region regardless of the value of the Crop parameter. For fabric image search, this parameter is ignored and the system searches based on the entire image. The Region parameter is unitless and is marked based on the width and height of the image in pixels. If the image is scaled, the value of the Region parameter must be scaled proportionally.	280,486,232,351
CustomContent	string	No	The custom content. The content can be up to 4,096 characters in length. Note This parameter is returned in query results. For example, you can add text such as the image description.	zidingyi
IntAttr	integer	No	The integer attribute. You can use this parameter to filter query results. This parameter is returned in query results.	22
StrAttr	string	No	The string attribute. The attribute can be up to 128 characters in length. You can use this parameter to filter query results. This parameter is returned in query results. Note Special characters such as \¥$&% are not supported.	ss
IntAttr2	integer	No	The integer attribute. You can use this parameter to filter query results. This parameter is returned in query results.	22
StrAttr2	string	No	The string attribute. The attribute can be up to 128 characters in length. You can use this parameter to filter query results. This parameter is returned in query results. Note Special characters such as \¥$&% are not supported.	ss
IntAttr3	integer	No	The integer attribute. You can use this parameter to filter query results. This parameter is returned in query results.	33
StrAttr3	string	No	The string attribute. The attribute can be up to 128 characters in length. You can use this parameter to filter query results. This parameter is returned in query results. Note Special characters such as \¥$&% are not supported.	ss
IntAttr4	integer	No	The integer attribute. You can use this parameter to filter query results. This parameter is returned in query results.	44
StrAttr4	string	No	The string attribute. The attribute can be up to 128 characters in length. You can use this parameter to filter query results. This parameter is returned in query results. Note Special characters such as \¥$&% are not supported.	ss

Response elements

Element	Type	Description	Example
	object	The response parameters.
Message	string	The error message. Note No data is returned for a successful request. An error message is returned for a failed request.	success
RequestId	string	The request ID.	E0845DE6-52AF-4B50-9F15-51ED4044E6AB
Code	integer	The error code. 0: The request is successful. Non-zero: The request failed.	0
PicInfo	object	The category prediction and subject identification results.
Region	string	The subject identification result. The subject area of the image. The format is `x1,x2,y1,y2`, where `x1,y1` specifies the upper-left corner and `x2,y2` specifies the lower-right corner. If a subject area is specified in the request, the specified subject area is used.	94,691,206,650
CategoryId	integer	The category prediction result. If a category is specified in the request, the specified category is used.	88888888
MultiRegion	array<object>	The collection of subject identification results. Note You must upgrade the SDK to V3.1.1 or later to use this parameter.
	object	The subject identification result.
Region	string	The subject identification result. The subject area of the image. The format is x1,x2,y1,y2, where x1,y1 specifies the upper-left corner and x2,y2 specifies the lower-right corner. If a subject area is specified in the request, the specified subject area is used.	94,691,206,650
AllCategories	array<object>	All categories supported by the system.
	object	All categories supported by the system.
Name	string	The category name.	Other
Id	integer	The category ID.	88888888
Success	boolean	Indicates whether the request is successful.	true

Examples

Success response

JSON format

{
  "Message": "success",
  "RequestId": "E0845DE6-52AF-4B50-9F15-51ED4044E6AB",
  "Code": 0,
  "PicInfo": {
    "Region": "94,691,206,650",
    "CategoryId": 88888888,
    "MultiRegion": [
      {
        "Region": "94,691,206,650"
      }
    ],
    "AllCategories": [
      {
        "Name": "Other",
        "Id": 88888888
      }
    ]
  },
  "Success": true
}

Error codes

HTTP status code	Error code	Error message	Description
400	BadRequest	The request has invalid parameters.	Invalid parameter.
400	InstanceStatusError	Your instance is unavailable.
400	InvalidInstance	The specified instance name is invalid.	The instance name is invalid.
400	NoCaretSeperator	The body content is missing the ^ separator.	The request body is missing a required symbol.
400	EmptyMeta	The body content has an empty meta field.	The request body contains empty fields.
400	InvalidMetaItem	The meta field is invalid.	The metadata field is invalid.
400	NoPicList	The body content is missing the pic_list parameter.	The pic_list field is not specified.
400	NoSpecifiedPic	The content of an image is not specified in the HTTP POST body.	The image is not specified.
400	NoSpecifiedSearchPic	The search image is not 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 maximum return result limit of 500 has been exceeded.
400	OverflowMaxReturnNum	The specified number of results for each request exceeds the maximum of 100.	The number of results returned in a single request exceeds the limit of 100.
400	InvalidStartParameter	The specified parameter s is inavlid.
400	InvalidNumParameter	The specified parameter n is invalid.
400	NoSpecifiedAddPic	The image to insert is not specified.
400	NoSpecifiedItemId	The item_id parameter is not specified.
400	InvalidIntAttr	The specified int_attr field is invalid.	The int filter field 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 in the instance exceeds the limit.
400	IncorrectOrientation	The image contains incorrect rotation flags in the meta data.	The image contains an unsupported rotation parameter.
400	UnsupportedPicPixels	The specified pixels is not supported.	The image pixel value is not supported.
400	SearchTimeout	The request is timed out.
400	PicNotExist	The search picture does not exist.
400	NoSpecifiedProductId	The parameter ProductId no specified.
400	NoSpecifiedPicName	The parameter PicName no specified.
400	NoSpecifiedPicContent	The parameter PicContent no specified.
400	InvalidType	The specified parameter Type is not valid.
400	InvalidProductId	The specified parameter ProductId is not valid.
400	InvalidPicName	The specified parameter PicName is not valid.
400	InvalidStrAttr	The specified parameter StrAttr is not valid.	Invalid StrAttr
400	InvalidCustomContent	The specified parameter CustomContent is not valid.
400	InvalidPicContent	The specified parameter PicContent length greater than 4 * 1024 * 1024.
400	TimeoutForTransferImage	Timeout after 5 seconds waiting for images transfer to complete.
400	InvalidPicUrl	The search picture does not exist at the specific url.
400	InvalidInstanceName	The parameter instanceName is not specified.
400	InvalidRequestId	The parameter requestId is not specified.
400	InvalidRequestIdTooLarge	The parameter requestId is too large.
400	InvalidRegion	The specific region is illegal.
400	RegionError	region.
400	InvalidStrAttr2	The specified parameter StrAttr2 is not valid.	Invalid
400	InvalidStrAttr3	The specified parameter StrAttr3 is not valid.	Invalid StrAttr3
400	InvalidStrAttr4	The specified parameter StrAttr4 is not valid.	Invalid StrAttr4
400	InvalidIntAttr2	The specified parameter IntAttr2 is not valid.	Invalid IntAttr2
400	InvalidIntAttr3	The specified parameter IntAttr3 is not valid.	Invalid IntAttr3
400	InvalidIntAttr4	The specified parameter IntAttr4 is not valid.	Invalid
400	PictureError	[download] Img Download Failed.	Picture download failed, please check the picture
400	UnsupportedOperationType	The specified action is not supported.	An internal error occurred: the action is not supported.
500	UnknownException	An internal server error occurred.	An unknown exception occurred.
500	NetworkException	A network error occurred.	An internal error occurred due to a network exception.
500	RequestTimeout	The request is timeout.
500	ExtractFeatureTimeout	The request was timed out while extracting features.
500	AccessEngineFailed	An error occurred while accessing the search engine.
500	InternalOssError	An internal OAS error occurred.	Internal error: An internal algorithm error occurred.
500	InternalSwiftError	An internal SWIFT error occurred.	Internal error: An internal MSMQ fault occurred.
500	InternalTableStoreError	An internal Table Store error occurred.	Internal error: A feature storage error occurred.
500	ConnectionDVException	Failed to obtain collection.	internalError
403	NoPermission	You are not authorized to perform this operation.	The action is unauthorized.
403	DeniedRequest	Your request was denied due to instance flow control.	The request was denied because the traffic throttling threshold of the instance was exceeded.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.