Initialization

Updated at：2025-11-11

Confirm Endpoint

Before configuring the endpoint for SDK usage, please refer to the developer guide section on API Service Domain Name to understand Endpoint-related concepts.

Access region	Endpoint
Global	csn.baidubce.com

Retrieve AK/SK

To use Baidu AI Cloud CSN, you must have a valid AK (Access Key ID) and SK (Secret Access Key) for signature authentication. These AK/SK credentials are system-generated strings used to identify users and authenticate service access. You can obtain and review your AK/SK information using the following steps:

Create CsnClient

The CsnClient functions as the interface for CSN services, delivering developers a variety of methods to interact with CSN services.

Create a new CsnClient with AK/SK

Users can refer to the following code to create a client to access CSN with AK/SK:

                Java
                
            

                public class Sample {
    public static void main(String[] args) {
 String ACCESS_KEY_ID =<your-access-key-id>;                   // User’s Access Key ID
 String SECRET_ACCESS_KEY =<your-secret-access-key>;           // User’s Secret Access Key
        
 // Initialize a CsnClient
        BceClientConfiguration config = new BceClientConfiguration();
        config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY));
        CsnClient client = new CsnClient(config);
    }
}
            

In the code above, ACCESS_KEY_ID corresponds to “Access Key ID” in the console. SECRET_ACCESS_KEY corresponds to “Access Key Secret” in the console. For the method to retrieve them, refer to the Guide - Manage ACCESSKEY.

By default, the above method uses the default domain name as CSN's service address. If you wish to use a custom domain name, input the ENDPOINT parameter accordingly.

                Java
                
            

                String ACCESS_KEY_ID =<your-access-key-id>;                   // User’s Access Key ID
 String SECRET_ACCESS_KEY =<your-secret-access-key>;           // User’s Secret Access Key
 String ENDPOINT = <domain-name>;                               // User-defined domain name
 BceClientConfiguration config = new BceClientConfiguration();
 config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID,SECRET_ACCESS_KEY));
 config.setEndpoint(ENDPOINT);
 CsnClient client = new CsnClient(config);
            

Create CsnClient with STS

Request STS Token

CSN supports temporary third-party access authorization using the STS mechanism. STS (Security Token Service) is a temporary authorization service provided by Baidu AI Cloud. It allows you to issue credentials with customized permissions and validity periods for third-party users, enabling them to directly call Baidu AI Cloud APIs or SDKs to access the cloud resources.

To access CSN via STS, users must first request a certification string through the STS client. For instructions on obtaining STS credentials, refer to Baidu AI Cloud STS Usage Guide。

Create CsnClient with STS token

After requesting the STS token, configure it in the CsnClient. The following codes demonstrate how to create a CsnClient:

                Java
                
            

                public class StsExample {
    private static final String STS_ENDPOINT = "http://sts.bj.baidubce.com";
    private static final String ACCESS_KEY_ID = "your accesskey id";
    private static final String SECRET_ACCESS_KEY = "your secret accesskey";
    public static void main(String[] args) {
        BceCredentials credentials = new DefaultBceCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY);
        StsClient client = new StsClient(
                new BceClientConfiguration().withEndpoint(STS_ENDPOINT).withCredentials(credentials)
        );
        GetSessionTokenResponse response = client.getSessionToken(new GetSessionTokenRequest());
        // or simply call:
        // GetSessionTokenResponse response = client.getSessionToken();
        // or you can specify limited permissions with ACL:
        // GetSessionTokenResponse response = client.getSessionToken(new GetSessionTokenRequest().withAcl("blabla"));
        // build DefaultBceSessionCredentials object from response:
        BceCredentials csnStsCredentials = new DefaultBceSessionCredentials(
                response.getAccessKeyId(),
                response.getSecretAccessKey(),
                response.getSessionToken());
        System.out.println("==================================");
        System.out.println("GetSessionToken result:");
        System.out.println("    accessKeyId:  " + response.getAccessKeyId());
        System.out.println("    secretAccessKey:  " + response.getSecretAccessKey());
        System.out.println("    securityToken:  " + response.getSessionToken());
        System.out.println("    expiresAt:  " + response.getExpiration().toString());
        System.out.println("==================================");
        // build CSN client
        BceClientConfiguration config = new BceClientConfiguration();
        config.setCredentials(csnStsCredentials);
        CsnClient client = new CsnClient(config);
    }
}
            

Note: Currently, when configuring a client with STS, regardless of where the corresponding CSN service endpoint is located, the endpoint must be set to http://sts.bj.baidubce.com.

Configure HTTPS access to CSN

CSN supports HTTPS transport protocol. You can use HTTPS to access the CSN service in the CSN Java SDK in the following two ways:

Specify HTTPS in the endpoint:

                Java
                
            

                 String endpoint = "https://csn.baidubce.com";
 String ak = "ak";
 String sk = "sk";
 BceClientConfiguration config = new BceClientConfiguration();
 config.setCredentials(new DefaultBceCredentials(ak, sk));
 CsnClient client = new CsnClient(config);
            

Configure HTTPS by calling setProtocol:

                Java
                
            

                 String endpoint = "csn.baidubce.com"; // Endpoint without protocol
 String ak = "ak";
 String sk = "sk";
 BceClientConfiguration config = new BceClientConfiguration();
 config.setCredentials(new DefaultBceCredentials(ak, sk));
 config.setEndpoint(ENDPOINT);
 config.setProtocol(Protocol.HTTPS); // Defaults to HTTP if unspecified
 CsnClient client = new CsnClient(config);
            

Note: If the endpoint already includes a protocol, the one in endpoint takes effect, and the setProtocol() method will be ignored.

                Java
                
            

                 String endpoint = "http://csn.baidubce.com";
 String ak = "ak";
 String sk = "sk";
 BceClientConfiguration config = new BceClientConfiguration();
 config.setCredentials(new DefaultBceCredentials(ak, sk));
 config.setEndpoint(ENDPOINT);    
 config.setProtocol(Protocol.HTTPS); // Invalid operation if specified in endpoint, applicable to HTTP cases
 CsnClient client = new CsnClient(config);
            

Configure CsnClient

To customise parameters for the CsnClient, pass a BceClientConfiguration object during initialization. This allows you to set options such as proxies, maximum connections, and other network parameters.

Use a proxy

The following code snippet enables the client to access CSN service using a proxy:

                Java
                
            

                String ACCESS_KEY_ID =<your-access-key-id>;                   // User’s Access Key ID
 String SECRET_ACCESS_KEY =<your-secret-access-key>;           // User’s Secret Access Key
 String ENDPOINT = <domain-name>;                               // User-defined domain name
 // Create BceClientConfiguration instance
 BceClientConfiguration config = new BceClientConfiguration();
 // Configure proxy to local port 8080
 config.setProxyHost("127.0.0.1");
 config.setProxyPort(8080);
 // Create CSN client
 config.setCredentials(new DefaultBceCredentials(ACCESS_KEY_ID,SECRET_ACCESS_KEY));
 config.setEndpoint(ENDPOINT);
 CsnClient client = new CsnClient(config);
            

All client requests will then be routed through the proxy at 127.0.0.1:8080.

For verified proxies, configure credentials:

Plain Text

1// Create BceClientConfiguration instance
2 BceClientConfiguration config = new BceClientConfiguration();
3    
4 // Configure proxy to local port 8080
5 config.setProxyHost("127.0.0.1");
6 config.setProxyPort(8080);
7    
8 // Set username and password
9 config.setProxyUsername(<username>);                             // Username
10 config.setProxyPassword(<password>);                             // Password

Set network parameters

Users may set the basic network parameters with BceClientConfiguration:

                Java
                
                BceClientConfiguration config = new BceClientConfiguration();
    
 // Set maximum number of HTTP connections to 10
config.setMaxConnections(10);
    
 // Set TCP connection timeout to 5,000 milliseconds
config.setConnectionTimeout(5000);
    
 // Set timeout for Socket data transmission to 2,000 milliseconds
config.setSocketTimeout(2000);

Parameter description The following parameters can be configured via BceClientConfiguration:

Parameters	Description
UserAgent	User agent, refers to HTTP’s User-Agent header
Protocol	Connection protocol type
ProxyDomain	Windows domain for NTLM-verified proxy
ProxyHost	Proxy server host address
ProxyPort	Proxy server port
ProxyUsername	Proxy verification username
ProxyPassword	Proxy verification password
ProxyPreemptiveAuthenticationEnabled	Enable user agent verification or not
ProxyWorkstation	NTLM proxy workstation name
LocalAddress	Local address
ConnectionTimeoutInMillis	Timeout for establishing TCP connections (unit: ms)
SocketTimeoutInMillis	Timeout for socket data transmission (unit: ms)
MaxConnections	Maximum allowable HTTP connections
RetryPolicy	Retry policy for connections
SocketBufferSizeInBytes	Buffer size for socket operations

Exception handling

Install the SDK Package