tencentcloud-sdk-go: installing only the Go packages a service needs

One Request struct and one Response struct per cloud API

The core design rule of this SDK is stated plainly in the project documentation: every interface has a corresponding Request struct and a Response struct. The cloud virtual machine example used throughout the documentation is DescribeInstances, which maps to DescribeInstancesRequest and DescribeInstancesResponse.

That convention is the whole API shape. You build a request struct, fill in fields, hand it to a product client, and get back a response struct. Because request fields are generated per interface rather than shared, a field that the product does not accept simply does not exist on the struct, and the compiler is what tells you so.

The import path carries the product and its API version together. The virtual machine package is imported as cvm from the path ending in cvm/v20170312, so the API date is part of the package identity rather than a runtime setting.

The package lives under the tencentcloud directory and the repository holds one top level directory per product family, with an examples directory that includes cvm, vpc, monitor, cls, ssm and others. That layout is the clearest sign of how the SDK is meant to scale: it is a set of independent API packages rather than one lumped client.

Per-product installs so your image does not carry the whole catalogue

Since v1.0.170 the SDK supports downloading only the base package and the product package you actually need, for example cvm. The documentation is explicit about the reason: it avoids pulling every product, which speeds up building images and compiling.

The base package comes first:

    go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common

Then the product package:

    go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm

The README points to products.md for the abbreviated package name of each product. The same section sets two conditions on this route. It only works with Go Modules dependency management, meaning the environment variable GO111MODULE must be auto or on and your project must have run go mod init. And if you install several product packages, the documentation recommends keeping them on the same version as the common package.

For teams that means the dependency list in go.mod is a deliberate statement of which cloud surfaces your service can reach, instead of a mirror of the entire Tencent Cloud API surface. The cost of that control is a version alignment rule you have to honour yourself.

GOPROXY mirror for the module download path

The installation section recommends a Tencent Cloud mirror for the module proxy, which is what the documentation calls the recommended way to get the packages. On Linux or macOS the environment variable is exported like this:

    export GOPROXY=https://mirrors.tencent.com/go/

The documentation gives a separate form for Windows, where the variable is set with the set command rather than exported. The point of a vendor mirror is that module downloads do not have to come from the public proxy for every artefact, which matters most for a network in mainland China and for CI runners that would otherwise each hit the default proxy on a cold cache.

There is also a source install route. The documentation directs you to a CNB repository, a GitHub repository or a Gitee repository, to download the latest code, unpack it and install it into the $GOPATH/src/github.com/tencentcloud directory. That path assumes a GOPATH layout rather than Go Modules, and it is the one to use if you are working on the SDK itself rather than consuming it.

One environment fact applies regardless of route: Go 1.9 or later is required, and Go 1.14 or later if you use go mod. Some products also need the corresponding service enabled in the console before its interfaces can be called, which is a setup step outside the code.

The client profile and the defaults the documentation asks you to leave alone

Before creating a client you can adjust a profile object, and the configuration section opens with a recommendation to use the defaults unless you have a specific reason. The detailed example shows which knobs exist:

        cpf.HttpProfile.ReqMethod = "POST"
        cpf.HttpProfile.ReqTimeout = 30
        cpf.HttpProfile.Endpoint = "cvm.tencentcloudapi.com"
        cpf.SignMethod = "TC3-HMAC-SHA256"
        cpf.Language = "en-US"

Each line carries a stated reason in the documentation. POST is the default and GET cannot handle some larger requests. The timeout has a default value you should look up in the source rather than guess, and 30 is shown as an explicit override in the example. The SDK picks the domain automatically, except for financial regions, where you must set the endpoint yourself, for example cvm.ap-shanghai-fsi.tencentcloudapi.com. TC3-HMAC-SHA256 is the default signing method and is described as safer while costing a little performance. The default language is zh-CN, and en-US is available, but the documentation notes that most products or interfaces do not return fully translated text.

That last point is a trap worth naming: switching the language does not give you an English API, it only changes what the service is willing to translate.

Credentials from the environment and the NewTokenCredential alternative

The documentation is blunt about hardcoding a key pair in source, calling it a security risk because code can leak, and recommending environment variables or a configuration file instead. The simplified example builds the credential from two environment variables:

	credential := common.NewCredential(
		os.Getenv("TENCENTCLOUD_SECRET_ID"),
		os.Getenv("TENCENTCLOUD_SECRET_KEY"),
	)

The same example documents a second constructor, NewTokenCredential, for temporary credentials with a token, and points to a Tencent Cloud documentation page on how to obtain them. The dependency section makes the same point, suggesting temporary security credentials over long lived keys where that is possible.

The client is then created with the credential, a region and a profile:

	client, _ := cvm.NewClient(credential, regions.Guangzhou, profile.NewClientProfile())

The region argument accepts a literal such as ap-guangzhou or one of the preset constants in the regions package, with regions.Guangzhou used in the example. Notice that the error return from NewClient is discarded with a blank identifier in both examples, so if you are picky about error handling you will want to handle it in your own code.

Pointer-style setters and separating API errors from transport errors

The SDK sets fields through pointers, even for basic types, and provides helper constructors for them. The documentation demonstrates the scalar case with request.Limit = common.Int64Ptr(1) to cap the number of returned instances, and the array case with common.StringPtrs for a slice of instance identifiers.

Nested structures are built as slices of pointers to product structs, so a filter with a name and a list of values is written as a slice literal of Filter pointers with StringPtr and StringPtrs inside. The example also shows a commented out InstanceIds assignment, because that field conflicts with the Filter parameter in the same request, which is a fair illustration of how product specific constraints surface in the types.

Error handling has two layers. A returned error can be type asserted to errors.TencentCloudSDKError, which identifies an error returned by the API itself, and the example prints that case and returns. Anything else is treated as a non-SDK failure and the example panics on it.

	if _, ok := err.(*errors.TencentCloudSDKError); ok {
		fmt.Printf("An API error has returned: %s", err)
		return
	}
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s\n", response.ToJsonString())

The response is rendered with ToJsonString, so a caller that wants the structured data works with the response struct rather than with parsed JSON.

The v3.x to v1.x version drop and the tags that were removed

One detail in the installation notes deserves attention from anyone with an existing dependency. To support go mod, the SDK version numbers were reduced from v3.x to v1.x. On 2021.05.10 all tags of the form v3.0.* and 3.0.* were removed from the repository. The project points at a commit2tag file in the project root for tracing the earlier tags.

For a team upgrading an old service, that means a go.mod line pinned to a v3 tag cannot be resolved from the tag namespace any more, and the fix is to find the equivalent commit through commit2tag rather than to expect the tag to come back.

The repository has no GitHub releases at all. Change history is instead split across CHANGELOG.md and SERVICE_CHANGELOG.md, the latter covering service level changes, and the repository also carries a testing directory alongside examples and a products.md index. The last push was on 2026-10-19.

The licence is Apache-2.0, with a LICENSE file at the repository root. Permissive terms cover both reading the SDK and shipping it inside your own product, though any modification and redistribution question should be reviewed against the licence text itself rather than assumed.

Where this SDK is the wrong tool

Several boundaries are visible in the documentation itself.

The first is version granularity. The recommendation to keep every product package on the same version as the common package means a team using several products cannot upgrade one of them independently, which slows the response to a security fix in a single product.

The second is language. This is the Go SDK. If your service is written in Python, Java or TypeScript, the value of the per-product install pattern and the client profile does not transfer, and you would be reading this repository to understand the API shape rather than to depend on it.

The third is that the SDK covers the Tencent Cloud API 3.0 platform. It is a client for one cloud provider. If the requirement is a cloud abstraction that spans several providers, this package is the wrong shape, because the product packages, the endpoint handling and the signing method are all Tencent Cloud specific by construction.

The fourth is operational. The documentation does not describe how to refresh a temporary credential inside a long running process, how to rotate keys without restarting, or how to classify the many API error codes beyond the type assertion to errors.TencentCloudSDKError. Those behaviours have to come from the platform documentation and from your own code.

Editorial conclusion

Adopt tencentcloud-sdk-go when your Go service talks to one or a few Tencent Cloud products and you want per-product dependency control instead of the whole catalogue. Do not adopt it if your build still relies on the removed v3.0.* tags, since those were deleted on 2021.05.10 and older references must be resolved through the commit2tag file. Before you commit, check the Go version in your image, confirm that GO111MODULE is set to auto or on for the per-product install path, and verify that every product package you pull sits on the same version as the common package.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. TencentCloud/tencentcloud-sdk-go on GitHub