cvm · 2017-03-12

RunInstances

POST

Create one or more instances with a specified configuration.

Wire call

Converge Cloud is RPC over HTTP. There is one path — / — and the action travels in the X-TC-Action header. The /cvm/RunInstances path used in the OpenAPI document is a documentation convenience so each action is addressable; it is not a route on the server.

curl

curl -sS https://cvm.api3.convergecloud.com/ \
  -H 'Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<YYYY-MM-DD>/cvm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<sig>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Host: cvm.api3.convergecloud.com' \
  -H 'X-TC-Action: RunInstances' \
  -H 'X-TC-Version: 2017-03-12' \
  -H 'X-TC-Timestamp: <unix-seconds>' \
  -H 'X-TC-Region: luzon' \
  -d '{"Placement":"<Placement>","ImageId":"<ImageId>"}'

Request parameters

Field	Type	Required	Description
InstanceChargeType	string	No	Instance billing type. `PREPAID`: Monthly Subscription, used for at least one month `POSTPAID_BY_HOUR`: Hourly-based pay-as-you-go `CDHPAID`: Dedicated CVM (associated with a dedicated host. Resource usage of the dedicated host is free of charge.) `SPOTPAID`: Spot instance Default value: `POSTPAID_BY_HOUR`.
InstanceChargePrepaid	InstanceChargePrepaid	No	Details of the monthly subscription, including the purchase period, auto-renewal. It is required if the `InstanceChargeType` is `PREPAID`.
Placement	Placement	Yes	Location of the instance. You can use this parameter to specify the availability zone, project, and CDH (for dedicated CVMs).
InstanceType	string	No	The instance model.
ImageId	string	Yes	The image ID in the format of `img-xxx`. There are three types of images: Public images Custom images Shared images To check the image ID: For public images, custom images, and shared images, go to the CVM console. Call DescribeImages, pass in `InstanceType` to retrieve the list of images supported by the current model, and then find the `ImageId` in the response.
SystemDisk	SystemDisk	No	System disk configuration of the instance. If this parameter is not specified, the default value will be used.
DataDisks	DataDisk[]	No	The configuration information of instance data disks. If this parameter is not specified, no data disk will be purchased by default. When purchasing, you can specify 21 data disks, which can contain at most 1 LOCAL_BASIC or LOCAL_SSD data disk, and at most 20 CLOUD_BASIC, CLOUD_PREMIUM, or CLOUD_SSD data disks.
VirtualPrivateCloud	VirtualPrivateCloud	No	Configuration information of VPC. This parameter is used to specify VPC ID and subnet ID, etc. If a VPC IP is specified in this parameter, it indicates the primary ENI IP of each instance. The value of parameter InstanceCount must be the same as the number of VPC IPs, which cannot be greater than 20.
InternetAccessible	InternetAccessible	No	Configuration of public network bandwidth. If this parameter is not specified, 0 Mbps will be used by default.
InstanceCount	integer	No	The number of instances to be purchased. Value range for pay-as-you-go instances: [1, 100]. Default value: `1`. The specified number of instances to be purchased cannot exceed the remaining quota allowed for the user. For more information on the quota, see Quota for CVM Instances.
MinCount	integer	No	Specifies the minimum number of instances to create. value range: positive integer not greater than InstanceCount.
InstanceName	string	No	Instance display name. If no instance display name is specified, it will display 'unnamed' by default. Supports up to 128 characters (including pattern strings). When purchasing multiple instances:.
LoginSettings	LoginSettings	No	Instance login settings. You can use this parameter to set the login method, password and key of the instance, or keep the original login settings of the image. If it's not specified, the user needs to set the login password using the "Reset password" option in the CVM console or calling the API `ResetInstancesPassword` to complete the creation of the CVM instance(s).
SecurityGroupIds	string[]	No	Security group to which an instance belongs. obtain this parameter by calling the `SecurityGroupId` field in the return value of DescribeSecurityGroups. if not specified, bind the default security group under the designated project. if the default security group does not exist, automatically create it.
EnhancedService	EnhancedService	No	Enhanced service. You can use this parameter to specify whether to enable services such as Anti-DDoS and Cloud Monitor. If this parameter is not specified, Cloud Monitor and Anti-DDoS are enabled for public images by default. However, for custom images and images from the marketplace, Anti-DDoS and Cloud Monitor are not enabled by default. The original services in the image will be retained.
ClientToken	string	No	A unique string supplied by the client to ensure that the request is idempotent. Its maximum length is 64 ASCII characters. If this parameter is not specified, the idem-potency of the request cannot be guaranteed.
HostName	string	No	Instance HostName. Period (.) and hyphen (-) should not be used as the first or last character of the hostname, and should not be used consecutively. Windows instances: The hostname should contain 2 to 15 characters, including letters (case insensitive), digits, and hyphens (-), does not support periods (.), and should not be all digits. Instances of other types (such as Linux instances): The h…
ActionTimer	ActionTimer	No	Scheduled tasks. You can use this parameter to specify scheduled tasks for the instance. Only scheduled termination is supported.
DisasterRecoverGroupIds	string[]	No	Placement group ID. You can only specify one.
TagSpecification	TagSpecification[]	No	List of tag description. By specifying this parameter, the tag can be bound to the corresponding CVM and CBS instances at the same time.
InstanceMarketOptions	InstanceMarketOptionsRequest	No	The market options of the instance.
UserData	string	No	User data provided to the instance. This parameter needs to be encoded in base64 format with the maximum size of 16 KB. For more information on how to get the value of this parameter, see the commands you need to execute on startup for Windows or Linux.
Metadata	Metadata	No	Custom metadata. specifies the support for creating custom metadata key-value pairs when creating a CVM.
DryRun	boolean	No	Whether the request is a dry run only.
CpuTopology	CpuTopology	No	Information about the CPU topology of an instance. If not specified, it is determined by system resources.
CamRoleName	string	No	CAM role name, which can be obtained from the `roleName` field in the response of the `DescribeRoleList` API.
HpcClusterId	string	No	HPC cluster ID. The HPC cluster must and can only be specified for a high-performance computing instance.
LaunchTemplate	LaunchTemplate	No	Instance launch template.
DedicatedClusterId	string	No	Specify the ID of the dedicated cluster where the CVM is created.
ChcIds	string[]	No	Specify the CHC physical server that used to create the CHC CVM.
DisableApiTermination	boolean	No	Instance termination protection flag, indicating whether an instance is allowed to be deleted through an API. Valid values: true: Instance protection is enabled, and the instance is not allowed to be deleted through the API. false: Instance protection is disabled, and the instance is allowed to be deleted through the API. Default value: false.
EnableJumboFrame	boolean	No	Whether the instance enables jumbo frames. valid values: true: means the instance enables jumbo frames. only models supporting jumbo frames can be set to true. false: means the instance disables jumbo frames. only models supporting jumbo frames can be set to false. instance specifications supporting jumbo frames: instance specifications.

Response

Fields are returned inside the Response envelope. Converge Cloud answers HTTP 200 for errors as well as successes, so read Response.Error rather than the status code — and test for the presence of that object, because Code is occasionally the empty string.

Field	Type	Description
InstanceIdSet	string[]	If you use this API to create instance(s), this parameter will be returned, representing one or more instance IDs. Retuning the instance ID list does not necessarily mean that the instance(s) were created successfully. To check whether the instance(s) were created successfully, you can call DescribeInstances and check the status of the instances in `InstancesSet` in the response. If the status …
RequestId	string	The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

Success

{
  "Response": {
    "InstanceIdSet": …,
    "RequestId": "…"
  }
}

Error

{
  "Response": {
    "Error": { "Code": "…", "Message": "…" },
    "RequestId": "…"
  }
}

Try it

CredentialThe key never leaves this tab — it signs the request here. The signed request goes to /api-relay/cvm.

SecretIdSecretKey

Request bodyvalid JSONPOST cvm.api3.convergecloud.com · RunInstances

{
  "Placement": "<Placement>",
  "ImageId": "<ImageId>"
}

This action changes resources in my own account and may create a charge. I understand.

Recorded example response — captured 2026-09-16

{
  "Response": {
    "InstanceIdSet": [
      "ins-6l9ee4b2"
    ],
    "RequestId": "607e66ca-d045-933e-fc68-69fa2e51a88c"
  }
}

What failure looks like

Example error responses for this action. Match on Code.

Recorded error 1

{
  "Response": {
    "Error": {
      "Code": "InvalidImageId.NotFound",
      "Message": "ImageId img-00000000 is not found"
    },
    "RequestId": "9b8cfed8-afba-00aa-7b2e-d3785b64bbac"
  }
}

Behaviour

Returns InstanceIdSet immediately; the instances are PENDING and reach RUNNING shortly afterwards. Most parameters have defaults, so an under-specified request will still launch billable instances.