Help & DocumentationCloud Virtual MachineAPI DocumentationInstance APIsRunInstances

RunInstances

Last updated: 2020-03-16 18:27:20

PDF

Contents：

1. API Description

Domain name for API request: cvm.tencentcloudapi.com.

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

  • After an instance is created successfully, it will start up automatically, and the instance state will become "Running".
  • If you create a pay-as-you-go instance billed on an hourly basis, an amount equivalent to the hourly rate will be frozen before the creation. Make sure your account balance is sufficient before calling this API.
  • The number of instances you can purchase through this API is subject to the CVM instance purchase limit. Both the instances created through this API and the console will be counted toward the quota.
  • This API is an async API. An instance ID list will be returned after you successfully make a creation request. However, it does not mean the creation has been completed. The state of the instance will be Creating during the creation. You can use DescribeInstances to query the status of the instance. If the status changes from Creating to Running, it means that the instance has been created successfully.

A maximum of 10 requests can be initiated per second for this API.

Note: This API supports Finance regions. If the common parameter Region is a Finance region, a domain name with the Finance region needs to be specified, for example: cvm.ap-shanghai-fsi.tencentcloudapi.com

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: RunInstances.
Version Yes String Common parameter. The value used for this API: 2017-03-12.
Region Yes String Common parameter. For more information, please see the list of regions supported by the product.
Placement Yes Placement Location of the instance. You can use this parameter to specify the attributes of the instance, such as its availability zone, project, and CDH. You can specify a CDH for a CVM by creating the CVM on the CDH.
ImageId Yes String The image ID in the format of img-xxx. There are four types of images:
  • Public images
  • Custom images
  • Shared images
  • Marketplace images

    • You can retrieve available image IDs in the following ways:
  • For the IDs of public images, custom images, and shared images, log in to the console to query the information. For the IDs of marketplace images, go to Cloud Marketplace.
  • Call DescribeImages, pass in InstanceType to retrieve the list of images supported by the current model, and then find the ImageId in the response.
    		•
    InstanceChargeType No String The instance billing method. Valid values:
  • POSTPAID_BY_HOUR: hourly, pay-as-you-go
  • CDHPAID: you are only billed for CDH instances, not the CVMs running on the CDH instances.
    Default value: POSTPAID_BY_HOUR.
    		•
    InstanceChargePrepaid No InstanceChargePrepaid Configuration of prepaid instances. You can use the parameter to specify the attributes of prepaid instances, such as the subscription period and the auto-renewal plan. This parameter is required for prepaid instances.
    InstanceType No String The instance model. Different resource specifications are specified for different instance models.

  • To view specific values for POSTPAID_BY_HOUR instances, you can call DescribeInstanceTypeConfigs or refer to Instance Types. If this parameter is not specified, S1.SMALL1 will be used by default.
  • For CDHPAID instances, the value of this parameter is in the format of CDH_XCXG based on the number of CPU cores and memory capacity. For example, if you want to create a CDH instance with a single-core CPU and 1 GB memory, specify this parameter as CDH_1C1G.
    		•
    SystemDisk No SystemDisk System disk configuration of the instance. If this parameter is not specified, the default value will be used.
    DataDisks.N No Array of DataDisk 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 data disk or LOCAL_SSD data disk, and at most 20 CLOUD_BASIC data disks, CLOUD_PREMIUM data disks, or CLOUD_SSD data disks.
    VirtualPrivateCloud No VirtualPrivateCloud VPC configurations. You can use this parameter to specify the VPC ID, subnet ID, etc. If this parameter is not specified, the basic network will be used by default. If a VPC IP is specified in this parameter, it will represent the primary ENI IP of each instance. The value of InstanceCount must be the same as the number of VPC IPs.
    InternetAccessible No InternetAccessible Configuration of public network bandwidth. If this parameter is not specified, 0 Mbps will be used by default.
    InstanceCount No Integer The number of instances to be purchased. Value range: [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 CVM instance purchase limit.
    InstanceName No String Instance name to be displayed.
  • If this parameter is not specified, "Unnamed" will be displayed by default.
  • If you purchase multiple instances at the same time and specify a pattern string {R:x}, numbers [x, x+n-1] will be generated, where n represents the number of instances purchased. For example, you specify a pattern string, server_{R:3}. If you only purchase 1 instance, the instance will be named server_3; if you purchase 2, they will be named server_3 and server_4. You can specify multiple pattern strings in the format of {R:x}.
  • If you purchase multiple instances at the same time and do not specify a pattern string, the instance names will be suffixed by 1, 2...n, where n represents the number of instances purchased. For example, if you purchase 2 instances and the instance name body is server_, the instance names will be server_1 and server_2.
    		•
    LoginSettings No LoginSettings Login settings of the instance. You can use this parameter to set the login method, password, and key of the instance or keep the login settings of the original image. By default, a random password will be generated and sent to you via the Message Center.
    SecurityGroupIds.N No Array of String Security groups to which the instance belongs. To obtain the security group IDs, you can call DescribeSecurityGroups and look for the sgld fields in the response. If this parameter is not specified, the instance will be associated with default security groups.
    EnhancedService No EnhancedService Specifies whether to enable services Anti-DDoS and Cloud Monitor. If this parameter is not specified, Cloud Monitor and Anti-DDoS are enabled for public images by default. But for custom images and images from market place, Anti-DDoS and Cloud Monitor are not enabled by default. The original services in the image will be retained.
    ClientToken No String A string used to ensure the idempotency of the request, which is generated by the user and must be unique to each request. The maximum length is 64 ASCII characters. If this parameter is not specified, the idempotency of the request cannot be guaranteed.
    For more information, see “How to ensure idempotency”.
    HostName No String Host name of the CVM.
  • Periods (.) or hyphens (-) cannot be the start or end of a host name or appear consecutively in a host name.
  • For Windows instances, the host name must be 2-15 characters long and can contain uppercase and lowercase letters, numbers, and hyphens (-). It cannot contain periods (.) or contain only numbers.
  • For other instances, such as Linux instances, the host name must be 2-60 characters long. It supports multiple periods (.) and allows uppercase and lowercase letters, numbers, and hyphens (-) between any two periods (.).
    		•
    ActionTimer No ActionTimer Scheduled tasks. You can use this parameter to specify scheduled tasks for the instance. Only scheduled termination is supported.
    DisasterRecoverGroupIds.N No Array of String Placement group ID. You can only specify one.
    TagSpecification.N No Array of TagSpecification The tag description list. This parameter is used to bind a tag to a resource instance. A tag can only be bound to CVM instances.
    InstanceMarketOptions No InstanceMarketOptionsRequest The market options of the instance.
    UserData No String User data provided to the instance, which needs to be encoded in base64 format with the maximum size of 16KB. 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.
    DryRun No Boolean Whether the request is a dry run only.
    true: dry run only. The request will not create instance(s). A dry run can check whether all the required parameters are specified, whether the request format is right, whether the request exceeds service limits, and whether the specified CVMs are available.
    If the dry run fails, the corresponding error code will be returned.
    If the dry run succeeds, the RequestId will be returned.
    false (default value): send a normal request and create instance(s) if all the requirements are met.

    3. Output Parameters

    Parameter Name Type Description
    InstanceIdSet Array of 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 states of the instances in InstancesSet in the response. If the state of an instance changes from "pending" to "running", it means that the instance has been created successfully.
    RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Creating an instance with the fewest parameters specified

    This example shows you how to create an instance in Guangzhou Zone 2 from the image whose image ID is img-pmqg1cw7. In the example, only the two required parameters, namely Placement.Zone and ImageId, are specified. Default values are used for the other parameters.

    Input Example

    GET https://cvm.tencentcloudapi.com/?Action=RunInstances
&Placement.Zone=ap-shanghai-2
&ImageId=img-pmqg1cw7
&<common request parameters>

    Output Example

    {
  "Response": {
    "InstanceIdSet": [
      "ins-1vogaxgk"
    ],
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

    Example2 Purchasing a pay-as-you-go instance billed on an hourly basis

    In this example, the instance has the following configurations. Availability zone: Guangzhou Zone 2; billing method: hourly, pay-as-you-go; image ID: img-pmqg1cw7; model: S2.SMALL1 (Standard S1, 1-core, 1 GB); system disk: 50 GB basic local disk; data disk: 100 GB basic local disk; network: basic network; public network billing method: bill-by-traffic, hourly, pay-as-you-go; maximum public network bandwidth: 10 Mbps; public IP address: assigned; instance name: QCLOUD-TEST; login password: Qcloud@TestApi123++; Cloud Monitor service: enabled; Cloud Security service: enabled; quantity: 1.

    Input Example

    GET https://cvm.tencentcloudapi.com/?Action=RunInstances
&Placement.Zone=ap-shanghai-2
&InstanceChargeType=PREPAID
&InstanceChargePrepaid.Period=1
&InstanceChargePrepaid.RenewFlag=NOTIFY_AND_AUTO_RENEW
&ImageId=img-pmqg1cw7
&InstanceType=S5.16XLARGE256
&SystemDisk.DiskType=CLOUD_PREMIUM
&SystemDisk.DiskSize=50
&DataDisks.0.DiskType=CLOUD_PREMIUM
&DataDisks.0.DiskSize=100
&InternetAccessible.InternetChargeType=TRAFFIC_POSTPAID_BY_HOUR
&InternetAccessible.InternetMaxBandwidthOut=10
&InternetAccessible.PublicIpAssigned=TRUE
&InstanceName=QCLOUD-TEST
&LoginSettings.Password=Qcloud@TestApi123++
&EnhancedService.SecurityService.Enabled=TRUE
&EnhancedService.MonitorService.Enabled=TRUE
&InstanceCount=1
&<common request parameters>

    Output Example

    {
  "Response": {
    "InstanceIdSet": [
      "ins-bfw5zq3y"
    ],
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

    Example3 Purchasing a pay-as-you-go instance billed on an hourly basis

    In this example, the instance has the following configurations. Availability zone: Guangzhou Zone 2; billing method: hourly, pay-as-you-go; image ID: img-pmqg1cw7; model: S2.SMALL1 (Standard S1, 1-core, 1 GB); system disk: 50 GB basic local disk; data disk: 100 GB basic local disk; network: basic network; public network billing method: bill-by-traffic, hourly, pay-as-you-go; maximum public network bandwidth: 10 Mbps; public IP address: assigned; instance name: QCLOUD-TEST; login password: Qcloud@TestApi123++; Cloud Monitor service: enabled; Cloud Security service: enabled; quantity: 1.

    Input Example

    GET https://cvm.tencentcloudapi.com/?Action=RunInstances
&Placement.Zone=ap-shanghai-2
&InstanceChargeType=POSTPAID_BY_HOUR
&ImageId=img-pmqg1cw7
&InstanceType=S5.16XLARGE256
&SystemDisk.DiskType=CLOUD_PREMIUM
&SystemDisk.DiskSize=50
&DataDisks.0.DiskType=CLOUD_PREMIUM
&DataDisks.0.DiskSize=100
&InternetAccessible.InternetChargeType=TRAFFIC_POSTPAID_BY_HOUR
&InternetAccessible.InternetMaxBandwidthOut=10
&InternetAccessible.PublicIpAssigned=TRUE
&InstanceName=QCLOUD-TEST
&LoginSettings.Password=Qcloud@TestApi123++
&EnhancedService.SecurityService.Enabled=TRUE
&EnhancedService.MonitorService.Enabled=TRUE
&InstanceCount=1
&<common request parameters>

    Output Example

    {
  "Response": {
    "InstanceIdSet": [
      "ins-32kcaqoa"
    ],
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

    Example4 Purchase a dedicated CVM

    In this example, the dedicated CVM instance has the following configurations. Availability zone: Guangzhou Zone 2; CDH ID: host-q88gab4i; billing method: billed by dedicated CVMs; image ID: img-pmqg1cw7; model: 1-core, 1 GB; system disk: 50 GB basic local disk; data disk: 100 GB basic local disk; network: basic network; public network billing method: bill-by-traffic, hourly, pay-as-you-go; maximum public network bandwidth: 10 Mbps; public IP address: assigned; instance name: QCLOUD-TEST; login password: Qcloud@TestApi123++; Cloud Monitor service: enabled; Cloud Security service: enabled; quantity: 1.

    Input Example

    GET https://cvm.tencentcloudapi.com/?Action=RunInstances
&Placement.Zone=ap-shanghai-2
&Placement.HostIds.0=host-q88gab4i
&InstanceChargeType=CDHPAID
&ImageId=img-pmqg1cw7
&InstanceType=CDH_1C1G
&SystemDisk.DiskType=CLOUD_PREMIUM
&SystemDisk.DiskSize=50
&DataDisks.0.DiskType=CLOUD_PREMIUM
&DataDisks.0.DiskSize=100
&InternetAccessible.InternetChargeType=TRAFFIC_POSTPAID_BY_HOUR
&InternetAccessible.InternetMaxBandwidthOut=10
&InternetAccessible.PublicIpAssigned=TRUE
&InstanceName=QCLOUD-TEST
&LoginSettings.Password=Qcloud@TestApi123++
&EnhancedService.SecurityService.Enabled=TRUE
&EnhancedService.MonitorService.Enabled=TRUE
&InstanceCount=1
&<common request parameters>

    Output Example

    {
  "Response": {
    "InstanceIdSet": [
      "ins-0s7wsh5x"
    ],
    "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
  }
}

    Example5 Creating an instance with the VPC IP specified

    In this example, the instance has the following configurations. Availability zone: Hong Kong Zone 1; billing method: hourly, pay-as-you-go; image ID: img-dkwyg6sr; model: S1.SMALL1 (Standard S1, 1-core, 1 GB); system disk: 50 GB basic local disk; network: VPC; VPC ID: 1urkhbj4; subnet ID: dcs9x3gz; VPC IP: 10.0.0.18, 10.0.0.19; quantity: 2.

    Input Example

    GET https://cvm.tencentcloudapi.com/?Action=RunInstances
&InstanceType=S5.16XLARGE256
&SystemDisk.DiskType=CLOUD_PREMIUM
&SystemDisk.DiskSize=50
&Placement.Zone=ap-shanghai-2
&ImageId=img-dkwyg6sr
&VirtualPrivateCloud.SubnetId=subnet-dcs9x3gz
&VirtualPrivateCloud.VpcId=vpc-1urkhbj4
&VirtualPrivateCloud.PrivateIpAddresses.0=10.0.0.18
&VirtualPrivateCloud.PrivateIpAddresses.1=10.0.0.19
&InstanceCount=2
&<common request parameters>

    Output Example

    {
  "Response": {
    "InstanceIdSet": [
      "ins-0s7wsh5x",
      "ins-03lw8hok"
    ],
    "RequestId": "3c14def19-cfes-470e-b241-90787u6jf5uj"
  }
}

    5. Developer Resources

    API Explorer

    This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    AccountQualificationRestrictions Your account failed the qualification verification.
    InstancesQuotaLimitExceeded You are trying to create more instances than your remaining quota allows.
    InvalidClientToken.TooLong The specified ClientToken exceeds the maximum length of 64 bytes.
    InvalidHostId.NotFound The specified HostId does not exist, or does not belong to your account.
    InvalidInstanceName.TooLong The specified InstanceName exceeds the maximum length of 60 bytes.
    InvalidInstanceType.Malformed The specified InstanceType parameter has an invalid format.
    InvalidParameter.InstanceImageNotSupport This API does not support instance images.
    InvalidParameter.InvalidIpFormat Invalid VPC IP address format.
    InvalidParameter.LackCoreCountOrThreadPerCore CoreCount and ThreadPerCore must be specified at the same time.
    InvalidParameterCombination The parameter combination is invalid.
    InvalidParameterValue Invalid parameter value: parameter value is in the wrong format or is not supported.
    InvalidParameterValue.CoreCountValue Illegal core count.
    InvalidParameterValue.Range Invalid parameter value: invalid parameter value range.
    InvalidParameterValue.ThreadPerCoreValue Invalid thread count per core.
    InvalidPassword Invalid password. The specified password does not meet the password requirements. For example, the password length does not meet the requirements.
    InvalidPeriod Invalid period. Valid values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 24, 36]; unit: month.
    InvalidPermission This operation is not supported for the account.
    InvalidZone.MismatchRegion The specified zone does not exist.
    MissingParameter Missing parameter: a required parameter is missing.
    VpcAddrNotInSubNet The VPC IP address is not in the subnet.
    VpcIpIsUsed The VPC IP address is already occupied.