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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

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());
    }
}

docs

batch-operations.md

caching.md

chat-sessions.md

client-configuration.md

content-generation.md

embeddings-tokens.md

error-handling.md

file-search-stores.md

files-management.md

image-operations.md

index.md

live-sessions.md

model-tuning.md

operations.md

tools-functions.md

types-reference.md

video-generation.md

tile.json