CreateSmartCluster-阿里云帮助中心

Use the CreateSmartCluster operation to create a SmartCluster in a specified dataset. A SmartCluster performs vector-based clustering on indexed materials in the dataset based on defined rules. Common use cases include face clustering based on reference face images and semantic clustering based on keywords.

Usage notes

By default, an Alibaba Cloud account can create a SmartCluster. To create a SmartCluster as a RAM user, ensure that the RAM user has the oss:MetaQuery permission.
This operation is available only when multi-dataset routing is enabled by configuring RouteRule in the OpenMetaQuery operation.
The name of a SmartCluster must be unique within a dataset. Otherwise, the operation returns an HTTP 409 error with the error code SmartClusterAlreadyExist.
The clustering calculation is an asynchronous process that runs after the SmartCluster is created. A 200 OK response indicates only that the request has been accepted. The clustering results are typically ready in several minutes. You can call the GetSmartCluster operation to check the progress.
The rules parameter is an array of clustering rules. When passed as a URL query string, you must JSON serialize and URL encode it. The BaseURIs parameter specifies the reference materials used to train the clustering rules. For example, face clustering requires several reference face images, and the objects specified in BaseURIs must exist.
If you use the notification parameter, you must first grant the RAM role the necessary permissions to access the specified MNS topic.

Request syntax

POST /?metaQuery&action=createSmartCluster&datasetName=DatasetName&name=ClusterName&clusterType=ClusterType&rules=Rules HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation uses only common request headers. For more information, see Common Request Headers.

Request elements

Parameter	Type	Required	Example	Description
datasetName	string	Yes	photos-2026	The name of the dataset that will contain the SmartCluster.
name	string	Yes	face-cluster-alice	The name of the SmartCluster. The name must be unique within the dataset and can be up to 128 characters long.
description	string	No	Cluster faces matching Alice	The description of the SmartCluster. The description can be up to 128 characters long.
clusterType	string	Yes	figure	The clustering type. Valid values: `figure`: Face clustering. `knowledge`: Semantic clustering.
rules	Array of SmartClusterRule	Yes	[{"RuleType":"face","BaseURIs":["oss://examplebucket/refs/alice.jpg"]}]	An array of clustering rules. When passed as a URL query string, you must JSON serialize and URL encode this parameter. Child node: SmartClusterRule
SmartClusterRule	container	Yes	N/A	A container for the parameters of a single clustering rule. Child nodes: RuleType, BaseURIs, Keywords, and Sensitivity Parent node: rules
RuleType	string	Yes	face	The type of the clustering rule. Valid values: `face`: Performs face clustering based on reference face images. This value must be used with `clusterType=figure`. `keywords`: Performs semantic clustering based on keywords. This value must be used with `clusterType=knowledge`. Parent node: SmartClusterRule
BaseURIs	Array of string	No	["oss://examplebucket/refs/alice.jpg"]	A list of Object Storage Service (OSS) URIs for the reference materials. The format is `oss://{bucket}/{key}`. This parameter is required when `RuleType` is set to `face`. You can specify up to three URIs. Parent node: SmartClusterRule
Keywords	Array of string	No	["Person","Vehicle","Building"]	A list of keywords for clustering. This parameter is required when `RuleType` is set to `keywords`. Parent node: SmartClusterRule
Sensitivity	float	No	0.7	The clustering sensitivity. The value must be in the range of [0, 1]. A larger value indicates a stricter match. Parent node: SmartClusterRule
notification	Notification object	No	{"MNS":{"TopicName":"imm-cluster-notification"}}	The configuration for Message Notification Service (MNS) notifications, used to send a message when the clustering task is complete. When passed as a URL query string, you must JSON serialize and URL encode this parameter. Child node: Notification
Notification	container	No	N/A	The configuration for clustering task notifications. Child node: MNS Parent node: notification
MNS	container	No	N/A	The MNS notification configuration. Child node: TopicName Parent node: Notification
TopicName	string	No	imm-cluster-notification	The name of the MNS topic. Parent node: MNS

Response headers

This operation uses only common response headers. For more information, see Common Response Headers.

Response elements

Parameter

Type

Required

Example

Description

CreateSmartClusterResponse

container

Yes

N/A

The root element of the response.

Child node: ObjectId

ObjectId

string

Yes

cluster-abc123def456

The unique ID assigned to the new SmartCluster. Use this ID for subsequent query, update, and delete operations.

Parent node: CreateSmartClusterResponse

Examples

Request example

POST /?metaQuery&action=createSmartCluster&datasetName=photos-2026&name=face-cluster-alice&clusterType=figure&rules=%5B%7B%22RuleType%22%3A%22face%22%2C%22BaseURIs%22%3A%5B%22oss%3A%2F%2Fexamplebucket%2Frefs%2Falice.jpg%22%5D%7D%5D&description=Cluster%20faces%20matching%20Alice HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 11:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F6
Date: Wed, 20 May 2026 11:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<CreateSmartClusterResponse>
  <ObjectId>cluster-abc123def456</ObjectId>
</CreateSmartClusterResponse>