Google Gen AI Java SDK

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

Add dependency

If you're using Maven, add the following to your dependencies: //: # ({x-version-update-start:google-genai:released})

<dependencies>
  <dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.10.0</version>
  </dependency>
</dependencies>

Getting Started

Follow the instructions in this section to get started using the Google Gen AI SDK for Java.

Create a client

The Google Gen AI Java SDK provides a Client class, simplifying interaction with both the Gemini API and Vertex AI API. With minimal configuration, you can seamlessly switch between the 2 backends without rewriting your code.

Instantiate a client that uses Gemini API

import com.google.genai.Client;

// Use Builder class for instantiation. Explicitly set the API key to use Gemini
// Developer backend.
Client client = Client.builder().apiKey("your-api-key").build();

Instantiate a client that uses Vertex AI API

Using project and location

import com.google.genai.Client;

// Use Builder class for instantiation. Explicitly set the project and location,
// and set `vertexAI(true)` to use Vertex AI backend.
Client client = Client.builder()
  .project("your-project")
  .location("your-location")
  .vertexAI(true)
  .build();

Using API key on Vertex AI (GCP Express Mode)

import com.google.genai.Client;

// Explicitly set the `apiKey` and `vertexAI(true)` to use Vertex AI backend
// in express mode.
Client client = Client.builder()
  .apiKey("your-api-key")
  .vertexAI(true)
  .build();

(Optional) Using environment variables:

You can create a client by configuring the necessary environment variables. Configuration setup instructions depends on whether you're using the Gemini Developer API or the Gemini API in Vertex AI.

Gemini Developer API: Set the GOOGLE_API_KEY. It will automatically be picked up by the client. Note that GEMINI_API_KEY is a legacy environment variable, it's recommended to use GOOGLE_API_KEY only. But if both are set, GOOGLE_API_KEY takes precedence.

export GOOGLE_API_KEY='your-api-key'

Gemini API on Vertex AI: Set GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, or GOOGLE_API_KEY for Vertex AI express mode. It's recommended that you set only project & location, or API key. But if both are set, project & location takes precedence.

export GOOGLE_GENAI_USE_VERTEXAI=true

// Set project and location for Vertex AI authentication
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'
// or API key for express mode
export GOOGLE_API_KEY='your-api-key'

After configuring the environment variables, you can instantiate a client without passing any variables.

import com.google.genai.Client;

Client client = new Client();

API Selection

By default, the SDK uses the beta API endpoints provided by Google to support preview features in the APIs. The stable API endpoints can be selected by setting the API version to v1.

To set the API version use HttpOptions. For example, to set the API version to v1 for Vertex AI:

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

Client client = Client.builder()
  .project("your-project")
  .location("your-location")
  .vertexAI(true)
  .httpOptions(HttpOptions.builder().apiVersion("v1"))
  .build();

To set the API version to v1alpha for the Gemini Developer API:

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

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

HttpOptions

Besides apiVersion, HttpOptions also allows for flexible customization of HTTP request parameters such as baseUrl, headers, and timeout:

HttpOptions httpOptions = HttpOptions.builder()
  .baseUrl("your-own-endpoint.com")
  .headers(ImmutableMap.of("key", "value"))
  .timeout(600)
  .build();

Beyond client-level configuration, HttpOptions can also be set on a per-request basis, providing maximum flexibility for diverse API call settings. See this example for more details.

ClientOptions

ClientOptions enables you to customize the behavior of the HTTP client. It currently supports configuring the connection pool via maxConnections (total maximum connections) and maxConnectionsPerHost (maximum connections to a single host).

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

Client client = Client.builder()
  .apiKey("your-api-key")
  .clientOptions(ClientOptions.builder().maxConnections(64).maxConnectionsPerHost(16))
  .build();

Interact with models

The Gen AI Java SDK allows you to access the service programmatically. The following code snippets are some basic usages of model inferencing.

Generate Content

Use generateContent method for the most basic text generation.

with text input

package <your package name>;

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

public class GenerateContentWithTextInput {
  public static void main(String[] args) {
    // Instantiate the client. The client by default uses the Gemini API. It
    //  gets the API key from the environment variable `GOOGLE_API_KEY`.
    Client client = new Client();

    GenerateContentResponse response =
        client.models.generateContent("gemini-2.0-flash-001", "What is your name?", null);

    // Gets the text string from the response by the quick accessor method `text()`.
    System.out.println("Unary response: " + response.text());
  }
}

with text and image input

package <your package name>;

import com.google.common.collect.ImmutableList;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;

public class GenerateContentWithImageInput {
  public static void main(String[] args) {
    // Instantiate the client using Vertex API. The client gets the project and
    // location from the environment variables `GOOGLE_CLOUD_PROJECT` and
    // `GOOGLE_CLOUD_LOCATION`.
    Client client = Client.builder().vertexAI(true).build();

    // Construct a multimodal content with quick constructors
    Content content =
        Content.fromParts(
            Part.fromText("describe the image"),
            Part.fromUri("gs://path/to/image.jpg", "image/jpeg"));

    GenerateContentResponse response =
        client.models.generateContent("gemini-2.0-flash-001", content, null);

    System.out.println("Response: " + response.text());
  }
}

Automatic function calling with generate content

The Models.generateContent methods supports automatic function calling (AFC). If the user passes in a list of public static method in the tool list of the GenerateContentConfig, by default AFC will be enabled with maximum remote calls to be 10 times. Follow the following steps to experience this feature.

Step 1: enable the compiler to parse parameter name of your methods. In your pom.xml, include the following compiler configuration.

<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>

Step 2: see the following code example to use AFC, pay special attention to the code line where the java.lang.reflect.Method instance was extracted.

import com.google.common.collect.ImmutableList;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Tool;
import java.lang.reflect.Method;

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

  public static void main(String[] args) throws NoSuchMethodException {
    Client client = new Client();

    Method method =
        GenerateContentWithFunctionCall.class.getMethod(
            "getCurrentWeather", String.class, String.class);

    GenerateContentConfig config =
        GenerateContentConfig.builder()
            .tools(
                ImmutableList.of(
                    Tool.builder().functions(ImmutableList.of(method)).build()))
            .build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-2.0-flash-001",
            "What is the weather in Vancouver?",
            config);

    System.out.println("The response is: " + response.text());
    System.out.println(
        "The automatic function calling history is: "
            + response.automaticFunctionCallingHistory().get());
  }
}

Stream Generated Content

To get a streamed response, you can use the generateContentStream method:

package <your package name>;

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

public class StreamGeneration {
  public static void main(String[] args) {
    // Instantiate the client using Vertex API. The client gets the project and location from the
    // environment variables `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`.
    Client client = Client.builder().vertexAI(true).build();

    ResponseStream<GenerateContentResponse> responseStream =
        client.models.generateContentStream(
            "gemini-2.0-flash-001", "Tell me a story in 300 words.", null);

    System.out.println("Streaming response: ");
    for (GenerateContentResponse res : responseStream) {
      System.out.print(res.text());
    }

    // To save resources and avoid connection leaks, it is recommended to close the response
    // stream after consumption (or using try block to get the response stream).
    responseStream.close();
  }
}

Async Generate Content

To get a response asynchronously, you can use the generateContent method from the client.async.models namespace.

package <your package name>;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;
import java.util.concurrent.CompletableFuture;

public class GenerateContentAsync {
  public static void main(String[] args) {
    // Instantiates the client using Gemini API, and sets the API key in the builder.
    Client client = Client.builder().apiKey("your-api-key").build();

    CompletableFuture<GenerateContentResponse> responseFuture =
        client.async.models.generateContent(
            "gemini-2.0-flash-001", "Introduce Google AI Studio.", null);

    responseFuture
        .thenAccept(
            response -> {
              System.out.println("Async response: " + response.text());
            })
        .join();
  }
}

Generate Content with extra configs

To set configurations like System Instructions and Safety Settings, you can pass a GenerateContentConfig to the GenerateContent method.

package <your package name>;

import com.google.common.collect.ImmutableList;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HarmBlockThreshold;
import com.google.genai.types.HarmCategory;
import com.google.genai.types.Part;
import com.google.genai.types.SafetySetting;
import com.google.genai.types.Tool;

public class GenerateContentWithConfigs {
  public static void main(String[] args) {
    Client client = new Client();

    // Sets the safety settings in the config.
    ImmutableList<SafetySetting> safetySettings =
        ImmutableList.of(
            SafetySetting.builder()
                .category(HarmCategory.Known.HARM_CATEGORY_HATE_SPEECH)
                .threshold(HarmBlockThreshold.Known.BLOCK_ONLY_HIGH)
                .build(),
            SafetySetting.builder()
                .category(HarmCategory.Known.HARM_CATEGORY_DANGEROUS_CONTENT)
                .threshold(HarmBlockThreshold.Known.BLOCK_LOW_AND_ABOVE)
                .build());

    // Sets the system instruction in the config.
    Content systemInstruction = Content.fromParts(Part.fromText("You are a history teacher."));

    // Sets the Google Search tool in the config.
    Tool googleSearchTool = Tool.builder().googleSearch(GoogleSearch.builder().build()).build();

    GenerateContentConfig config =
        GenerateContentConfig.builder()
            .candidateCount(1)
            .maxOutputTokens(1024)
            .safetySettings(safetySettings)
            .systemInstruction(systemInstruction)
            .tools(ImmutableList.of(googleSearchTool))
            .build();

    GenerateContentResponse response =
        client.models.generateContent("gemini-2.0-flash-001", "Tell me the history of LLM", config);

    System.out.println("Response: " + response.text());
  }
}

Generate Content with JSON response schema

To get a response in JSON by passing in a response schema to the GenerateContent API.

package <your package name>;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;

public class GenerateContentWithSchema {
  public static void main(String[] args) {
    Client client = new Client();

    ImmutableMap<String, Object> schema = ImmutableMap.of(
        "type", "object",
        "properties", ImmutableMap.of(
            "recipe_name", ImmutableMap.of("type", "string"),
            "ingredients", ImmutableMap.of(
                "type", "array",
                "items", ImmutableMap.of("type", "string")
            )
        ),
        "required", ImmutableList.of("recipe_name", "ingredients")
    );

    GenerateContentConfig config =
        GenerateContentConfig.builder()
            .responseMimeType("application/json")
            .candidateCount(1)
            .responseSchema(schema)
            .build();

    GenerateContentResponse response =
        client.models.generateContent("gemini-2.0-flash-001", "Tell me your name", config);

    System.out.println("Response: " + response.text());
  }
}

Versioning

This library follows Semantic Versioning.

Contribute to this library

The Google Gen AI Java SDK will accept contributions in the future.

License

Apache 2.0 - See LICENSE for more information.