Updated on 2025-07-25 GMT+08:00

Batch Creating Instances

Function

This API is used to batch create instances. The supported scheduling policies are as follows:

1. Scheduling to selected servers

2. Random scheduling to idle servers

VPC and AI parameter plane networks can be configured.

This API is an asynchronous API. The instance creation and startup are not completed immediately. You can call the ShowInstanceStatus API to check whether the instance statuses are running. If they are, the instances have been created.

Constraint: The value of manage_state for the instances must be ready.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/instances/batch-create

Table 1 URI parameter

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

The project ID.

Constraints

N/A

Range

The project ID of the account

Default Value

N/A

Request Parameters

Table 2 Request header parameter

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

Requests for calling an API can be authenticated using a token. If token-based authentication is used, this parameter is mandatory and must be set to a user token.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

The hostname of an instance.

Constraints

N/A

Range

The value can contain 1 to 63 characters, including letters (case-sensitive), digits, underscores (_), hyphens (-), and periods (.).

Default Value

N/A

image_id

Yes

String

Definition

Image ID.

Constraints

N/A

Range

N/A

Default Value

N/A

vpc_id

Yes

String

Definition

ID of the VPC which the network interface to be created belongs to. You can query the ID using the VPC API: https://support.huaweicloud.com/intl/en-us/api-vpc/vpc_api01_0003.html

Constraints

N/A

Range

VPC ID

Default Value

N/A

network_interfaces

Yes

Array of network_interfaces objects

Definition

Network interface information about an iMetal server.

Constraints

An iMetal server can contain a maximum of two network interfaces, and the first one serves as the primary network interface. If multiple network interfaces are specified, ensure that all network interfaces belong to the same VPC.

password

Yes

String

Definition

Default login password for the instance administrator. For Linux, the administrator is root. For Windows, the administrator is Administrator.

Constraints

N/A

Range

The value can contain 8 to 26 characters.

The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (!@$%^-_=+[{}]:,./?).

The password cannot contain the username or the username spelled backwards.

Default Value

N/A

metadata

No

Table 5 object

-

description

No

String

Definition

Description of an iMetal instance.

Constraints

N/A

Range

Maximum length: 255 characters

Default Value

The value is an empty character string by default.

placement

No

placement object

Definition

Placement of the instance, which specifies the server policy. If placement is not specified, idle servers are selected based on min_count and max_count.

Constraints

N/A

min_count

No

Integer

Definition

The minimum number of instances that must be started. If the number of actually started instances cannot meet the requirement, the entire request fails (in this case, no instances will be started).

Constraints

This parameter takes effect only when placement is not specified.

The value cannot be greater than that of max_count.

Range

1-100

Default Value

N/A

max_count

No

Integer

Definition

The maximum number of instances that can be started. The system tries to start the maximum number of instances. However, the actual number of instances to be started is between min_count and max_count.

Constraints

This parameter takes effect only when placement is not specified.

The value cannot be less than that of min_count.

Range

1-100

Default Value

N/A

Table 4 network_interfaces

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

Definition

subnet ID

Constraints

N/A

Range

N/A

Default Value

N/A

Table 5 metadata

Parameter

Mandatory

Type

Description

{Custom key}

No

Map<String,String>

Definition

Metadata for creating an iMetal instance. You can use metadata to customize key-value pairs.

If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data.

Constraints

N/A

Range

A maximum of 10 key-value pairs can be injected.

A metadata key consists of 1 to 255 characters and contains only uppercase letters, lowercase letters, spaces, digits, hyphens (-), underscores (_), colons (:), and decimal points (.).

A metadata value consists of a maximum of 255 characters.

Default Value

N/A

Table 6 placement

Parameter

Mandatory

Type

Description

server_id_set

No

Array of strings

Definition

A set of server IDs.

Constraints

A server ID list cannot contain more than 50 IDs.

Response Parameters

Status code: 202

Table 7 Response body parameter

Parameter

Type

Description

instances

Array of instances objects

Definition

Returned instance information.

Constraints

N/A

Table 8 instances

Parameter

Type

Description

id

String

Definition

Instance ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Status code: 400

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

Constraints

N/A

Range

N/A

Default Value

N/A

error_msg

String

Definition

Error message.

Constraints

N/A

Range

N/A

Default Value

N/A

Status code: 401

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

Constraints

N/A

Range

N/A

Default Value

N/A

error_msg

String

Definition

Error message.

Constraints

N/A

Range

N/A

Default Value

N/A

Status code: 429

Table 11 Response body parameter

Parameter

Type

Description

-

String

-

Status code: 500

Table 12 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

Constraints

N/A

Range

N/A

Default Value

N/A

error_msg

String

Definition

Error message.

Constraints

N/A

Range

N/A

Default Value

N/A

Example Request

Request for batch creating instances

POST https://{endpoint}/v1/{project_id}/instances/batch-create

Example Response

Status code: 202

Instances created.

{
  "instances" : {
    "id" : "0198170e-4ca7-7ee4-89a7-fa631843920b"
  }
}

Status Codes

Status Code

Description

202

Instances created.

400

Invalid request parameter.

401

The request is not authenticated.

429

The request is overloaded.

500

Internal server error.

Error Codes

For details, see Error Codes.