Tencent Cloud's Java SDK is generated, versioned per product, and picky about credentials

A generated client for the Cloud API 3.0 surface

This repository is the Tencent Cloud API 3.0 SDK for Java, and it is published under Apache 2.0 with Java as the primary language. There are no GitHub releases, and the last push was on 2026-10-19, with the default branch `master`.

The repository layout shows what kind of project this is. There is `src/` for the generated and handwritten code, `vendor/` for the bundled jars, `pom.xml` for the Maven build, and an `examples/` directory with one folder per product area, among them `cvm/`, `cls/`, `common/`, `cr/`, `ecc/`, `ess/`, `hcm/`, `hunyuan/`, `soe/` and `tci/`. There is also `products.md`, which lists the package name abbreviation for each product, and two changelogs, `CHANGELOG.md` and `SERVICE_CHANGELOG.md`, one for the SDK and one for the services it covers.

The dependency requirements in the README are short. You need JDK 7 or later, you need the relevant product enabled from the Tencent Cloud console, and you need a SecretID, a SecretKey and the endpoint to call. The endpoint generally takes the form `*.tencentcloudapi.com`, with the CVM endpoint given as `cvm.tencentcloudapi.com` and each product documented separately.

One build detail is worth knowing before you compile anything. From version 3.1.500 onwards, the project is compiled and published with KonaJDK, Tencent's own JDK build.

Credentials and the signature are separate concerns

The credential model is described in the setup section, and it has two halves that are often conflated.

The SecretID identifies who is making the API call, and the SecretKey is the key used to encrypt the signature string, which the server then verifies. The README is emphatic that the SecretKey must be kept strictly and must not leak, which is why the example code creates the credential from environment variables rather than from literals.

Separately from the credentials, the client configuration decides how the request is made. A `ClientProfile` carries the sign method, and the default is `ClientProfile.SIGN_TC3_256`, which is TC3-HMAC-SHA256. It also carries the language for common parameters, and from version 3.1.16 you can set `Language.EN_US` or `Language.ZH_CN`, with the default being not to send the parameter at all. Since 3.1.80 the SDK can also print debug logs, switched with `setDebug(true)`.

So there are two objects, and a third one nested inside the second. A `Credential` holds who you are, an `HttpProfile` holds the transport details, and a `ClientProfile` holds the sign method, the language and the `HttpProfile`.

Install one product or all of them, never both

Maven is the recommended installation route, and there are two artifacts.

The full product SDK contains the calling code for every cloud product and is large in size, and the README says that for scenarios sensitive to size, installing the specific product SDK is recommended. The specific package is named after the product, with the artifact id following the `tencentcloud-sdk-java-` prefix, and the product package abbreviations are listed in `products.md`.

The two routes are mutually exclusive. The README states that installing the all-product SDK and installing specific product SDKs are two ways and you can only choose one of them. And if you install multiple product packages, it recommends keeping them on the same version as the common package, so the generated request and response classes line up.

The version to pin, at the time of writing, is 3.1.1000, and the artifact identifiers are `com.tencentcloudapi` for the group and `tencentcloud-sdk-java` for the full bundle.

For a Java service that calls two or three products, the per-product packages are clearly the right choice, because the all-product bundle pulls in a client and a model class for every service Tencent offers.

A Maven index delay and a version to avoid

Two version details in the README will save you time.

The first is about how releases become visible. The SDK confirms a `mvn deploy` before a GitHub tag is updated, but the Maven repository's index lags behind, so a newly published version can be missing from the Maven site search for roughly one to two hours. The README is clear that this does not affect using the latest version and that commands such as `mvn compile` work normally, so the failure to find a version in search is not a problem with your setup.

The second is a warning. The version 4.0.11 shown in the Maven repository is a deprecated version, the maintainers have contacted Maven to have the jar removed, but the index entry cannot be cleared, and the instruction is not to use it. That is a specific trap: the artifact resolves, the index still shows it, and it is the wrong build.

For anyone who cannot reach the official repository, the README suggests adding a mirror to the `mirrors` section of the Maven `settings.xml`:

    <mirror>
      <id>tencent</id>
      <name>tencent maven mirror</name>
      <url>https://mirrors.tencent.com/nexus/repository/maven-public/</url>
      <mirrorOf>*</mirrorOf>
    </mirror>

Installing from a source archive

The README also documents installing from a source package, and the steps are four.

Download the source archive from CNB, from GitHub or from Gitee, extract it into a suitable location in your project, place the jars under the `vendor` directory where the Java toolchain can find them, and then refer to the examples for the import style you need.

That third step is the one with a practical consequence. The `vendor` directory in the repository is part of the build, so a source install means you are taking on a set of jars that your build has to locate, which is why the Maven route is the recommended one and why the source route is documented mainly for environments where a repository is not an option.

The examples directory is the same one the product list refers to, with a folder per product area, so the source install and the product packages serve the same purpose: they give you a working client for a specific service.

A first call: listing CVM instances

The worked example is the `DescribeInstances` interface, the one that lists instances, and the simplified version is short enough to read as the shape of every call.

The imports come from three packages, the common credential and exception classes, the product client, and the request and response models:

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
import com.tencentcloudapi.cvm.v20170312.CvmClient;
import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesRequest;
import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesResponse;

Note the version in the package path, `v20170312`, which is the API version rather than the SDK version. Then the credential comes from the environment, and the client is created with a region:

            Credential cred = new Credential(System.getenv("TENCENTCLOUD_SECRET_ID"), System.getenv("TENCENTCLOUD_SECRET_KEY"));
            CvmClient client = new CvmClient(cred, "ap-shanghai");

The request object is filled in, the call is made, and the response is printed as JSON, with the call wrapped in a `try` block that catches `TencentCloudSDKException`.

The README also shows the alternative to the environment variable form, which is a `Credential` built from two string literals, and it marks that line as not recommended, with the reason given in the surrounding comments: hardcoding the keys into code risks them leaking with the code, and the advice is to set them in an environment variable or a configuration file instead.

The detailed version: profiles, timeouts and filters

The longer example adds the optional configuration, and it is the part worth copying when you move beyond a first call.

The `HttpProfile` controls the transport. It can set the request method, with `GET` as an option and `POST` as the default. It sets the connection timeout, the write timeout and the read timeout, each in seconds, with the defaults being 60 seconds for the connection and 0 for the other two. Since version 3.0.96 it can set an HTTP proxy, through a proxy host and a proxy port. And it sets the endpoint, with the example using the CVM endpoint in the Shanghai region, while the default is to connect to the nearest region.

The `ClientProfile` then holds the sign method, the `HttpProfile` itself, the debug flag and the language. The CVM client is then constructed with the credential, the region and the profile, all three being optional apart from the credential and the region.

The request itself is filled in through the request object's member variables, and the example queries by zone with a `Filter` whose name is `zone` and whose values are `ap-shanghai-1` and `ap-shanghai-2`, then passes the filter to the request with `setFilters`. The comment on the request object explains where to find the parameter definitions, in the official interface documentation or in the definition of the request class itself.

So the call pattern is consistent throughout: a request object per interface, a response object that matches it, and a client configured once.

Editorial conclusion

Adopt tencentcloud-sdk-java when you are calling Tencent Cloud products from a Java service and want a generated, per-product client rather than hand written HTTP calls. Do not install the all-product bundle for a service that uses one or two products, since the README explicitly warns that it is large, and do not mix the two installation styles. Verify first that the product packages you install sit on the same version as the common package, that the artifact version you pin is not the deprecated 4.0.11, that your credentials come from environment variables rather than source, and that the endpoint you configure matches the region your resources live in.

Frequently asked questions

Official sources

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