tencent cloud

APIs

ドキュメントAPIsCloud Load BalancerInstance APIsCreateLoadBalancer

CreateLoadBalancer

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-06-17 17:21:42

1. API Description

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

This API is used to create a Cloud Load Balancer instance (this interface supports only pay-as-you-go CLB instances. For annual/monthly subscription, proceed to purchase through the console). To use the CLB service, you must purchase one or more CLB instances. After successfully calling the API, the unique ID of the CLB instance will be returned. CLB instances are divided into public network and private network types. For details, refer to the product type in the product description.
Note: (1) To apply for Cloud Load Balancer (CLB) in a specified availability zone or cross-zone disaster recovery (only supported in Hong Kong (China)), submit a request if you need to experience the feature. (2) Currently only Beijing, Shanghai, and Guangzhou support IPv6. (3) The default purchase quota for an account in each region is 100 for public network and 100 for private network.
This is an async API. After the API returns successfully, you can use the DescribeLoadBalancers API to query the status of the Cloud Load Balancer instance (such as creating and normal) to confirm whether the creation is successful.

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: 2023-04-17.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
LoadBalancerType Yes String

Network type of the Cloud Load Balancer instance:
OPEN: public network attribute, INTERNAL: private network attribute.
Forward No Integer

Type of the Cloud Load Balancer instance. 1: Common Cloud Load Balancer instance. Currently only support input 1.
LoadBalancerName No String

The name of a Cloud Load Balancer instance takes effect only when creating an instance. Rule: 1-80 characters in internationally compatible languages, including English letters, Chinese characters, digits, hyphens "-", underscores "_", and other common characters (Unicode supplementary characters such as emojis and rare Chinese characters are forbidden). Note: If the name is identical to that of an existing Cloud Load Balancer instance in the system, the system will automatically generate a name for the newly created CLB instance.
VpcId No String

The network ID of the backend target device belonging to the Cloud Load Balancer, such as vpc-12345678, can be obtained through the DescribeVpcs API. It defaults to DefaultVPC if this parameter is not specified. This parameter is required when creating a private network CLB instance.
SubnetId No String

A subnet ID must be specified when you purchase a private network CLB instance under a VPC. The VIP of the private network CLB instance is generated 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

The project ID associated with the Cloud Load Balancer instance can be obtained through the DescribeProject API. If this parameter is left blank, it will be used as the default project.
AddressIPVersion No String

Applicable only to public network CLB. IP version, valid values: IPV4, IPV6, IPv6FullChain, case-insensitive, default value IPV4. Description: A value of IPV6 means IPV6 NAT64 version; a value of IPv6FullChain means IPv6 version.
Number No Integer

Count of Cloud Load Balancers to create. Default value: 1.
MasterZoneId No String

Applicable only to public network IPv4 Cloud Load Balancer. Sets the primary AZ ID for cross-AZ disaster recovery, 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. Currently, primary and secondary AZs are supported only for IPv4 CLB instances in Guangzhou, Shanghai, Nanjing, Beijing, Chengdu, Shenzhen Finance, Hong Kong (China), Seoul, Frankfurt, and Singapore regions. You can call the DescribeResources API to query the primary AZ list of a region. If you need to experience this feature, submit a ticket.
ZoneId No String

Applicable only to public network load balancing with IPv4 version. Availability zone ID. Designated availability zone to create a CLB instance, for example: ap-guangzhou-1.
InternetAccessible No InternetAccessible

Maximum outbound bandwidth under the network billing mode. It applies only to LCU-supported instances of the private network type and all instances of the public network type.
VipIsp No String

Applicable only to public network CLB. Currently, static single-line IP type is supported in Guangzhou, Shanghai, Nanjing, Jinan, Hangzhou, Fuzhou, Beijing, Shijiazhuang, Wuhan, Changsha, Chengdu, and Chongqing regions. If you need to experience it, contact business manager to submit a request. After approval, just select CMCC, CUCC, or CTCC as the operator type. Only can be used BANDWIDTH_PACKAGE for network billing mode. If this parameter is not specified, use BGP by default. You can check ISPs supported in a region via the DescribeResources api query.
Tags.N No Array of TagInfo

When you purchase Cloud Load Balancer (CLB), you can tag it with up to 20 tag key-value pairs.
Vip No String

Apply for a Cloud Load Balancer with a designated VIP. This parameter is optional. If this parameter is not specified, the VIP is assigned by system. This parameter is supported for IPv4 and IPv6 types but unsupported for IPv6 NAT64 type.
Note: When specifying a VIP to create a private network instance or a public IPv6 BGP instance, creation fails if the VIP is not within the specified VPC subnet or if the VIP is already occupied.
BandwidthPackageId No String

Bandwidth package ID. If this parameter is specified, the network billing mode (InternetAccessible.InternetChargeType) will only support 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 ISP type is not BGP, the bandwidth package ID cannot be specified.
ExclusiveCluster No ExclusiveCluster

Dedicated instance info. This parameter is required when creating a private network CLB instance of exclusive type.
SlaType No String

Performance capacity specification.

  • 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
  • For domestic site users, this parameter is not required when creating a shared instance. For international site users, the default purchased instance is standard if this parameter is not passed.
For specification details, see Instance Specifications Comparison.
ClientToken No String

A string used to ensure request idempotency. This string is generated by the customer and must be unique among different requests, with a maximum value of no more than 64 ASCII characters. If not specified, request idempotency cannot be guaranteed.
SnatPro No Boolean

Whether the cross-regional or cross-Vpc IP binding feature is supported.
SnatIps.N No Array of SnatIp

After enabling the cross-regional/cross-Vpc IP binding feature, create a SnatIp.
ClusterTag No String

Tag of the Stgw exclusive cluster.
SlaveZoneId No String

Applicable only to public network load balancing with IPv4 version. Sets the secondary AZ ID for cross-AZ disaster recovery, such as 100001 or ap-guangzhou-1.
Note: The secondary AZ is the availability zone that needs to carry traffic after primary availability zone failure. You can query a region's list of primary/secondary AZs via the DescribeResources API. [If you need to trial the feature, submit a ticket application]
EipAddressId No String

Unique ID of EIP, such as eip-11112222, applicable only to private network CLB to bind EIP.
LoadBalancerPassToTarget No Boolean

Allow CLB traffic to the Target. Enable (true): verify security groups on CLB; deny CLB traffic to the Target (false): verify security groups on both CLB and backend instances.
Egress No String

Network outbound
LBChargePrepaid No LBChargePrepaid

Prepaid billing attributes of the Cloud Load Balancer instance
LBChargeType No String

Billing type of the CLB instance. Valid values: POSTPAID_BY_HOUR and PREPAID. Default value: POSTPAID_BY_HOUR.
AccessLogTopicId No String

L7 access log topic ID
AdvancedRoute No Boolean

Whether layer-7 advanced routing is enabled
AvailableZoneAffinityInfo No AvailableZoneAffinityInfo

Availability zone affinity info

3. Output Parameters

Parameter Name Type Description
LoadBalancerIds Array of String

An array of unique IDs of Cloud Load Balancer instances.
In certain scenarios, such as a delay in creation, this field may return null. At this point, you can query the created resource ID through the DescribeTaskStatus API using the RequestId or DealName parameter returned by the API.
DealName String

Order ID.
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

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 Incorrect parameter format.
InvalidParameterValue Parameter value error.
InvalidParameterValue.Length Invalid parameter length.
InvalidParameterValue.Range Invalid parameter value range.
LimitExceeded The quota limit is exceeded.
MissingParameter Parameters are missing.
ResourceInsufficient Insufficient resources.
UnauthorizedOperation Unauthorized operation.
UnsupportedOperation The operation is not supported.
前の記事へ: Responses次の記事へ: CloneLoadBalancer

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック