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

Queries the image information in an Image Search instance based on text.

Operation description

Usage notes

This operation queries the image information in an Image Search instance based on text. This operation is available only for instances whose service type is product multimodal search.

Note

For more product details and technical support, click Online Consultation or contact us through the DingTalk group (35035130).

QPS limits

You can view the default maximum queries per second (QPS) for query operations in the console. The QPS is the access frequency that you selected when you purchased the instance. Supported values: 1, 5, and 10.

SDK version notes

If you upgrade the Image Search SDK to V3.1.1, you can use the multi-subject identification and similarity score features. For more information, see Java SDK.

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

get

*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 that you use the correct value.	demoinstance1
Num	integer	No	The number of entries to return. Valid values: 1 to 100. Default value: 10.	10
Start	integer	No	The starting position of the entries to return. Valid values: 0 to 499. Default value: 0.	0
Filter	string	No	The filter condition. The int_attr field supports the following operators: in, not in, greater than (>), greater than or equal to (>=), less than (<), less than or equal to (<=), and equal to (=). The str_attr field supports the following operators: in, not in, equal to (=), and not equal to (!=). You can use AND and OR to connect multiple conditions. Examples: int_attr >= 100. str_attr != "value1". int_attr = 1000 AND str_attr = "value1". Note The filter condition can be up to 4,096 characters in length.	int_attr=1000 AND str_attr="value1"
DistinctProductId	boolean	No	Specifies whether to deduplicate data based on the ProductId field during retrieval.	false
Text	string	Yes	The description text used to search for images. Both Chinese and English are supported. Note The text can be up to 512 characters in length.	xxxx
ScoreThreshold	string	No	The similarity score threshold. If you specify this parameter, only the information about images whose similarity scores are greater than or equal to the threshold is returned. Valid values: 0.00 to 1.00. The value can contain up to two decimal places. Default value: 0.00.	0.50

Response elements

Element	Type	Description	Example
	object	The returned result.
Msg	string	The error message.	success
Head	object	The summary of the search results.
DocsFound	integer	The number of returned entries.	10
DocsReturn	integer	The number of matched entries in the instance.	10000
SearchTime	integer	The time taken for the search, in milliseconds.	95
RequestId	string	The request ID.	B3137727-7D6E-488C-BA21-0E034C38A879
Auctions	array<object>	The description information of all returned products.
	object	The description information of all returned products.
ProductId	string	The product ID.	2092061_1
PicName	string	The image name.	2092061_1.jpg
CategoryId	integer	The image category.	8888888
CustomContent	string	The custom content.	zidingyi
Score	number	The similarity score of the image. Valid values: 0 to 1. Note This parameter is available only after you upgrade the SDK to V3.1.1.	1
IntAttr	integer	The integer attribute.	2
IntAttr2	integer	The integer attribute.	2
StrAttr2	string	The string attribute.	xxxx
StrAttr	string	The string attribute.	xxxx
StrAttr3	string	The string attribute.	xxxx
StrAttr4	string	The string attribute.	xxxx
IntAttr3	integer	The integer attribute.	2
IntAttr4	integer	The integer attribute.	2
Code	integer	The error code. 0: Success. Other values: Failure.	0
PicInfo	object	The category information.
AllCategories	array<object>	The categories supported by the system.
	object	The 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
AccessDeniedDetail	object	The authentication details.
AuthAction	string	The action of the authentication request.	xxx
AuthPrincipalDisplayName	string	The display name of the authentication principal.	111
AuthPrincipalOwnerId	string	The ID of the Alibaba Cloud account to which the authentication principal belongs.	222
AuthPrincipalType	string	The type of the authentication principal.	SubUser
EncodedDiagnosticMessage	string	The encoded diagnostic message.	xxxxxx
NoPermissionType	string	ImplicitDeny: No policy is matched. ExplicitDeny: A deny policy is explicitly matched.	ImplicitDeny
PolicyType	string	The type of the policy that causes the permission denial.	PauseNotify

Examples

Success response

JSON format

{
  "Msg": "success",
  "Head": {
    "DocsFound": 10,
    "DocsReturn": 10000,
    "SearchTime": 95
  },
  "RequestId": "B3137727-7D6E-488C-BA21-0E034C38A879",
  "Auctions": [
    {
      "ProductId": "2092061_1",
      "PicName": "2092061_1.jpg",
      "CategoryId": 8888888,
      "CustomContent": "zidingyi",
      "Score": 1,
      "IntAttr": 2,
      "IntAttr2": 2,
      "StrAttr2": "xxxx",
      "StrAttr": "xxxx",
      "StrAttr3": "xxxx",
      "StrAttr4": "xxxx",
      "IntAttr3": 2,
      "IntAttr4": 2
    }
  ],
  "Code": 0,
  "PicInfo": {
    "AllCategories": [
      {
        "Name": "other",
        "Id": 88888888
      }
    ]
  },
  "Success": true,
  "AccessDeniedDetail": {
    "AuthAction": "xxx",
    "AuthPrincipalDisplayName": "111",
    "AuthPrincipalOwnerId": "222",
    "AuthPrincipalType": "SubUser",
    "EncodedDiagnosticMessage": "xxxxxx",
    "NoPermissionType": "ImplicitDeny",
    "PolicyType": "PauseNotify"
  }
}

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	TimeoutForTransferImage	Timeout after 5 seconds waiting for images transfer to complete.
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	InvalidPicList	The specified pic_list parameter is invalid.	The pic_list field is invalid.
400	NoSpecifiedPic	he content of an image is not specified in the HTTP POST body.
400	NoSpecifiedSearchPic	The search image is not specified.
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 start is inavlid.
400	InvalidNumParameter	The specified parameter num is invalid.	The num field 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	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	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	InvalidIntAttr4	The specified parameter IntAttr4 is not valid.	Invalid
400	InvalidIntAttr3	The specified parameter IntAttr3 is not valid.	Invalid IntAttr3
400	InvalidIntAttr2	The specified parameter IntAttr2 is not valid.	Invalid IntAttr2
400	InvalidStrAttr4	The specified parameter StrAttr4 is not valid.	Invalid StrAttr4
400	InvalidStrAttr3	The specified parameter StrAttr3 is not valid.	Invalid StrAttr3
400	InvalidStrAttr2	The specified parameter StrAttr2 is not valid.	Invalid
400	InvalidText	The specified parameter Text is not valid.	Description Text cannot be null
400	InvalidTextLength	Invalid text clause.	The text field length must be within 512.
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	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.