Google Gen AI Java SDK

The SDK supports Automatic Function Calling. When you provide a list of methods in the tools list of GenerateContentConfig, the SDK can automatically execute these methods on the client side.

Requirement: You must enable the -parameters compiler argument in your pom.xml so the compiler preserves parameter names, which the SDK uses for reflection.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.14.0</version>
  <configuration>
    <compilerArgs>
      <arg>-parameters</arg>
    </compilerArgs>
  </configuration>
</plugin>

Usage:

1. Define a public static method.
2. Extract the java.lang.reflect.Method object.
3. Pass it to Tool.builder().functions(method).

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.Tool;
import java.lang.reflect.Method;

public static String getCurrentWeather(String location, String unit) {
    return "The weather in " + location + " is very nice.";
}

// In main:
Method method = GenerateContentWithFunctionCall.class.getMethod("getCurrentWeather", String.class, String.class);
GenerateContentConfig config = GenerateContentConfig.builder()
    .tools(Tool.builder().functions(method))
    .build();

client.models.generateContent("gemini-2.5-flash", "What is the weather in Vancouver?", config);

The Client class is the primary entry point for interacting with the Gemini API and the Gemini Enterprise Agent Platform API. You can instantiate it using a builder pattern or by relying on environment variables.

Gemini Developer API

Use an API key to access the Gemini Developer backend:

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

Gemini Enterprise Agent Platform API

To use the Enterprise backend, you must set the enterprise(true) flag. You can authenticate using project/location details or an API key (Express Mode).

Using Project and Location:

Client client = Client.builder()
  .project("your-project")
  .location("your-location")
  .enterprise(true)
  .build();

Using API Key (Express Mode):

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

Using Environment Variables

You can instantiate a client using new Client() if the following environment variables are set:

For Gemini Developer API:

• GOOGLE_API_KEY: Recommended. (GEMINI_API_KEY is legacy and takes lower precedence).

For Gemini Enterprise Agent Platform:

• GOOGLE_GENAI_USE_ENTERPRISE=true
• GOOGLE_CLOUD_PROJECT: Your project ID.
• GOOGLE_CLOUD_LOCATION: Your location (e.g., us-central1).
• GOOGLE_API_KEY: For Express Mode.

import com.google.genai.Client;

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

// Gemini Enterprise Agent Platform
Client client = Client.builder()
  .project("your-project")
  .location("your-location")
  .enterprise(true)
  .build();

The ChatBase class manages the state of a conversation through two distinct history lists: comprehensiveHistory and curatedHistory.

History Types

1. Comprehensive History: A complete log of all interactions. It is used to ensure no data is lost, even if a model response is flagged or fails validation.
2. Curated History: A cleaned version of the conversation used to construct subsequent requests to the model. It only includes messages that follow the required protocol (e.g., alternating 'user' and 'model' roles) and contain valid content.

Validation Rules

To maintain a valid conversation state, the SDK enforces several rules during history recording:

• Role Alternation: The first message in a history must have the role user. Subsequent messages must alternate between user and model.
• Content Integrity: Every Content object must contain non-empty Part objects.
• Finish Reason: If a model response's finishReason() indicates an unexpected termination, the message is added to the comprehensiveHistory but is excluded from the curatedHistory to prevent sending invalid context back to the model in future turns.

ClientOptions allows for low-level customization of the underlying HTTP client.

Connection Pool

Configure maxConnections (total) and maxConnectionsPerHost (per host).

Proxy Configuration

Use ProxyOptions to configure HTTP, SOCKS, or DIRECT connections. DIRECT bypasses system-level proxy settings.

Custom OkHttpClient

For advanced control (interceptors, custom SSL, etc.), you can provide your own OkHttpClient instance. The SDK will clone it to preserve your settings while appending its internal RetryInterceptor.

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

// Proxy Example
ClientOptions clientOptions = ClientOptions.builder()
    .proxyOptions(
        ProxyOptions.builder()
            .type(ProxyType.Known.HTTP)
            .host("your-proxy-host")
            .port(8080)
            .username("your-proxy-username")
            .password("your-proxy-password"))
    .build();
Client client = Client.builder().apiKey("your-api-key").clientOptions(clientOptions).build();

The Client provides access to two distinct interaction patterns:

1. Synchronous API: Accessed directly via properties on the Client instance (e.g., client.models, client.chats, client.files). Use these for standard blocking calls.
2. Asynchronous API: Accessed via the client.async property. This provides asynchronous versions of the same services (e.g., client.async.models, client.async.chats). Use these for non-blocking operations.

Available Service Groups (both Sync and Async):

• models: Model management and interaction.
• batches: Batch processing.
• caches: Context caching.
• operations: Long-running operations.
• chats: Chat sessions.
• files: File management.
• tunings: Model tuning.
• authTokens: Authentication tokens.
• fileSearchStores: File search storage.
• live: Live streaming capabilities (Async only).
• elements: (Note: Async includes AsyncLive, while Client includes Live via Async mapping).

// Synchronous usage
client.models.generateContent(...);

// Asynchronous usage
client.async.models.generateContent(...);

The Client class is the primary entrypoint for interacting with Gemini APIs. It is thread-safe and implements AutoCloseable, so it should be used within a try-with-resources block to ensure the underlying HTTP client is closed properly.

You can initialize a client in two ways:

1. Default Constructor: Uses environment variables for configuration (e.g., apiKey, project, location).
2. Builder Pattern: Provides explicit control over authentication and API selection (Gemini API vs. Vertex AI).

Important Constraints:

• Gemini API: Requires an apiKey. It does not support project or location settings.
• Vertex AI: Requires project, location, and GoogleCredentials. It does not support apiKey.
• Setting both apiKey and project/location will throw an IllegalArgumentException.

// Using the Builder for Gemini API
try (Client client = Client.builder()
        .apiKey("YOUR_API_KEY")
        .build()) {
    // Use client here
}

// Using the Builder for Vertex AI
try (Client client = Client.builder()
        .project("your-project-id")
        .location("us-central1")
        .credentials(googleCredentials)
        .vertexAI(true)
        .build()) {
    // Use client here
}

The Files API allows you to upload and manage media files (text, images, audio) for use with Gemini models. Note: This feature is exclusively supported by the Gemini API.

• Capacity: Up to 20 GB per project; max 2 GB per file.
• Retention: Files are stored for 48 hours and then automatically deleted.
• Usage: Always use the Files API for requests where the total size (including prompt and instructions) exceeds 20 MB.

Operations:

• upload: Upload a media file.
• get: Retrieve file metadata.
• list: List uploaded files.
• delete: Manually delete a file.

import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;

Client client = new Client();
File file = client.files.upload("path/to/file.pdf", UploadFileConfig.builder().mimeType("application/pdf").build());

// Use the file in a prompt
Content content = Content.fromParts(
    Part.fromText("Summary this pdf."),
    Part.fromUri(file.name().get(), file.mimeType().get()));
client.models.generateContent("gemini-2.5-flash", content, null);