Tenant Cloud Compute Cloud Virtual Machine Instance APIs CloneInstance

CloneInstance

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

1. Interface Description

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

This API (CloneInstance) is used to clone an instance with a specified configuration.

  • After an instance is successfully created, it will automatically start up, and the Instance Status will change to Running.
  • The purchase of prepaid instances will deduct the amount required for the instance purchase in advance. The purchase of pay-per-hour postpaid instances will freeze the amount required for the instance purchase within 1 hour in advance. Make sure your account balance is sufficient before calling this API.
  • This API is an asynchronous API. After the creation request is successfully sent, a list of instance IDs will be returned. At this point, the creation of the instance is not immediately completed. During this period, the instance status will be Preparing. You can query the status of the corresponding instance by calling the API DescribeInstancesStatus to determine whether the production ultimately succeeded. If the instance status changes from Preparing to Running, it indicates that the instance is successfully created.

Default interface request rate limit: 10 times per second.

Interface update time: 2025-08-05 00:55:05.

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: CloneInstance
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. PREPAID: Prepaid, which is monthly subscription. POSTPAID_BY_HOUR: Pay-as-you-go on an hourly basis. CDHPAID: Dedicated host billing (created based on CVM Dedicated Host (CDH) and resources of the host not charged). In this billing mode, you must fill in the default value of placement.hostid parameter: POSTPAID_BY_HOUR.
Example: PREPAID
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: S2.SMALL1
    		•
    ImageId Yes No String Specifies a valid Image ID in the formats such as img-xxx. There are four types of images: 1. Public Image 2. Custom Image 3. Shared Image 4. Service Market Image. The IDs of the Public Image, Custom Image, and Shared Image can be found by logging in to the Console. The ID of the Service Market Image can be found in the Cloud Marketplace. By calling the DescribeImages API and inputting InstanceType, you can get the list of images supported by the current model from the returned ImageId field.
    Example: img-c1otssej
    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: 12
    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: alice-1
    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: ["sec-61dyt49h"]
    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: 12dasfa423fdasq5twerra
    SpotPrice No No String Used to specify price production, currently mainly used to spot instances.
    Example: 2050
    HostName No No String The HostName for Cloud Virtual Machine (CVM) cannot have a dot (.) or hyphen (-) at the beginning or end, and they can not be used consecutively. Windows instances: The name must have [2, 15] characters, which can include letters (case insensitive), numbers, and hyphens (-), but cannot include dots (.) or be comprised entirely of numbers. Other types of instances (such as Linux): The name must have [2, 60] characters, which can include multiple dots, and each segment between dots can include letters (case insensitive), numbers, and hyphens (-).
    Example: alice-host
    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: IyEvYmluL2Jhc2gKZWNobyAiSGVsbG8gVGVuY2VudCBDbG91ZC4iCg==
    DisasterRecoverGroupIds No No Array of String Placement group ID, only one can be specified.
    Example: ["ps-l86ok62z"]
    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
    InstanceId Yes No String Instance ID Needs to Be Cloned
    Example: ins-61dyt49h
    DataDiskIds Yes No Array of String Data Disk ID Needs to be Cloned for Instance
    Example: ["disk-61dyt49h"]
    DisableApiTermination No No Bool Whether to allow instance deletion through the API.
    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-61dyt49h"]
    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
    UnauthorizedOperation.ProjectNotFound This operation is not allowed. Please ensure this account is in the selected project.