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

Compares the similarity between two images.

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:CompareSimilarByImage

none

*All Resource

*

None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
PrimaryPicContent	string	Yes	The image content. The image size cannot exceed 4 MB. Image formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, and PPM. The transmission wait time cannot exceed 5 seconds. When the service type is product image search, generic image search, furniture and home furnishing image search, or industrial hardware image search, the image width and height must be greater than or equal to 100 pixels and less than or equal to 4,096 pixels. When the service type is trademark image search, the image width and height must be greater than or equal to 200 pixels and less than 4,096 pixels. When the service type is fabric image search, the image width and height 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 To call the operation by using an SDK: - Only SDK V3 is supported. You do not need to specify the PrimaryPicContent field. The SDK encapsulates this field into the PrimaryPicContentObject field and automatically converts it to Base64 encoding. For specific examples, refer to Java SDK. - The SDK does not support directly passing image URLs. SDK V3 provides an alternative method to upload images by URL. For specific examples, refer to Java SDK.	AAAANSUhEUgAAAPcAAAEVCAYAAAA8d3NuAAAAAXNSR0IArs......RK5CYII=
SecondaryPicContent	string	Yes	The image content. The image size cannot exceed 4 MB. Image formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, and PPM. The transmission wait time cannot exceed 5 seconds. When the service type is product image search, generic image search, furniture and home furnishing image search, or industrial hardware image search, the image width and height must be greater than or equal to 100 pixels and less than or equal to 4,096 pixels. When the service type is trademark image search, the image width and height must be greater than or equal to 200 pixels and less than 4,096 pixels. When the service type is fabric image search, the image width and height 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 To call the operation by using an SDK: - Only SDK V3 is supported. You do not need to specify the PrimaryPicContent field. The SDK encapsulates this field into the PrimaryPicContentObject field and automatically converts it to Base64 encoding. For specific examples, refer to Java SDK. - The SDK does not support directly passing image URLs. SDK V3 provides an alternative method to upload images by URL. For specific examples, refer to Java SDK.	AAAANSUhEUgAAAPcAAAEVCAYAAAA8d3NuAAAAAXNSR0IArs......RK5CYII=
InstanceName	string	Yes	The name of the Image Search instance. The name can be up to 20 characters in length. If you have 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 here is not the instance ID. Distinguish between them when you use the instance.	demoinstance1

Response elements

Element	Type	Description	Example
	object	The similarity calculation result.
Score	number	The similarity score of the images. Valid values: 0 to 1.	0.85
Success	boolean	Indicates whether the request is successful.	true
RequestId	string	The request ID.	B3137727-7D6E-488C-BA21-0E034C38A879
Msg	string	The error message.	success
AccessDeniedDetail	object	The access denied details.
AuthAction	string	The action in the authorization request.	xxx
AuthPrincipalDisplayName	string	The display name of the principal.	111
AuthPrincipalOwnerId	string	The ID of the Alibaba Cloud account that owns the principal.	222
AuthPrincipalType	string	The type of the principal.	SubUser
EncodedDiagnosticMessage	string	The encoded complete diagnostic message.	xxxxxx
NoPermissionType	string	The type of the no-permission error. Valid values: ImplicitDeny: No policy is matched. ExplicitDeny: A Deny policy is explicitly matched.	ImplicitDeny
PolicyType	string	The type of the policy that causes the access denial.	AccountLevelIdentityBasedPolicy
Code	integer	The error code. Valid values: 0: The request is successful. Non-zero: The request fails.	0

Examples

Success response

JSON format

{
  "Score": 0.85,
  "Success": true,
  "RequestId": "B3137727-7D6E-488C-BA21-0E034C38A879",
  "Msg": "success",
  "AccessDeniedDetail": {
    "AuthAction": "xxx",
    "AuthPrincipalDisplayName": "111",
    "AuthPrincipalOwnerId": "222",
    "AuthPrincipalType": "SubUser",
    "EncodedDiagnosticMessage": "xxxxxx",
    "NoPermissionType": "ImplicitDeny",
    "PolicyType": "AccountLevelIdentityBasedPolicy"
  },
  "Code": 0
}

Error codes

HTTP status code	Error code	Error message	Description
400	SearchTimeout	The request timed out.	The request timed out.
400	TimeoutForTransferImage	Image transfer timed out.	The client image transfer timed out.
400	UnsupportedPicFormat	The specified image format is invalid.	The image format is invalid.
400	UnsupportedPicPixels	The specified pixels is not supported.	The image pixel value is not supported.
400	UnsupportedPictureFormat	The format of the specified picture is not supported.	The user image format is not supported.
400	Console.InstanceNotFound	The specified ImageSearch instance is not found.	The specified instance ID does not exist. Check the instance ID and try again.
400	Console.PidError	The number of PID bindings of the current instance exceeds 50.	The number of PIDs bound to the current instance exceeds 50.
400	EmptyMeta	The body content has an empty meta field.	The request body contains empty fields.
400	IncorrectOrientation	The image contains incorrect rotation flags in the meta data.	The image contains an unsupported rotation parameter.
400	InstanceOverQuota	The number of items exceeds the limit.	The number of images in the instance exceeds the limit.
400	InstanceStatusError	The current instance status does not support this operation.	The instance status is unavailable.
400	InvalidInstance	The specified instance name is invalid.	The instance name is invalid.
400	InvalidPicContent	The image size exceeds 4 MB.	The image size exceeds 4 MB.
400	InvalidPicUrl	The specified parameter PicUrl is not valid.	The PicUrl parameter is invalid.
400	NeedRegisterBeforeInvoke	Register for PID before invoking the service.	Register the PID before calling this operation.
400	NoCaretSeperator	The body content is missing the ^ separator.	The request body is missing a required symbol.
400	NoSpecifiedPic	The content of an image is not specified in the HTTP POST body.	The image is not specified.
400	PicNotExist	The specified image does not exist.	The image is not specified.
400	InvalidSecondaryPicContent	The specified parameter SecondaryPicContent is not valid.	Invalid SecondaryPicContent parameter
400	InvalidPrimaryPicContent	The specified parameter PrimaryPicContent is not valid.	Invalid PrimaryPicContent parameter
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.
400	UnsupportedInstanceType	The instance type is not supported.	An internal error occurred: the instance type is not supported.
500	ServerInternalError	An internal error occurred.	An internal system error occurred.
500	UnknownException	An internal server error occurred.	An unknown exception occurred.
500	AccessEngineFailed	An error occurred while accessing the search engine.
500	ConnectionDVException	Failed to obtain collection.	internalError
500	Console.CallServiceError	An internal service error occurred.	An error occurred when accessing the internal service.
500	ExtractFeatureTimeout	The request timed out while extracting features.	Internal error: Feature extraction timed out.
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	NetworkException	A network error occurred.	An internal error occurred due to a network exception.
500	RequestTimeout	The request timed out.	An internal error occurred: the request timed out.
403	Console.NoPermissionError	You are not authorized to perform this operation.	You do not have the permission to perform this operation.
403	Console.NotAllowedModifyToken	You are not allowed to modify token today.	The token value cannot be modified by the user today.
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.
403	NoPermission	You are not authorized to perform this operation.	The action is unauthorized.
409	Console.TaskAlreadyExist	A task that is in progress already exists.	A running task already exists.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.