0
# Google GenAI Java SDK
1

2
Java idiomatic SDK for Google's Gemini Developer APIs and Vertex AI APIs. This SDK provides a unified client that enables seamless switching between Gemini API and Vertex AI backends without code rewrites, supporting content generation, embeddings, image/video generation, file management, caching, tuning, batch operations, and more.
3

4
## Package Information
5

6
- **Package Name**: google-genai
7
- **Package Type**: maven
8
- **Group ID**: com.google.genai
9
- **Artifact ID**: google-genai
10
- **Version**: 1.28.0
11
- **Language**: Java (Java 8+)
12
- **Installation**:
13

14
```xml
15
<dependencies>
16
  <dependency>
17
    <groupId>com.google.genai</groupId>
18
    <artifactId>google-genai</artifactId>
19
    <version>1.28.0</version>
20
  </dependency>
21
</dependencies>
22
```
23

24
## Core Imports
25

26
```java { .api }
27
// Core client
28
import com.google.genai.Client;
29

30
// Main service classes
31
import com.google.genai.Models;
32
import com.google.genai.Chat;
33
import com.google.genai.Files;
34
import com.google.genai.Batches;
35
import com.google.genai.Caches;
36
import com.google.genai.Operations;
37
import com.google.genai.Tunings;
38

39
// Response types
40
import com.google.genai.types.GenerateContentResponse;
41
import com.google.genai.types.EmbedContentResponse;
42
import com.google.genai.types.GenerateImagesResponse;
43
import com.google.genai.types.CountTokensResponse;
44

45
// Content and configuration types
46
import com.google.genai.types.Content;
47
import com.google.genai.types.Part;
48
import com.google.genai.types.GenerateContentConfig;
49

50
// Streaming and pagination
51
import com.google.genai.ResponseStream;
52
import com.google.genai.Pager;
53

54
// Error handling
55
import com.google.genai.errors.ApiException;
56
import com.google.genai.errors.ClientException;
57
import com.google.genai.errors.ServerException;
58
import com.google.genai.errors.GenAiIOException;
59

60
// Async operations
61
import java.util.concurrent.CompletableFuture;
62
```
63

64
## Basic Usage
65

66
### Using Gemini API
67

68
```java
69
import com.google.genai.Client;
70
import com.google.genai.types.GenerateContentResponse;
71

72
// Create client with API key
73
Client client = Client.builder()
74
    .apiKey("your-api-key")
75
    .build();
76

77
// Generate content
78
GenerateContentResponse response = client.models.generateContent(
79
    "gemini-2.0-flash",
80
    "Tell me a story",
81
    null
82
);
83

84
System.out.println(response.text());
85

86
// Close when done
87
client.close();
88
```
89

90
### Using Vertex AI
91

92
```java
93
import com.google.genai.Client;
94
import com.google.genai.types.GenerateContentResponse;
95

96
// Create client for Vertex AI
97
Client client = Client.builder()
98
    .vertexAI(true)
99
    .project("your-project")
100
    .location("us-central1")
101
    .build();
102

103
// Generate content (same API as Gemini)
104
GenerateContentResponse response = client.models.generateContent(
105
    "gemini-2.0-flash",
106
    "Tell me a story",
107
    null
108
);
109

110
System.out.println(response.text());
111
client.close();
112
```
113

114
## Capabilities
115

116
### Client Configuration and Authentication
117

118
Configure the client for Gemini API or Vertex AI with authentication, HTTP options, retry settings, and connection pools.
119

120
```java { .api }
121
class Client implements AutoCloseable {
122
  static Builder builder();
123
  void close();
124

125
  // Service access
126
  final Models models;
127
  final Batches batches;
128
  final Caches caches;
129
  final Operations operations;
130
  final Chats chats;
131
  final Files files;
132
  final Tunings tunings;
133
  final FileSearchStores fileSearchStores;
134
  final Async async;
135

136
  class Async {
137
    final AsyncModels models;
138
    final AsyncBatches batches;
139
    final AsyncCaches caches;
140
    final AsyncOperations operations;
141
    final AsyncChats chats;
142
    final AsyncFiles files;
143
    final AsyncTunings tunings;
144
    final AsyncFileSearchStores fileSearchStores;
145
    final AsyncLive live;
146
  }
147
}
148

149
class Client.Builder {
150
  Builder apiKey(String apiKey);
151
  Builder project(String project);
152
  Builder location(String location);
153
  Builder vertexAI(boolean vertexAI);
154
  Builder credentials(GoogleCredentials credentials);
155
  Builder httpOptions(HttpOptions httpOptions);
156
  Builder clientOptions(ClientOptions clientOptions);
157
  Client build();
158
}
159
```
160

161
[Client Configuration](./client-configuration.md)
162

163
### Content Generation
164

165
Generate text content synchronously, asynchronously, or with streaming. Supports multimodal inputs (text, images, video, audio), structured outputs, system instructions, safety settings, and tool use.
166

167
```java { .api }
168
class Models {
169
  // Sync generation
170
  GenerateContentResponse generateContent(
171
      String model,
172
      String text,
173
      GenerateContentConfig config);
174

175
  GenerateContentResponse generateContent(
176
      String model,
177
      Content content,
178
      GenerateContentConfig config);
179

180
  GenerateContentResponse generateContent(
181
      String model,
182
      List<Content> contents,
183
      GenerateContentConfig config);
184

185
  // Streaming generation
186
  ResponseStream<GenerateContentResponse> generateContentStream(
187
      String model,
188
      String text,
189
      GenerateContentConfig config);
190

191
  ResponseStream<GenerateContentResponse> generateContentStream(
192
      String model,
193
      Content content,
194
      GenerateContentConfig config);
195

196
  ResponseStream<GenerateContentResponse> generateContentStream(
197
      String model,
198
      List<Content> contents,
199
      GenerateContentConfig config);
200
}
201

202
class AsyncModels {
203
  // Async generation
204
  CompletableFuture<GenerateContentResponse> generateContent(
205
      String model,
206
      String text,
207
      GenerateContentConfig config);
208

209
  CompletableFuture<ResponseStream<GenerateContentResponse>> generateContentStream(
210
      String model,
211
      String text,
212
      GenerateContentConfig config);
213
}
214
```
215

216
[Content Generation](./content-generation.md)
217

218
### Embeddings and Token Operations
219

220
Generate embeddings for text and compute or count tokens in prompts.
221

222
```java { .api }
223
class Models {
224
  // Embeddings
225
  EmbedContentResponse embedContent(
226
      String model,
227
      String text,
228
      EmbedContentConfig config);
229

230
  EmbedContentResponse embedContent(
231
      String model,
232
      List<String> texts,
233
      EmbedContentConfig config);
234

235
  // Token operations
236
  CountTokensResponse countTokens(
237
      String model,
238
      String text,
239
      CountTokensConfig config);
240

241
  CountTokensResponse countTokens(
242
      String model,
243
      List<Content> contents,
244
      CountTokensConfig config);
245

246
  ComputeTokensResponse computeTokens(
247
      String model,
248
      String text,
249
      ComputeTokensConfig config);
250

251
  ComputeTokensResponse computeTokens(
252
      String model,
253
      List<Content> contents,
254
      ComputeTokensConfig config);
255
}
256
```
257

258
[Embeddings and Token Operations](./embeddings-tokens.md)
259

260
### File Management
261

262
Upload, retrieve, list, download, and delete files for use with Gemini models. Supports various file types including images, audio, video, and documents.
263

264
```java { .api }
265
class Files {
266
  // Upload
267
  File upload(java.io.File file, UploadFileConfig config);
268
  File upload(byte[] bytes, UploadFileConfig config);
269
  File upload(InputStream inputStream, long size, UploadFileConfig config);
270
  File upload(String filePath, UploadFileConfig config);
271

272
  // Retrieve and list
273
  File get(String name, GetFileConfig config);
274
  Pager<File> list(ListFilesConfig config);
275

276
  // Download
277
  void download(String fileName, String downloadPath, DownloadFileConfig config);
278
  void download(File file, String downloadPath, DownloadFileConfig config);
279

280
  // Delete
281
  DeleteFileResponse delete(String name, DeleteFileConfig config);
282
}
283
```
284

285
[File Management](./files-management.md)
286

287
### Batch Operations
288

289
Create and manage batch jobs for processing multiple requests efficiently. Supports both content generation and embeddings batch jobs.
290

291
```java { .api }
292
class Batches {
293
  // Create batch jobs
294
  BatchJob create(
295
      String model,
296
      BatchJobSource src,
297
      CreateBatchJobConfig config);
298

299
  BatchJob createEmbeddings(
300
      String model,
301
      EmbeddingsBatchJobSource src,
302
      CreateEmbeddingsBatchJobConfig config);
303

304
  // Manage batch jobs
305
  BatchJob get(String name, GetBatchJobConfig config);
306
  void cancel(String name, CancelBatchJobConfig config);
307
  DeleteResourceJob delete(String name, DeleteBatchJobConfig config);
308
  Pager<BatchJob> list(ListBatchJobsConfig config);
309
}
310
```
311

312
[Batch Operations](./batch-operations.md)
313

314
### Cached Content
315

316
Create and manage cached content to optimize repeated requests with the same context, reducing latency and costs.
317

318
```java { .api }
319
class Caches {
320
  CachedContent create(CreateCachedContentConfig config);
321
  CachedContent get(String name, GetCachedContentConfig config);
322
  CachedContent update(String name, UpdateCachedContentConfig config);
323
  DeleteCachedContentResponse delete(String name, DeleteCachedContentConfig config);
324
  Pager<CachedContent> list(ListCachedContentsConfig config);
325
}
326
```
327

328
[Cached Content](./caching.md)
329

330
### Chat Sessions
331

332
Create and manage multi-turn chat sessions with automatic history management.
333

334
```java { .api }
335
class Chats {
336
  Chat create(String model, GenerateContentConfig config);
337
  Chat create(String model);
338
}
339

340
class Chat {
341
  // Send messages
342
  GenerateContentResponse sendMessage(String text);
343
  GenerateContentResponse sendMessage(String text, GenerateContentConfig config);
344
  GenerateContentResponse sendMessage(Content content);
345
  GenerateContentResponse sendMessage(List<Content> contents);
346

347
  // Stream messages
348
  ResponseStream<GenerateContentResponse> sendMessageStream(String text);
349
  ResponseStream<GenerateContentResponse> sendMessageStream(Content content);
350
}
351
```
352

353
[Chat Sessions](./chat-sessions.md)
354

355
### Model Tuning
356

357
Create and manage tuning jobs to fine-tune models with custom training data.
358

359
```java { .api }
360
class Tunings {
361
  TuningOperation create(CreateTuningJobConfig config);
362
  TuningOperation get(String name, GetTuningJobConfig config);
363
  void cancel(String name, CancelTuningJobConfig config);
364
  Pager<TuningOperation> list(ListTuningJobsConfig config);
365
}
366

367
class Models {
368
  Model get(String model, GetModelConfig config);
369
  Pager<Model> list(ListModelsConfig config);
370
  Model update(String model, UpdateModelConfig config);
371
  DeleteModelResponse delete(String model, DeleteModelConfig config);
372
}
373
```
374

375
[Model Tuning](./model-tuning.md)
376

377
### Image Operations
378

379
Generate, edit, upscale, recontextualize, and segment images using Imagen models.
380

381
```java { .api }
382
class Models {
383
  // Generate images
384
  GenerateImagesResponse generateImages(
385
      String model,
386
      String prompt,
387
      GenerateImagesConfig config);
388

389
  // Edit images
390
  EditImageResponse editImage(
391
      String model,
392
      String prompt,
393
      List<ReferenceImage> referenceImages,
394
      EditImageConfig config);
395

396
  // Upscale images
397
  UpscaleImageResponse upscaleImage(
398
      String model,
399
      Image image,
400
      String upscaleFactor,
401
      UpscaleImageConfig config);
402

403
  // Recontextualize images
404
  RecontextImageResponse recontextImage(
405
      String model,
406
      RecontextImageSource source,
407
      RecontextImageConfig config);
408

409
  // Segment images
410
  SegmentImageResponse segmentImage(
411
      String model,
412
      SegmentImageSource source,
413
      SegmentImageConfig config);
414
}
415
```
416

417
[Image Operations](./image-operations.md)
418

419
### Video Generation
420

421
Generate videos from text prompts or images using Veo models.
422

423
```java { .api }
424
class Models {
425
  // Generate videos
426
  GenerateVideosOperation generateVideos(
427
      String model,
428
      GenerateVideosSource source,
429
      GenerateVideosConfig config);
430

431
  GenerateVideosOperation generateVideos(
432
      String model,
433
      String prompt,
434
      Image image,
435
      Video video,
436
      GenerateVideosConfig config);
437
}
438

439
class Operations {
440
  Operation get(String name, GetOperationConfig config);
441
  Operation wait(String name, WaitOperationConfig config);
442
}
443
```
444

445
[Video Generation](./video-generation.md)
446

447
### Tools and Function Calling
448

449
Use tools like Google Search, code execution, and custom function calling with automatic or manual execution.
450

451
```java { .api }
452
class Tool {
453
  static Builder builder();
454

455
  Optional<List<FunctionDeclaration>> functionDeclarations();
456
  Optional<GoogleSearchRetrieval> googleSearchRetrieval();
457
  Optional<GoogleSearch> googleSearch();
458
  Optional<GoogleMaps> googleMaps();
459
  Optional<CodeExecution> codeExecution();
460
  Optional<FileSearch> fileSearch();
461
  Optional<ComputerUse> computerUse();
462
  Optional<Retrieval> retrieval();
463
  Optional<UrlContext> urlContext();
464
}
465

466
class FunctionDeclaration {
467
  static Builder builder();
468

469
  Optional<String> name();
470
  Optional<String> description();
471
  Optional<Schema> parameters();
472
}
473

474
class GenerateContentConfig {
475
  Optional<List<Tool>> tools();
476
  Optional<ToolConfig> toolConfig();
477
  Optional<AutomaticFunctionCallingConfig> automaticFunctionCalling();
478
}
479
```
480

481
[Tools and Function Calling](./tools-functions.md)
482

483
### Common Types and Data Models
484

485
Core types for content, parts, blobs, schemas, and configurations used throughout the SDK.
486

487
```java { .api }
488
class Content {
489
  static Content fromParts(Part... parts);
490
  static Content fromParts(List<Part> parts);
491
  static Builder builder();
492

493
  Optional<List<Part>> parts();
494
  Optional<String> role();
495
}
496

497
class Part {
498
  static Part fromText(String text);
499
  static Part fromImage(Image image);
500
  static Part fromVideo(Video video);
501
  static Part fromFileData(FileData fileData);
502
  static Part fromFunctionCall(FunctionCall functionCall);
503
  static Part fromFunctionResponse(FunctionResponse functionResponse);
504

505
  Optional<String> text();
506
  Optional<Blob> inlineData();
507
  Optional<FileData> fileData();
508
  Optional<FunctionCall> functionCall();
509
  Optional<FunctionResponse> functionResponse();
510
}
511

512
class GenerateContentConfig {
513
  static Builder builder();
514

515
  Optional<Content> systemInstruction();
516
  Optional<Double> temperature();
517
  Optional<Integer> maxOutputTokens();
518
  Optional<List<String>> stopSequences();
519
  Optional<List<SafetySetting>> safetySettings();
520
  Optional<List<Tool>> tools();
521
  Optional<String> responseMimeType();
522
  Optional<Schema> responseSchema();
523
}
524
```
525

526
[Types Reference](./types-reference.md)
527

528
### Error Handling
529

530
Exception hierarchy for handling API errors, client errors, server errors, and I/O errors.
531

532
```java { .api }
533
class ApiException extends RuntimeException {
534
  ApiException(int code, String status, String message);
535
  int code();
536
  String status();
537
  String message();
538
}
539

540
class ClientException extends ApiException {
541
  ClientException(int code, String status, String message);
542
}
543

544
class ServerException extends ApiException {
545
  ServerException(int code, String status, String message);
546
}
547

548
class GenAiIOException extends RuntimeException {
549
  GenAiIOException(String message);
550
  GenAiIOException(String message, Throwable cause);
551
  GenAiIOException(Throwable cause);
552
}
553
```
554

555
[Error Handling](./error-handling.md)
556

557
### Operations Management
558

559
Manage long-running operations like video generation and tuning jobs.
560

561
```java { .api }
562
class Operations {
563
  Operation get(String name, GetOperationConfig config);
564
  void cancel(String name, CancelOperationConfig config);
565
  DeleteResourceJob delete(String name, DeleteOperationConfig config);
566
  Pager<Operation> list(ListOperationsConfig config);
567
  Operation wait(String name, WaitOperationConfig config);
568
}
569

570
class Operation {
571
  Optional<String> name();
572
  Optional<JsonNode> metadata();
573
  Optional<Boolean> done();
574
  Optional<Status> error();
575
  Optional<JsonNode> response();
576
}
577
```
578

579
[Operations Management](./operations.md)
580

581
### Live Sessions (Experimental)
582

583
Real-time bidirectional communication with AI models using WebSocket connections for low-latency streaming interactions.
584

585
```java { .api }
586
class AsyncLive {
587
  CompletableFuture<AsyncSession> connect(String model, LiveConnectConfig config);
588
}
589

590
class AsyncSession {
591
  CompletableFuture<Void> sendClientContent(LiveSendClientContentParameters clientContent);
592
  CompletableFuture<Void> sendRealtimeInput(LiveSendRealtimeInputParameters realtimeInput);
593
  CompletableFuture<Void> sendToolResponse(LiveSendToolResponseParameters toolResponse);
594
  CompletableFuture<Void> receive(Consumer<LiveServerMessage> onMessage);
595
  CompletableFuture<Void> close();
596
  String sessionId();
597
}
598
```
599

600
[Live Sessions](./live-sessions.md)
601

602
### File Search Stores and Documents
603

604
Create and manage file search stores for Retrieval-Augmented Generation (RAG). Upload documents and perform semantic search.
605

606
```java { .api }
607
class FileSearchStores {
608
  final Documents documents;
609

610
  FileSearchStore create(CreateFileSearchStoreConfig config);
611
  FileSearchStore get(String name, GetFileSearchStoreConfig config);
612
  void delete(String name, DeleteFileSearchStoreConfig config);
613
  Pager<FileSearchStore> list(ListFileSearchStoresConfig config);
614

615
  UploadToFileSearchStoreOperation uploadToFileSearchStore(
616
      String storeName,
617
      java.io.File file,
618
      UploadToFileSearchStoreConfig config);
619

620
  ImportFileOperation importFile(
621
      String fileSearchStoreName,
622
      String fileName,
623
      ImportFileConfig config);
624
}
625

626
class Documents {
627
  Document get(String name, GetDocumentConfig config);
628
  void delete(String name, DeleteDocumentConfig config);
629
  Pager<Document> list(String parent, ListDocumentsConfig config);
630
}
631
```
632

633
[File Search Stores](./file-search-stores.md)
634

635
## Design Patterns
636

637
### Builder Pattern
638

639
All configuration and data types use immutable builders:
640

641
```java
642
GenerateContentConfig config = GenerateContentConfig.builder()
643
    .temperature(0.7)
644
    .maxOutputTokens(1024)
645
    .build();
646
```
647

648
### Optional Fields
649

650
Most fields use Java's `Optional<T>` for null safety:
651

652
```java
653
response.text();  // Returns String directly (convenience method)
654
response.candidates().ifPresent(candidates -> {
655
    // Process candidates
656
});
657
```
658

659
### Resource Management
660

661
Use try-with-resources for automatic cleanup:
662

663
```java
664
try (Client client = Client.builder().apiKey("key").build()) {
665
    // Use client
666
} // Automatically closes
667
```
668

669
### Async Operations
670

671
All async methods return `CompletableFuture<T>`:
672

673
```java
674
CompletableFuture<GenerateContentResponse> future =
675
    client.async.models.generateContent("gemini-2.0-flash", "Hello", null);
676

677
future.thenAccept(response -> {
678
    System.out.println(response.text());
679
});
680
```
681

682
### Pagination
683

684
Iterate through paginated results:
685

686
```java
687
Pager<File> pager = client.files.list(null);
688
for (File file : pager) {
689
    System.out.println(file.name());
690
}
691
```
692

693
### Streaming
694

695
Stream responses for real-time processing:
696

697
```java
698
try (ResponseStream<GenerateContentResponse> stream =
699
    client.models.generateContentStream("gemini-2.0-flash", "Tell a story", null)) {
700
    for (GenerateContentResponse chunk : stream) {
701
        System.out.print(chunk.text());
702
    }
703
}
704
```
705