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

client-configuration.mddocs/

Client Configuration

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.

Core Imports

import com.google.genai.Client;
import com.google.genai.types.ClientOptions;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;
import com.google.auth.oauth2.GoogleCredentials;

Client Class

package com.google.genai;

public final class Client implements AutoCloseable {
  // Constructors
  public Client();

  // Static methods
  public static Builder builder();
  public static void setDefaultBaseUrls(
      Optional<String> geminiBaseUrl,
      Optional<String> vertexBaseUrl);

  // Instance methods
  public boolean vertexAI();
  public String project();
  public String location();
  public String apiKey();
  public void close();

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

Service Access

The Client provides access to various services through public fields:

  • models - Content generation, embeddings, image/video operations
  • batches - Batch job management
  • caches - Cached content management
  • operations - Long-running operations
  • chats - Chat session creation
  • files - File upload/download/management
  • tunings - Model tuning operations
  • fileSearchStores - File search store operations
  • async - Async versions of all services

Async Service Container

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

Client Builder

package com.google.genai;

public static class Client.Builder {
  // Build method
  public Client build();

  // Authentication configuration
  public Builder apiKey(String apiKey);
  public Builder project(String project);
  public Builder location(String location);
  public Builder credentials(GoogleCredentials credentials);

  // Backend selection
  public Builder vertexAI(boolean vertexAI);

  // HTTP and client options
  public Builder httpOptions(HttpOptions httpOptions);
  public Builder clientOptions(ClientOptions clientOptions);
}

Authentication Methods

Gemini API with API Key

import com.google.genai.Client;

Client client = Client.builder()
    .apiKey("your-api-key")
    .build();

Vertex AI with Project and Location

import com.google.genai.Client;

Client client = Client.builder()
    .vertexAI(true)
    .project("your-project-id")
    .location("us-central1")
    .build();

Vertex AI with Custom Credentials

import com.google.genai.Client;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.FileInputStream;

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

Client client = Client.builder()
    .vertexAI(true)
    .project("your-project-id")
    .location("us-central1")
    .credentials(credentials)
    .build();

Vertex AI Express Mode (API Key)

import com.google.genai.Client;

Client client = Client.builder()
    .apiKey("your-api-key")
    .vertexAI(true)
    .build();

Using Environment Variables

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

For Gemini API:

export GOOGLE_API_KEY='your-api-key'

For Vertex AI:

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'

Then create client without parameters:

import com.google.genai.Client;

Client client = new Client();

HTTP Options

package com.google.genai.types;

public final class HttpOptions {
  public static Builder builder();

  public Optional<String> baseUrl();
  public Optional<String> apiVersion();
  public Optional<Integer> timeout();
  public Optional<Map<String, String>> headers();
  public Optional<JsonNode> extraBody();
  public Optional<JsonNode> extraQuery();
  public Optional<HttpRetryOptions> retryOptions();
}

API Version Configuration

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

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

// Use v1 stable API for Vertex AI
Client client = Client.builder()
    .vertexAI(true)
    .project("your-project")
    .location("us-central1")
    .httpOptions(HttpOptions.builder()
        .apiVersion("v1")
        .build())
    .build();

// Use v1alpha for Gemini API
Client client2 = Client.builder()
    .apiKey("your-api-key")
    .httpOptions(HttpOptions.builder()
        .apiVersion("v1alpha")
        .build())
    .build();

Custom Base URL

import com.google.genai.types.HttpOptions;

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

Client client = Client.builder()
    .apiKey("your-api-key")
    .httpOptions(httpOptions)
    .build();

Custom Headers and Timeout

import com.google.common.collect.ImmutableMap;
import com.google.genai.types.HttpOptions;

HttpOptions httpOptions = HttpOptions.builder()
    .headers(ImmutableMap.of(
        "X-Custom-Header", "value",
        "User-Agent", "MyApp/1.0"
    ))
    .timeout(60000) // 60 seconds in milliseconds
    .build();

Client client = Client.builder()
    .apiKey("your-api-key")
    .httpOptions(httpOptions)
    .build();

Per-Request HTTP Options

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

import com.google.genai.types.HttpOptions;
import com.google.genai.types.GenerateContentConfig;

// Client-level timeout
Client client = Client.builder()
    .apiKey("your-api-key")
    .httpOptions(HttpOptions.builder()
        .timeout(30000)
        .build())
    .build();

// Override timeout for specific request
GenerateContentConfig config = GenerateContentConfig.builder()
    .httpOptions(HttpOptions.builder()
        .timeout(60000) // 60 seconds for this request
        .build())
    .build();

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    "Long prompt that needs more time...",
    config
);

HTTP Retry Options

package com.google.genai.types;

public final class HttpRetryOptions {
  public static Builder builder();

  public Optional<Integer> attempts();
  public Optional<List<Integer>> httpStatusCodes();
  public Optional<Long> initialDelayMs();
  public Optional<Long> maxDelayMs();
  public Optional<Double> backoffMultiplier();
}

Retry Configuration

import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;
import com.google.common.collect.ImmutableList;

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

Client client = Client.builder()
    .apiKey("your-api-key")
    .httpOptions(httpOptions)
    .build();

Per-Request Retry Override

import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

// Override retry settings for specific request
GenerateContentConfig config = GenerateContentConfig.builder()
    .httpOptions(HttpOptions.builder()
        .retryOptions(HttpRetryOptions.builder()
            .attempts(5)
            .httpStatusCodes(429) // Only retry rate limits
            .build())
        .build())
    .build();

GenerateContentResponse response = client.models.generateContent(
    "gemini-2.0-flash",
    "Prompt text",
    config
);

Client Options

package com.google.genai.types;

public final class ClientOptions {
  public static Builder builder();

  public Optional<Integer> maxConnections();
  public Optional<Integer> maxConnectionsPerHost();
  public Optional<Integer> maxRetries();
  public Optional<Long> retryDelayMs();
}

Connection Pool Configuration

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

Client client = Client.builder()
    .apiKey("your-api-key")
    .clientOptions(ClientOptions.builder()
        .maxConnections(64) // Total connection pool size
        .maxConnectionsPerHost(16) // Connections per host
        .build())
    .build();

Legacy Retry Configuration

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

import com.google.genai.types.ClientOptions;

ClientOptions options = ClientOptions.builder()
    .maxRetries(3)
    .retryDelayMs(1000L)
    .build();

Client client = Client.builder()
    .apiKey("your-api-key")
    .clientOptions(options)
    .build();

Resource Management

Try-With-Resources

The Client implements AutoCloseable and should be closed after use:

try (Client client = Client.builder().apiKey("key").build()) {
    // Use client
    GenerateContentResponse response = client.models.generateContent(
        "gemini-2.0-flash",
        "Hello",
        null
    );
} // Client automatically closed

Manual Closing

Client client = Client.builder().apiKey("key").build();
try {
    // Use client
    GenerateContentResponse response = client.models.generateContent(
        "gemini-2.0-flash",
        "Hello",
        null
    );
} finally {
    client.close();
}

Thread Safety

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

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

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

// Safe to use client from multiple threads
for (int i = 0; i < 100; i++) {
    final int index = i;
    executor.submit(() -> {
        GenerateContentResponse response = client.models.generateContent(
            "gemini-2.0-flash",
            "Request " + index,
            null
        );
        System.out.println(response.text());
    });
}

executor.shutdown();
client.close();

Default Base URL Override

Override default base URLs globally for all clients:

import com.google.genai.Client;
import java.util.Optional;

// Set custom base URLs globally
Client.setDefaultBaseUrls(
    Optional.of("https://custom-gemini-api.com"),
    Optional.of("https://custom-vertex-api.com")
);

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

Configuration Examples

Production Configuration

import com.google.genai.Client;
import com.google.genai.types.ClientOptions;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;
import com.google.common.collect.ImmutableMap;

Client client = Client.builder()
    .apiKey(System.getenv("GOOGLE_API_KEY"))
    .httpOptions(HttpOptions.builder()
        .timeout(60000) // 60 second timeout
        .headers(ImmutableMap.of("User-Agent", "MyApp/1.0"))
        .retryOptions(HttpRetryOptions.builder()
            .attempts(3)
            .httpStatusCodes(408, 429, 500, 502, 503, 504)
            .initialDelayMs(1000L)
            .maxDelayMs(30000L)
            .backoffMultiplier(2.0)
            .build())
        .build())
    .clientOptions(ClientOptions.builder()
        .maxConnections(64)
        .maxConnectionsPerHost(16)
        .build())
    .build();

Development Configuration

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

Client client = Client.builder()
    .apiKey("dev-api-key")
    .httpOptions(HttpOptions.builder()
        .timeout(120000) // Longer timeout for debugging
        .apiVersion("v1beta") // Use beta API
        .build())
    .build();

Multi-Region Vertex AI

import com.google.genai.Client;

// US region client
Client usClient = Client.builder()
    .vertexAI(true)
    .project("my-project")
    .location("us-central1")
    .build();

// Europe region client
Client euClient = Client.builder()
    .vertexAI(true)
    .project("my-project")
    .location("europe-west1")
    .build();

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

usClient.close();
euClient.close();

Install with Tessl CLI

npx tessl i tessl/maven-com-google-genai--google-genai

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