0
# Client Configuration
1

2
The Client is the main entry point for the Google GenAI SDK. It provides access to all SDK services and can be configured to use either the Gemini Developer API or Vertex AI API.
3

4
## Core Imports
5

6
```java
7
import com.google.genai.Client;
8
import com.google.genai.types.ClientOptions;
9
import com.google.genai.types.HttpOptions;
10
import com.google.genai.types.HttpRetryOptions;
11
import com.google.auth.oauth2.GoogleCredentials;
12
```
13

14
## Client Class
15

16
```java { .api }
17
package com.google.genai;
18

19
public final class Client implements AutoCloseable {
20
  // Constructors
21
  public Client();
22

23
  // Static methods
24
  public static Builder builder();
25
  public static void setDefaultBaseUrls(
26
      Optional<String> geminiBaseUrl,
27
      Optional<String> vertexBaseUrl);
28

29
  // Instance methods
30
  public boolean vertexAI();
31
  public String project();
32
  public String location();
33
  public String apiKey();
34
  public void close();
35

36
  // Service fields
37
  public final Models models;
38
  public final Batches batches;
39
  public final Caches caches;
40
  public final Operations operations;
41
  public final Chats chats;
42
  public final Files files;
43
  public final Tunings tunings;
44
  public final FileSearchStores fileSearchStores;
45
  public final Async async;
46
}
47
```
48

49
### Service Access
50

51
The Client provides access to various services through public fields:
52

53
- `models` - Content generation, embeddings, image/video operations
54
- `batches` - Batch job management
55
- `caches` - Cached content management
56
- `operations` - Long-running operations
57
- `chats` - Chat session creation
58
- `files` - File upload/download/management
59
- `tunings` - Model tuning operations
60
- `fileSearchStores` - File search store operations
61
- `async` - Async versions of all services
62

63
### Async Service Container
64

65
```java { .api }
66
public static class Client.Async {
67
  public final AsyncModels models;
68
  public final AsyncBatches batches;
69
  public final AsyncCaches caches;
70
  public final AsyncOperations operations;
71
  public final AsyncLive live;
72
  public final AsyncChats chats;
73
  public final AsyncFiles files;
74
  public final AsyncTunings tunings;
75
  public final AsyncFileSearchStores fileSearchStores;
76
}
77
```
78

79
## Client Builder
80

81
```java { .api }
82
package com.google.genai;
83

84
public static class Client.Builder {
85
  // Build method
86
  public Client build();
87

88
  // Authentication configuration
89
  public Builder apiKey(String apiKey);
90
  public Builder project(String project);
91
  public Builder location(String location);
92
  public Builder credentials(GoogleCredentials credentials);
93

94
  // Backend selection
95
  public Builder vertexAI(boolean vertexAI);
96

97
  // HTTP and client options
98
  public Builder httpOptions(HttpOptions httpOptions);
99
  public Builder clientOptions(ClientOptions clientOptions);
100
}
101
```
102

103
## Authentication Methods
104

105
### Gemini API with API Key
106

107
```java
108
import com.google.genai.Client;
109

110
Client client = Client.builder()
111
    .apiKey("your-api-key")
112
    .build();
113
```
114

115
### Vertex AI with Project and Location
116

117
```java
118
import com.google.genai.Client;
119

120
Client client = Client.builder()
121
    .vertexAI(true)
122
    .project("your-project-id")
123
    .location("us-central1")
124
    .build();
125
```
126

127
### Vertex AI with Custom Credentials
128

129
```java
130
import com.google.genai.Client;
131
import com.google.auth.oauth2.GoogleCredentials;
132
import java.io.FileInputStream;
133

134
GoogleCredentials credentials = GoogleCredentials
135
    .fromStream(new FileInputStream("path/to/credentials.json"));
136

137
Client client = Client.builder()
138
    .vertexAI(true)
139
    .project("your-project-id")
140
    .location("us-central1")
141
    .credentials(credentials)
142
    .build();
143
```
144

145
### Vertex AI Express Mode (API Key)
146

147
```java
148
import com.google.genai.Client;
149

150
Client client = Client.builder()
151
    .apiKey("your-api-key")
152
    .vertexAI(true)
153
    .build();
154
```
155

156
### Using Environment Variables
157

158
The SDK automatically reads credentials from environment variables if no explicit configuration is provided.
159

160
**For Gemini API:**
161

162
```bash
163
export GOOGLE_API_KEY='your-api-key'
164
```
165

166
**For Vertex AI:**
167

168
```bash
169
export GOOGLE_GENAI_USE_VERTEXAI=true
170
export GOOGLE_CLOUD_PROJECT='your-project-id'
171
export GOOGLE_CLOUD_LOCATION='us-central1'
172
```
173

174
Then create client without parameters:
175

176
```java
177
import com.google.genai.Client;
178

179
Client client = new Client();
180
```
181

182
## HTTP Options
183

184
```java { .api }
185
package com.google.genai.types;
186

187
public final class HttpOptions {
188
  public static Builder builder();
189

190
  public Optional<String> baseUrl();
191
  public Optional<String> apiVersion();
192
  public Optional<Integer> timeout();
193
  public Optional<Map<String, String>> headers();
194
  public Optional<JsonNode> extraBody();
195
  public Optional<JsonNode> extraQuery();
196
  public Optional<HttpRetryOptions> retryOptions();
197
}
198
```
199

200
### API Version Configuration
201

202
Select API version (default is beta for preview features):
203

204
```java
205
import com.google.genai.Client;
206
import com.google.genai.types.HttpOptions;
207

208
// Use v1 stable API for Vertex AI
209
Client client = Client.builder()
210
    .vertexAI(true)
211
    .project("your-project")
212
    .location("us-central1")
213
    .httpOptions(HttpOptions.builder()
214
        .apiVersion("v1")
215
        .build())
216
    .build();
217

218
// Use v1alpha for Gemini API
219
Client client2 = Client.builder()
220
    .apiKey("your-api-key")
221
    .httpOptions(HttpOptions.builder()
222
        .apiVersion("v1alpha")
223
        .build())
224
    .build();
225
```
226

227
### Custom Base URL
228

229
```java
230
import com.google.genai.types.HttpOptions;
231

232
HttpOptions httpOptions = HttpOptions.builder()
233
    .baseUrl("https://your-custom-endpoint.com")
234
    .build();
235

236
Client client = Client.builder()
237
    .apiKey("your-api-key")
238
    .httpOptions(httpOptions)
239
    .build();
240
```
241

242
### Custom Headers and Timeout
243

244
```java
245
import com.google.common.collect.ImmutableMap;
246
import com.google.genai.types.HttpOptions;
247

248
HttpOptions httpOptions = HttpOptions.builder()
249
    .headers(ImmutableMap.of(
250
        "X-Custom-Header", "value",
251
        "User-Agent", "MyApp/1.0"
252
    ))
253
    .timeout(60000) // 60 seconds in milliseconds
254
    .build();
255

256
Client client = Client.builder()
257
    .apiKey("your-api-key")
258
    .httpOptions(httpOptions)
259
    .build();
260
```
261

262
### Per-Request HTTP Options
263

264
HTTP options can be set at the client level or overridden per request:
265

266
```java
267
import com.google.genai.types.HttpOptions;
268
import com.google.genai.types.GenerateContentConfig;
269

270
// Client-level timeout
271
Client client = Client.builder()
272
    .apiKey("your-api-key")
273
    .httpOptions(HttpOptions.builder()
274
        .timeout(30000)
275
        .build())
276
    .build();
277

278
// Override timeout for specific request
279
GenerateContentConfig config = GenerateContentConfig.builder()
280
    .httpOptions(HttpOptions.builder()
281
        .timeout(60000) // 60 seconds for this request
282
        .build())
283
    .build();
284

285
GenerateContentResponse response = client.models.generateContent(
286
    "gemini-2.0-flash",
287
    "Long prompt that needs more time...",
288
    config
289
);
290
```
291

292
## HTTP Retry Options
293

294
```java { .api }
295
package com.google.genai.types;
296

297
public final class HttpRetryOptions {
298
  public static Builder builder();
299

300
  public Optional<Integer> attempts();
301
  public Optional<List<Integer>> httpStatusCodes();
302
  public Optional<Long> initialDelayMs();
303
  public Optional<Long> maxDelayMs();
304
  public Optional<Double> backoffMultiplier();
305
}
306
```
307

308
### Retry Configuration
309

310
```java
311
import com.google.genai.types.HttpOptions;
312
import com.google.genai.types.HttpRetryOptions;
313
import com.google.common.collect.ImmutableList;
314

315
HttpOptions httpOptions = HttpOptions.builder()
316
    .retryOptions(HttpRetryOptions.builder()
317
        .attempts(3) // Maximum 3 attempts (1 initial + 2 retries)
318
        .httpStatusCodes(408, 429, 500, 502, 503, 504) // Retry on these codes
319
        .initialDelayMs(1000L) // Start with 1 second delay
320
        .maxDelayMs(30000L) // Maximum 30 seconds delay
321
        .backoffMultiplier(2.0) // Double delay each retry
322
        .build())
323
    .build();
324

325
Client client = Client.builder()
326
    .apiKey("your-api-key")
327
    .httpOptions(httpOptions)
328
    .build();
329
```
330

331
### Per-Request Retry Override
332

333
```java
334
import com.google.genai.types.GenerateContentConfig;
335
import com.google.genai.types.HttpOptions;
336
import com.google.genai.types.HttpRetryOptions;
337

338
// Override retry settings for specific request
339
GenerateContentConfig config = GenerateContentConfig.builder()
340
    .httpOptions(HttpOptions.builder()
341
        .retryOptions(HttpRetryOptions.builder()
342
            .attempts(5)
343
            .httpStatusCodes(429) // Only retry rate limits
344
            .build())
345
        .build())
346
    .build();
347

348
GenerateContentResponse response = client.models.generateContent(
349
    "gemini-2.0-flash",
350
    "Prompt text",
351
    config
352
);
353
```
354

355
## Client Options
356

357
```java { .api }
358
package com.google.genai.types;
359

360
public final class ClientOptions {
361
  public static Builder builder();
362

363
  public Optional<Integer> maxConnections();
364
  public Optional<Integer> maxConnectionsPerHost();
365
  public Optional<Integer> maxRetries();
366
  public Optional<Long> retryDelayMs();
367
}
368
```
369

370
### Connection Pool Configuration
371

372
```java
373
import com.google.genai.Client;
374
import com.google.genai.types.ClientOptions;
375

376
Client client = Client.builder()
377
    .apiKey("your-api-key")
378
    .clientOptions(ClientOptions.builder()
379
        .maxConnections(64) // Total connection pool size
380
        .maxConnectionsPerHost(16) // Connections per host
381
        .build())
382
    .build();
383
```
384

385
### Legacy Retry Configuration
386

387
ClientOptions also supports legacy retry configuration (prefer HttpRetryOptions instead):
388

389
```java
390
import com.google.genai.types.ClientOptions;
391

392
ClientOptions options = ClientOptions.builder()
393
    .maxRetries(3)
394
    .retryDelayMs(1000L)
395
    .build();
396

397
Client client = Client.builder()
398
    .apiKey("your-api-key")
399
    .clientOptions(options)
400
    .build();
401
```
402

403
## Resource Management
404

405
### Try-With-Resources
406

407
The Client implements `AutoCloseable` and should be closed after use:
408

409
```java
410
try (Client client = Client.builder().apiKey("key").build()) {
411
    // Use client
412
    GenerateContentResponse response = client.models.generateContent(
413
        "gemini-2.0-flash",
414
        "Hello",
415
        null
416
    );
417
} // Client automatically closed
418
```
419

420
### Manual Closing
421

422
```java
423
Client client = Client.builder().apiKey("key").build();
424
try {
425
    // Use client
426
    GenerateContentResponse response = client.models.generateContent(
427
        "gemini-2.0-flash",
428
        "Hello",
429
        null
430
    );
431
} finally {
432
    client.close();
433
}
434
```
435

436
## Thread Safety
437

438
The Client class is thread-safe and can be shared across multiple threads. Services accessed through the client are also thread-safe.
439

440
```java
441
import java.util.concurrent.ExecutorService;
442
import java.util.concurrent.Executors;
443

444
Client client = Client.builder().apiKey("key").build();
445
ExecutorService executor = Executors.newFixedThreadPool(10);
446

447
// Safe to use client from multiple threads
448
for (int i = 0; i < 100; i++) {
449
    final int index = i;
450
    executor.submit(() -> {
451
        GenerateContentResponse response = client.models.generateContent(
452
            "gemini-2.0-flash",
453
            "Request " + index,
454
            null
455
        );
456
        System.out.println(response.text());
457
    });
458
}
459

460
executor.shutdown();
461
client.close();
462
```
463

464
## Default Base URL Override
465

466
Override default base URLs globally for all clients:
467

468
```java
469
import com.google.genai.Client;
470
import java.util.Optional;
471

472
// Set custom base URLs globally
473
Client.setDefaultBaseUrls(
474
    Optional.of("https://custom-gemini-api.com"),
475
    Optional.of("https://custom-vertex-api.com")
476
);
477

478
// All clients created after this will use custom URLs
479
Client client = Client.builder().apiKey("key").build();
480
```
481

482
## Configuration Examples
483

484
### Production Configuration
485

486
```java
487
import com.google.genai.Client;
488
import com.google.genai.types.ClientOptions;
489
import com.google.genai.types.HttpOptions;
490
import com.google.genai.types.HttpRetryOptions;
491
import com.google.common.collect.ImmutableMap;
492

493
Client client = Client.builder()
494
    .apiKey(System.getenv("GOOGLE_API_KEY"))
495
    .httpOptions(HttpOptions.builder()
496
        .timeout(60000) // 60 second timeout
497
        .headers(ImmutableMap.of("User-Agent", "MyApp/1.0"))
498
        .retryOptions(HttpRetryOptions.builder()
499
            .attempts(3)
500
            .httpStatusCodes(408, 429, 500, 502, 503, 504)
501
            .initialDelayMs(1000L)
502
            .maxDelayMs(30000L)
503
            .backoffMultiplier(2.0)
504
            .build())
505
        .build())
506
    .clientOptions(ClientOptions.builder()
507
        .maxConnections(64)
508
        .maxConnectionsPerHost(16)
509
        .build())
510
    .build();
511
```
512

513
### Development Configuration
514

515
```java
516
import com.google.genai.Client;
517
import com.google.genai.types.HttpOptions;
518

519
Client client = Client.builder()
520
    .apiKey("dev-api-key")
521
    .httpOptions(HttpOptions.builder()
522
        .timeout(120000) // Longer timeout for debugging
523
        .apiVersion("v1beta") // Use beta API
524
        .build())
525
    .build();
526
```
527

528
### Multi-Region Vertex AI
529

530
```java
531
import com.google.genai.Client;
532

533
// US region client
534
Client usClient = Client.builder()
535
    .vertexAI(true)
536
    .project("my-project")
537
    .location("us-central1")
538
    .build();
539

540
// Europe region client
541
Client euClient = Client.builder()
542
    .vertexAI(true)
543
    .project("my-project")
544
    .location("europe-west1")
545
    .build();
546

547
// Use different clients based on requirements
548
GenerateContentResponse usResponse = usClient.models.generateContent(
549
    "gemini-2.0-flash", "US request", null);
550
GenerateContentResponse euResponse = euClient.models.generateContent(
551
    "gemini-2.0-flash", "EU request", null);
552

553
usClient.close();
554
euClient.close();
555
```
556