CreateLoadBalancer

Download PDF

Last updated: 2025-11-25 10:11:27

CreateLoadBalancer

Last updated: 2025-11-25 10:11:27

Download PDF

1. API Description

Domain name for API request: clb.intl.tencentcloudapi.com.

This API (CreateLoadBalancer) is used to create a CLB instance. To use the CLB service, you first need to purchase one or more instances. After this API is called successfully, a unique instance ID will be returned. There are two types of instances: public network and private network. For more information, see the product types in the product documentation.
Note: (1) To apply for a CLB instance in the specified AZ and cross-AZ disaster recovery, please submit a ticket; (2) Currently, IPv6 is supported only in Beijing, Shanghai, and Guangzhou regions.
This is an async API. After it is returned successfully, you can call the DescribeLoadBalancers API to query the status of the instance (such as creating and normal) to check whether it is successfully created.

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

We recommend you to use API Explorer

Try it

API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

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 Params. The value used for this API: CreateLoadBalancer.
Version	Yes	String	Common Params. The value used for this API: 2018-03-17.
Region	Yes	String	Common Params. For more information, please see the list of regions supported by the product.
LoadBalancerType	Yes	String	CLB instance network type: OPEN: public network; INTERNAL: private network.
Forward	No	Integer	CLB instance type. Valid value: 1 (generic CLB instance).
LoadBalancerName	No	String	CLB instance name, which takes effect only when only one instance is to be created in the request. It can consist 1 to 60 letters, digits, hyphens (-), or underscores (_). Note: if the name of the new CLB instance already exists, a default name will be generated automatically.
VpcId	No	String	Network ID of the target device on the CLB backend, such as `vpc-12345678`, which can be obtained through the `DescribeVpcEx` API. If this parameter is not entered, `DefaultVPC` is used by default. This parameter is required when creating a private network instance.
SubnetId	No	String	A subnet ID should be specified when you purchase a private network CLB instance under a VPC. The VIP of the private network CLB instance is in this subnet. This parameter is required when you create a private network CLB instance but not supported when you create a public network IPv4 CLB instance.
ProjectId	No	Integer	ID of the project to which a CLB instance belongs, which can be obtained through the `DescribeProject` API. If this parameter is not entered, the default project will be used.
AddressIPVersion	No	String	It's only applicable to public network CLB instances. IP version. Values: `IPV4`, `IPV6` and `IPv6FullChain` (case-insensitive). Default: `IPV4`. Note: `IPV6` indicates IPv6 NAT64, while `IPv6FullChain` indicates IPv6.
Number	No	Integer	Specifies the count of cloud load balancers to create, with a default value of 1. the count must not exceed the maximum value allowed for the account, with a default creation maximum value of 20.
MasterZoneId	No	String	Applicable only to public network IPv4 cloud load balancer instances. specifies the primary AZ ID for cross-az disaster recovery. both AZ ID and name are supported, such as 100001 or ap-guangzhou-1. Note: the primary AZ loads traffic. the secondary AZ does not load traffic by default and is used only if the primary AZ becomes unavailable.
ZoneId	No	String	Applicable only to public network IPv4 clb instances. specifies the AZ ID or availability zone name for creating a clb instance. for example, 100001 or ap-guangzhou-1.
InternetAccessible	No	InternetAccessible	Network billing mode by the maximum outbound bandwidth. It applies only to private network LCU-supported instances and all public network instances. The feature of purchasing monthly subscription instances via an API is under grayscale release. If you want to experience this feature, submit a ticket.
VipIsp	No	String	ISP of VIP. Values: `CMCC` (China Mobile), `CUCC` (China Unicom) and `CTCC` (China Telecom). You need to activate static single-line IPs. This feature is in beta and is only available in Guangzhou, Shanghai, Nanjing, Jinan, Hangzhou, Fuzhou, Beijing, Shijiazhuang, Wuhan, Changsha, Chengdu and Chongqing regions. To try it out, please contact your sales rep. If it's specified, the network billing mode must be `BANDWIDTH_PACKAGE`. If it's not specified, BGP is used by default. To query ISPs supported in a region, please use DescribeResources.
Tags.N	No	Array of TagInfo	Tags the CLB instance when purchasing it. Up to 20 tag key value pairs are supported.
Vip	No	String	Specifies the VIP for the application of a CLB instance. This parameter is optional. If you do not specify this parameter, the system automatically assigns a value for the parameter. IPv4 and IPv6 CLB instances support this parameter, but IPv6 NAT64 CLB instances do not. Note: If the specified VIP is occupied or is not within the IP range of the specified VPC subnet, you cannot use the VIP to create a CLB instance in a private network or an IPv6 BGP CLB instance in a public network.
BandwidthPackageId	No	String	BANDWIDTH PACKAGE ID, which can be obtained through the DescribeBandwidthPackages api. specifies the BANDWIDTH PACKAGE ID. when this parameter is specified, the network billing mode (InternetAccessible.InternetChargeType) supports only billing by BANDWIDTH PACKAGE (BANDWIDTH_PACKAGE). the attributes of the BANDWIDTH PACKAGE determine the settlement method. for IPv6 clb instances purchased by non-promoted users, if the operator type is not BGP, the BANDWIDTH PACKAGE ID cannot be specified.
ExclusiveCluster	No	ExclusiveCluster	Information about the dedicated CLB instance. You must specify this parameter when you create a dedicated CLB instance in a private network.
SlaType	No	String	Specification of the LCU-supported instance. If you need to create an LCU-supported instance, this parameter is required. Valid values: clb.c2.medium: Standard clb.c3.small: Advanced 1 clb.c3.medium: Advanced 2 clb.c4.small: Super Large 1 clb.c4.medium: Super Large 2 clb.c4.large: Super Large 3 clb.c4.xlarge: Super Large 4 If you need to create a shared instance, this parameter is not required. For specification details, see Instance Specifications Comparison.
ClusterIds.N	No	Array of String	Cluster ID. This cluster identifier is used for configuring a public cloud exclusive cluster or a cloud dedicated cluster. To apply for a public cloud exclusive cluster, submit a ticket. For cloud dedicated clusters, see the descriptions in Cloud Dedicated Cluster.
ClientToken	No	String	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 idempotency of the request cannot be guaranteed.
SnatPro	No	Boolean	Whether Binding IPs of other VPCs feature switch
SnatIps.N	No	Array of SnatIp	Creates `SnatIp` when the binding IPs of other VPCs feature is enabled
ClusterTag	No	String	Tag for the STGW exclusive cluster.
SlaveZoneId	No	String	Applicable only to public network IPv4 clb instances. specifies the secondary AZ ID for cross-az disaster recovery. both AZ ID and name are supported, such as 100001 or ap-guangzhou-1. Note: The secondary AZ sustains traffic when the primary AZ encounters faults. You can call the DescribeResources API to query the list of primary/secondary AZs in a region. If you want to experience this feature, submit a ticket.
EipAddressId	No	String	The unique ID of EIP, which can be queried through the DescribeAddresses API (https://www.tencentcloud.comom/document/product/215/16702?from_cn_redirect=1). format: EIP-qhx8udkc. applicable only to private network clb binding EIP.
LoadBalancerPassToTarget	No	Boolean	Specifies whether to allow CLB traffic to the Target. enable (true): verify security groups on CLB. disable (false): verify security groups on both CLB and backend instances. IPv6 CLB security group default permit, this parameter is not required.
DynamicVip	No	Boolean	Upgrades to domain name-based CLB
Egress	No	String	Network egress point
LBChargePrepaid	No	LBChargePrepaid	Prepayment-related attributes of a CLB instance. The feature of purchasing monthly subscription instances via an API is under grayscale release. If you want to experience this feature, submit a ticket.
LBChargeType	No	String	Billing type of a CLB instance. Valid values: POSTPAID_BY_HOUR and PREPAID. Default value: POSTPAID_BY_HOUR. The feature of purchasing monthly subscription instances via an API is under grayscale release. If you want to experience this feature, submit a ticket.
AccessLogTopicId	No	String	Topic ID of logs of traffic access over layer-7 protocols.
AdvancedRoute	No	Boolean	Whether layer-7 advanced routing is enabled.

3. Output Parameters

Parameter Name	Type	Description
LoadBalancerIds	Array of String	Array of unique CLB instance IDs. This field may return `null` in some cases, such as there is delay during instance creation. You can query the IDs of the created instances by invoking `DescribeTaskStatus` with the `RequestId` or `DealName` returned by this API. Note: This field may return `null`, indicating that no valid values can be obtained.
DealName	String	Order ID. Note: this field may return `null`, indicating that no valid values can be obtained.
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.

4. Example

Example1 Creating a Public Network CLB Instance

This example shows you how to create a public network CLB instance in a VPC.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateLoadBalancer
<Common request parameters>

{
    "Forward": 1,
    "ProjectId": 0,
    "LoadBalancerType": "OPEN",
    "VpcId": "vpc-30xqxt9p",
    "LoadBalancerName": "test-open"
}

Output Example

{
    "Response": {
        "LoadBalancerIds": [
            "lb-6efswuxa"
        ],
        "DealName": "20220101660009831340631",
        "RequestId": "9b3f0b57-fb64-4918-8dd6-ce02604fb52c"
    }
}

Example2 Creating a Private Network CLB Instance

This example shows you how to create a private network CLB instance in a VPC.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateLoadBalancer
<Common request parameters>

{
    "Forward": 1,
    "SubnetId": "subnet-k57djpow",
    "LoadBalancerType": "INTERNAL",
    "VpcId": "vpc-30xqxt9p",
    "LoadBalancerName": "test_internal"
}

Output Example

{
    "Response": {
        "LoadBalancerIds": [
            "lb-kmfrnqci"
        ],
        "DealName": "20211230660009761735781",
        "RequestId": "7ffa6830-cd1b-4bc4-8e24-1688885f594a"
    }
}

5. Developer Resources

SDK

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

Command Line Interface

Tencent Cloud CLI 3.0

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
FailedOperation	Operation failed.
InternalError	Internal error.
InvalidParameter	Parameter error.
InvalidParameter.ClientTokenLimitExceeded	To ensure no resource leakage and maintain the ID idempotence of created resources, ClientToken is used to create resources. If the order process has ended and shipment failed, or the order process has not been updated for a long time, a message will indicate that the current ClientToken has timed out.
InvalidParameter.FormatError	Wrong parameter format.
InvalidParameterValue	Incorrect parameter value.
InvalidParameterValue.Length	Wrong parameter length.
InvalidParameterValue.Range	Wrong parameter value range.
LimitExceeded	Quota exceeded.
MissingParameter	Missing parameter.
ResourceInsufficient	Insufficient resources.
UnauthorizedOperation	Unauthorized operation.
UnsupportedOperation	Unsupported operation.

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

tencent cloud

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Example1 Creating a Public Network CLB Instance

Input Example

Output Example

Example2 Creating a Private Network CLB Instance

Input Example

Output Example

5. Developer Resources

SDK

Command Line Interface

6. Error Code