Tenant Cloud Compute Cloud Virtual Machine Instance APIs RunInstances

RunInstances

Last Updated At: 2026-08-02 00:05:21

1. Interface Description

Interface request domain name: cvm.api3.convergecloud.com.

This API is used to create one or more instances with specified configurations.

  • Once an instance is successfully created, it will automatically start upon boot. [Instance status](../data structure#instancestatus) will change to "Running".
  • This API is asynchronous. When the creation request is successfully issued, it returns a list of instance IDs. At this point, the instance creation is not yet complete. During this period, the instance status will be "Preparing". You can call the DescribeInstancesStatus API to query the status of the instance to determine if the creation was ultimately successful. If the instance status changes from "Preparing" to "Running", it has been successfully created.

Default interface request rate limit: 10 times per second.

Interface update time: 2022-04-22 07:24:14.

The interface only verifies the signature but does not authenticate.

2. Input Parameters

The following list of request parameters only lists interface request parameters and some public parameters, For a complete list of public parameters see public request parameters.

Parameter name Required Allow NULL Type Description
Action Yes No String Public parameter, The value of this interface: RunInstances
Version Yes No String Public parameter, The value of this interface: 2017-03-12
Region No No String Public parameter,Regional information A list of supported geographies is available through the DescribeRegions interface
InstanceChargeType No No String Instance billing type. 
  • POSTPAID_BY_HOUR: Postpaid by hour
  • CDHPAID: CDHPAID (created based on a CDH, where CDH resources are free of charge). In this billing mode, the placement.hostid parameter is mandatory. 
    Default value: POSTPAID_BY_HOUR.
    Example: POSTPAID_BY_HOUR
    		•
    InstanceChargePrepaid No No InstanceChargePrepaid Prepaid mode, that is, monthly subscription-related parameter settings. You can specify attributes of a monthly subscription instance, such as purchase duration and whether to set auto-renewal, through this parameter. If the billing mode of the specified instance is prepaid mode, this parameter is required.
    Example:View
    Placement Yes No Placement Location of the instance. You can specify attributes such as availability zone, project, and CDH (for creating a instance with a dedicated host billing mode) to which the instance belongs through this parameter.
    Example:View
    InstanceType No No String Instance model. Different instance models specify different resource specifications.

  • For creating a instance with billing mode as PREPAID or POSTPAID_BY_HOUR, you can obtain the specific values by calling the API DescribeInstanceTypeConfigs to obtain the latest specification table or seeing the description of the Instance Types. If this parameter is not specified, the default model is S1.SMALL1.
  • For creating a instance with billing mode as CDHPAID, this parameter starts with a prefix CDH_ and is generated based on the CPU and memory configurations. Its specific form is CDH_XCXG. For example, for creating a CDH instance with 1 core CPU and 1 GB memory, this parameter should be CDH_1C1G.
    Example: S5.LARGE4
    		•
    ImageId Yes No String Specify a valid Image ID, in the format of img-xxx. There are three types of images:
  • Public Image
  • Custom Image
  • Shared Image
  • You can obtain available image IDs in the following ways:
  • The image IDs for the Public Image, Custom Image, and Shared Image can be queried by logging in to the Console;
  • Through the ImageId field in the returned information by calling the API DescribeImages.

    • Example: img-irmer45l
    PurchaseSource No No String Purchase Source
    Example: MC
    SystemDisk No No SystemDisk Instance system disk configuration information. If this parameter is not specified, it will be assigned based on the system default values.
    Example:View
    DataDisks No No Array of DataDisk Instance data disk configuration information. If this parameter is not specified, no data disks are purchased by default. Specifying multiple data disks when purchasing is supported.
    Example:View
    VirtualPrivateCloud No No VirtualPrivateCloud VPC-related information configuration. You can specify information such as VPC ID and subnet ID through this parameter. If this parameter is not specified, use the basic network by default. If a VPC IP is specified in this parameter, the InstanceCount parameter can be 1 or 2.
    Example:View
    InternetAccessible No No InternetAccessible Public bandwidth-related settings. If this parameter is not specified, the public bandwidth is 0 Mbps by default.
    Example:View
    InstanceCount No No Int64 Number of instances to purchase. Value range: [1,100]. Default value: 1. The specified number of instances to purchase should not exceed the remaining quota of the user.
    Example: 1
    InstanceName No No String Instance display name. If not specified, it will be displayed as unnamed by default. A maximum of 60 characters are supported. Names after a period will be filtered out.
    Example: server_{R:3}
    LoginSettings No No LoginSettings Instance login settings. You can set login method, password, or key of the instance or retain the original login settings of the image. By default, a password will be randomly generated and notified to the user through Message Center.
    Example:View
    SecurityGroupIds No No Array of String Security groups to which an instance belongs. If this parameter is not specified, bind the security group by default.
    Example: ["sg-ajhn9qtq"]
    EnhancedService No No EnhancedService Enhanced services. You can specify whether to enable services such as Cloud Security and Cloud Monitor through this parameter. If this parameter is not specified, the Cloud Monitor and Cloud Security is enabled by default.
    Example:View
    ClientToken No No String String used to ensure request idempotency. This string is generated by the customer and should be unique across different requests. The maximum length should be no more than 64 ASCII characters. If this parameter is not specified, the idempotency of the request cannot be ensured.
    Example: system-f3827db9-c58a-49cc-bf10-33fc1923a34a
    SpotPrice No No String Used to specify price production, currently mainly used to spot instances.
    Example: 300.0
    HostName No No String Hostname of CVM.
  • Period (.) and hyphen (-) should not be used as the first or last character of the HostName, and should not be used consecutively.
  • Windows instance: The name should contain [2, 15] characters, including letters (case insensitive), digits, and hyphens (-), does not support periods (.), and should not be all digits.
  • Instance of other types (such as Linux instances): The name should contain [2, 31] characters, including multiple periods, with each segment between periods considered as one section. Each section can contain letters (case insensitive), digits, and hyphens (-), but should not be all digits. Period and hyphen placed together (.-) is not supported.
    Example: MyHostName
    		•
    UserData No No String User data provided for the instance, should be encoded in base64 format, supports a maximum data size of 16 KB.
    Example: TXlVc2VyRGF0YQo=
    DisasterRecoverGroupIds No No Array of String Placement group ID, only one can be specified.
    Example: ['ps-3p88qhfo']
    TagSpecification No No Array of TagSpecification List of tag descriptions. You can bind tags to corresponding resource instances at the same time by specifying this parameter. Currently, only binding tags to the CVM is supported.
    Example:View
    ProjectSpecification No No ProjectSpecification Specified project ID, only one can be specified.
    Example:View
    HpcClusterId No No String High-performance computing cluster ID. If the created instance is a high-performance computing instance, the cluster where the instance is placed should be specified. Otherwise, it cannot be specified.
    Example: hpc-a5n666lo
    DisableApiTermination No No Bool Instance destruction protection flag, indicating whether deletion through APIs is allowed. Valid values:
  •  TRUE: instance protection is enabled and deletion through APIs is not allowed
  •  FALSE: instance protection is disabled and deletion through APIs is allowed
     Default value: FALSE.
    Example: false
    		•

    3. Output Parameters

    Parameter name Type Description
    InstanceIdSet Array of String When creating an instance through this API, this parameter will be returned, indicating one or more instance IDs. Returning a list of instance IDs does not indicate that the instance is successfully created. You can determine whether the creation is completed by querying the status of the corresponding instance ID in the returned InstancesSet through the API DescribeInstancesStatus. If the instance status changes from Preparing to Running, it indicates that the instance is successfully created.
    Example: ['ins-rn99mzt1']
    RequestId String Unique request id, Each request will return. The RequestId of the request needs to be provided when locating the problem.

    4. Error Code

    The following lists only the error codes related to the interface business logic, For other error codes, see public ErrorCode.

    Error Code Description
    InvalidPermission The account does not support this operation.
    InvalidParameterValue Invalid parameter value. The format of the parameter value is incorrect or not supported, etc.
    InvalidParameterValue.Range Invalid parameter value. The range of the parameter value is not legal.
    InvalidInstanceType.Malformed The parameter format of the specified InstanceType is invalid.
    InvalidPeriod Invalid duration. Currently, only the following durations are supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 24, 36], unit: months.
    VpcIpIsUsed The VPC IP has already been used.
    VpcAddrNotInSubNet The VPC IP is not within the subnet.
    InvalidClientToken.TooLong The string length of the specified ClientToken exceeds the limit. It should be less than or equal to 64 bytes.
    InvalidHostId.NotFound The specified HostId does not exist, or does not belong to the requesting account.
    MissingParameter Parameters are missing. The request did not include mandatory parameters.
    InstancesQuotaLimitExceeded It indicates that the number of instances being created exceeds the remaining quota allowed for purchase by the account.
    InvalidParameterCombination It indicates that the parameter combination is incorrect.
    InvalidParameter.InvalidIpFormat The specified VPC IP format is incorrect.
    InvalidZone.MismatchRegion The specified zone does not exist.
    AccountQualificationRestrictions The requesting account did not pass the qualification audit.
    InvalidPassword Invalid password. The specified password does not meet password complexity restrictions. For example, the password length does not meet restrictions.
    InvalidInstanceName.TooLong The string length of the specified InstanceName exceeds the limit. It should be less than or equal to 60 bytes.
    InvalidCloudDisk.SoldOut The cloud disk has been sold out.
    TradeUnknownError Billing request error
    ResourceInsufficient.SpecifiedInstanceType The inventory of the specified instance type is insufficient.