CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-google-genai--google-genai

Java idiomatic SDK for the Gemini Developer APIs and Vertex AI APIs

Overview
Eval results
Files

Google GenAI Java SDK

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.

Package Information

  • Package Name: google-genai
  • Package Type: maven
  • Group ID: com.google.genai
  • Artifact ID: google-genai
  • Version: 1.28.0
  • Language: Java (Java 8+)
  • Installation:
<dependencies>
  <dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.28.0</version>
  </dependency>
</dependencies>

Core Imports

// Core client
import com.google.genai.Client;

// Main service classes
import com.google.genai.Models;
import com.google.genai.Chat;
import com.google.genai.Files;
import com.google.genai.Batches;
import com.google.genai.Caches;
import com.google.genai.Operations;
import com.google.genai.Tunings;

// Response types
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.GenerateImagesResponse;
import com.google.genai.types.CountTokensResponse;

// Content and configuration types
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import com.google.genai.types.GenerateContentConfig;

// Streaming and pagination
import com.google.genai.ResponseStream;
import com.google.genai.Pager;

// Error handling
import com.google.genai.errors.ApiException;
import com.google.genai.errors.ClientException;
import com.google.genai.errors.ServerException;
import com.google.genai.errors.GenAiIOException;

// Async operations
import java.util.concurrent.CompletableFuture;

Basic Usage

Using Gemini API

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

// Create client with API key
Client client = Client.builder()
    .apiKey("your-api-key")
    .build();

// Generate content
GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    "Tell me a story",
    null
);

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

// Close when done
client.close();

Using Vertex AI

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

// Create client for Vertex AI
Client client = Client.builder()
    .vertexAI(true)
    .project("your-project")
    .location("us-central1")
    .build();

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

System.out.println(response.text());
client.close();

Capabilities

Client Configuration and Authentication

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

class Client implements AutoCloseable {
  static Builder builder();
  void close();

  // Service access
  final Models models;
  final Batches batches;
  final Caches caches;
  final Operations operations;
  final Chats chats;
  final Files files;
  final Tunings tunings;
  final FileSearchStores fileSearchStores;
  final Async async;

  class Async {
    final AsyncModels models;
    final AsyncBatches batches;
    final AsyncCaches caches;
    final AsyncOperations operations;
    final AsyncChats chats;
    final AsyncFiles files;
    final AsyncTunings tunings;
    final AsyncFileSearchStores fileSearchStores;
    final AsyncLive live;
  }
}

class Client.Builder {
  Builder apiKey(String apiKey);
  Builder project(String project);
  Builder location(String location);
  Builder vertexAI(boolean vertexAI);
  Builder credentials(GoogleCredentials credentials);
  Builder httpOptions(HttpOptions httpOptions);
  Builder clientOptions(ClientOptions clientOptions);
  Client build();
}

Client Configuration

Content Generation

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

class Models {
  // Sync generation
  GenerateContentResponse generateContent(
      String model,
      String text,
      GenerateContentConfig config);

  GenerateContentResponse generateContent(
      String model,
      Content content,
      GenerateContentConfig config);

  GenerateContentResponse generateContent(
      String model,
      List<Content> contents,
      GenerateContentConfig config);

  // Streaming generation
  ResponseStream<GenerateContentResponse> generateContentStream(
      String model,
      String text,
      GenerateContentConfig config);

  ResponseStream<GenerateContentResponse> generateContentStream(
      String model,
      Content content,
      GenerateContentConfig config);

  ResponseStream<GenerateContentResponse> generateContentStream(
      String model,
      List<Content> contents,
      GenerateContentConfig config);
}

class AsyncModels {
  // Async generation
  CompletableFuture<GenerateContentResponse> generateContent(
      String model,
      String text,
      GenerateContentConfig config);

  CompletableFuture<ResponseStream<GenerateContentResponse>> generateContentStream(
      String model,
      String text,
      GenerateContentConfig config);
}

Content Generation

Embeddings and Token Operations

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

class Models {
  // Embeddings
  EmbedContentResponse embedContent(
      String model,
      String text,
      EmbedContentConfig config);

  EmbedContentResponse embedContent(
      String model,
      List<String> texts,
      EmbedContentConfig config);

  // Token operations
  CountTokensResponse countTokens(
      String model,
      String text,
      CountTokensConfig config);

  CountTokensResponse countTokens(
      String model,
      List<Content> contents,
      CountTokensConfig config);

  ComputeTokensResponse computeTokens(
      String model,
      String text,
      ComputeTokensConfig config);

  ComputeTokensResponse computeTokens(
      String model,
      List<Content> contents,
      ComputeTokensConfig config);
}

Embeddings and Token Operations

File Management

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

class Files {
  // Upload
  File upload(java.io.File file, UploadFileConfig config);
  File upload(byte[] bytes, UploadFileConfig config);
  File upload(InputStream inputStream, long size, UploadFileConfig config);
  File upload(String filePath, UploadFileConfig config);

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

  // Download
  void download(String fileName, String downloadPath, DownloadFileConfig config);
  void download(File file, String downloadPath, DownloadFileConfig config);

  // Delete
  DeleteFileResponse delete(String name, DeleteFileConfig config);
}

File Management

Batch Operations

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

class Batches {
  // Create batch jobs
  BatchJob create(
      String model,
      BatchJobSource src,
      CreateBatchJobConfig config);

  BatchJob createEmbeddings(
      String model,
      EmbeddingsBatchJobSource src,
      CreateEmbeddingsBatchJobConfig config);

  // Manage batch jobs
  BatchJob get(String name, GetBatchJobConfig config);
  void cancel(String name, CancelBatchJobConfig config);
  DeleteResourceJob delete(String name, DeleteBatchJobConfig config);
  Pager<BatchJob> list(ListBatchJobsConfig config);
}

Batch Operations

Cached Content

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

class Caches {
  CachedContent create(CreateCachedContentConfig config);
  CachedContent get(String name, GetCachedContentConfig config);
  CachedContent update(String name, UpdateCachedContentConfig config);
  DeleteCachedContentResponse delete(String name, DeleteCachedContentConfig config);
  Pager<CachedContent> list(ListCachedContentsConfig config);
}

Cached Content

Chat Sessions

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

class Chats {
  Chat create(String model, GenerateContentConfig config);
  Chat create(String model);
}

class Chat {
  // Send messages
  GenerateContentResponse sendMessage(String text);
  GenerateContentResponse sendMessage(String text, GenerateContentConfig config);
  GenerateContentResponse sendMessage(Content content);
  GenerateContentResponse sendMessage(List<Content> contents);

  // Stream messages
  ResponseStream<GenerateContentResponse> sendMessageStream(String text);
  ResponseStream<GenerateContentResponse> sendMessageStream(Content content);
}

Chat Sessions

Model Tuning

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

class Tunings {
  TuningOperation create(CreateTuningJobConfig config);
  TuningOperation get(String name, GetTuningJobConfig config);
  void cancel(String name, CancelTuningJobConfig config);
  Pager<TuningOperation> list(ListTuningJobsConfig config);
}

class Models {
  Model get(String model, GetModelConfig config);
  Pager<Model> list(ListModelsConfig config);
  Model update(String model, UpdateModelConfig config);
  DeleteModelResponse delete(String model, DeleteModelConfig config);
}

Model Tuning

Image Operations

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

class Models {
  // Generate images
  GenerateImagesResponse generateImages(
      String model,
      String prompt,
      GenerateImagesConfig config);

  // Edit images
  EditImageResponse editImage(
      String model,
      String prompt,
      List<ReferenceImage> referenceImages,
      EditImageConfig config);

  // Upscale images
  UpscaleImageResponse upscaleImage(
      String model,
      Image image,
      String upscaleFactor,
      UpscaleImageConfig config);

  // Recontextualize images
  RecontextImageResponse recontextImage(
      String model,
      RecontextImageSource source,
      RecontextImageConfig config);

  // Segment images
  SegmentImageResponse segmentImage(
      String model,
      SegmentImageSource source,
      SegmentImageConfig config);
}

Image Operations

Video Generation

Generate videos from text prompts or images using Veo models.

class Models {
  // Generate videos
  GenerateVideosOperation generateVideos(
      String model,
      GenerateVideosSource source,
      GenerateVideosConfig config);

  GenerateVideosOperation generateVideos(
      String model,
      String prompt,
      Image image,
      Video video,
      GenerateVideosConfig config);
}

class Operations {
  Operation get(String name, GetOperationConfig config);
  Operation wait(String name, WaitOperationConfig config);
}

Video Generation

Tools and Function Calling

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

class Tool {
  static Builder builder();

  Optional<List<FunctionDeclaration>> functionDeclarations();
  Optional<GoogleSearchRetrieval> googleSearchRetrieval();
  Optional<GoogleSearch> googleSearch();
  Optional<GoogleMaps> googleMaps();
  Optional<CodeExecution> codeExecution();
  Optional<FileSearch> fileSearch();
  Optional<ComputerUse> computerUse();
  Optional<Retrieval> retrieval();
  Optional<UrlContext> urlContext();
}

class FunctionDeclaration {
  static Builder builder();

  Optional<String> name();
  Optional<String> description();
  Optional<Schema> parameters();
}

class GenerateContentConfig {
  Optional<List<Tool>> tools();
  Optional<ToolConfig> toolConfig();
  Optional<AutomaticFunctionCallingConfig> automaticFunctionCalling();
}

Tools and Function Calling

Common Types and Data Models

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

class Content {
  static Content fromParts(Part... parts);
  static Content fromParts(List<Part> parts);
  static Builder builder();

  Optional<List<Part>> parts();
  Optional<String> role();
}

class Part {
  static Part fromText(String text);
  static Part fromImage(Image image);
  static Part fromVideo(Video video);
  static Part fromFileData(FileData fileData);
  static Part fromFunctionCall(FunctionCall functionCall);
  static Part fromFunctionResponse(FunctionResponse functionResponse);

  Optional<String> text();
  Optional<Blob> inlineData();
  Optional<FileData> fileData();
  Optional<FunctionCall> functionCall();
  Optional<FunctionResponse> functionResponse();
}

class GenerateContentConfig {
  static Builder builder();

  Optional<Content> systemInstruction();
  Optional<Double> temperature();
  Optional<Integer> maxOutputTokens();
  Optional<List<String>> stopSequences();
  Optional<List<SafetySetting>> safetySettings();
  Optional<List<Tool>> tools();
  Optional<String> responseMimeType();
  Optional<Schema> responseSchema();
}

Types Reference

Error Handling

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

class ApiException extends RuntimeException {
  ApiException(int code, String status, String message);
  int code();
  String status();
  String message();
}

class ClientException extends ApiException {
  ClientException(int code, String status, String message);
}

class ServerException extends ApiException {
  ServerException(int code, String status, String message);
}

class GenAiIOException extends RuntimeException {
  GenAiIOException(String message);
  GenAiIOException(String message, Throwable cause);
  GenAiIOException(Throwable cause);
}

Error Handling

Operations Management

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

class Operations {
  Operation get(String name, GetOperationConfig config);
  void cancel(String name, CancelOperationConfig config);
  DeleteResourceJob delete(String name, DeleteOperationConfig config);
  Pager<Operation> list(ListOperationsConfig config);
  Operation wait(String name, WaitOperationConfig config);
}

class Operation {
  Optional<String> name();
  Optional<JsonNode> metadata();
  Optional<Boolean> done();
  Optional<Status> error();
  Optional<JsonNode> response();
}

Operations Management

Live Sessions (Experimental)

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

class AsyncLive {
  CompletableFuture<AsyncSession> connect(String model, LiveConnectConfig config);
}

class AsyncSession {
  CompletableFuture<Void> sendClientContent(LiveSendClientContentParameters clientContent);
  CompletableFuture<Void> sendRealtimeInput(LiveSendRealtimeInputParameters realtimeInput);
  CompletableFuture<Void> sendToolResponse(LiveSendToolResponseParameters toolResponse);
  CompletableFuture<Void> receive(Consumer<LiveServerMessage> onMessage);
  CompletableFuture<Void> close();
  String sessionId();
}

Live Sessions

File Search Stores and Documents

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

class FileSearchStores {
  final Documents documents;

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

  UploadToFileSearchStoreOperation uploadToFileSearchStore(
      String storeName,
      java.io.File file,
      UploadToFileSearchStoreConfig config);

  ImportFileOperation importFile(
      String fileSearchStoreName,
      String fileName,
      ImportFileConfig config);
}

class Documents {
  Document get(String name, GetDocumentConfig config);
  void delete(String name, DeleteDocumentConfig config);
  Pager<Document> list(String parent, ListDocumentsConfig config);
}

File Search Stores

Design Patterns

Builder Pattern

All configuration and data types use immutable builders:

GenerateContentConfig config = GenerateContentConfig.builder()
    .temperature(0.7)
    .maxOutputTokens(1024)
    .build();

Optional Fields

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

response.text();  // Returns String directly (convenience method)
response.candidates().ifPresent(candidates -> {
    // Process candidates
});

Resource Management

Use try-with-resources for automatic cleanup:

try (Client client = Client.builder().apiKey("key").build()) {
    // Use client
} // Automatically closes

Async Operations

All async methods return CompletableFuture<T>:

CompletableFuture<GenerateContentResponse> future =
    client.async.models.generateContent("gemini-2.0-flash", "Hello", null);

future.thenAccept(response -> {
    System.out.println(response.text());
});

Pagination

Iterate through paginated results:

Pager<File> pager = client.files.list(null);
for (File file : pager) {
    System.out.println(file.name());
}

Streaming

Stream responses for real-time processing:

try (ResponseStream<GenerateContentResponse> stream =
    client.models.generateContentStream("gemini-2.0-flash", "Tell a story", null)) {
    for (GenerateContentResponse chunk : stream) {
        System.out.print(chunk.text());
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-com-google-genai--google-genai
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.google.genai/google-genai@1.28.x